Web-component viewer planned changes

This directory contains complete follow-on changes and evidence-gated proposal-only drafts for the Causeway web-component viewer programme. They are held outside openspec/changes/ because the repository permits only one active OpenSpec change at a time. The foundation, domain-component, rich GraphQL correctness, value-semantics, collection-windowing, application-entry, composite-object, menubar, generic HTMX, theming, Vaadin evaluation, and Vaadin reference-widget pilot changes are archived. The Reference Application regression suite and input-value hardening changes are archived. The action-dispatch correctness change is archived, completing the remaining Priority 0 correction identified by that broad capability inventory. The versionless-identity and preparation correction is archived. The union-projection correction is archived. The opaque-route correction is archived. The archived add-paged-graphql-reference-autocomplete change adds honest bounded server response windows, and the archived expand-vaadin-semantic-editor-families change qualifies the broader editor families before the default-policy flip in vaadin-default-roadmap.md. The archived make-vaadin-default-for-webcomponent-viewer change completes the policy-focused Vaadin-editor-default sequence while retaining explicit native rollback. The archived extend-vaadin-to-domain-member-presentation, use-vaadin-grid-for-collection-presentation, and use-vaadin-menu-bar-for-application-menus changes extend that internal toolkit to read-only fields and buttons, collections, and horizontal application navigation in independently reviewable tranches. Their order, shared boundaries, and promotion gates are recorded in vaadin-presentation-roadmap.md. The proposal-only analyze-configurable-vertical-application-menus draft evaluates left-side vertical application navigation without changing the accepted horizontal Menu Bar implementation. The older Vue and Svelte drafts are aligned with the declarative context-boundary contract, and a parallel Angular draft joins the metadata, diagnostics, performance-analysis, catalogue, and designer drafts queued for separate review. Proposal-only security drafts separate local SecMan authentication for the HTMX viewer, subsequent OAuth/OIDC support, eventual promotion of the proven bridge into shared Causeway security, future CSRF-safe Wicket and HTMX coexistence, and stable SecMan delegated-user identity mapping.

Complete child directories contain .openspec.yaml, proposal.md, design.md, tasks.md, and delta specifications and can be promoted verbatim after review. Proposal-only directories contain only proposal.md; they require current evidence, full artifact generation, and strict validation before promotion. After the active change is archived, promote an applicable complete draft with:

git mv openspec/planned-changes/web-component-viewer/<name> openspec/changes/<name>
openspec validate <name> --strict

The OpenSpec CLI does not scan this planned-change directory, so drafts must be strictly validated after promotion and before implementation. Review each draft against discoveries made by preceding changes and update stale assumptions before promotion. Do not promote the proposal-only Vaadin-default follow-ons out of the order and gates recorded in vaadin-default-roadmap.md. Matrix entry references point to viewers/graphql/adoc/modules/ROOT/examples/referenceapp-analysis/coverage-matrix.yaml and provide the scope gate for evidence-derived drafts.

Evidence-backed promotion order

The two P0 changes correct successful-looking or unsafe established contracts and precede additive capabilities. The P1 GraphQL changes are independent bounded capabilities after their stated prerequisites, but the single-active-change rule requires serial promotion. The four generic viewers are higher priority than the catalogue workbench and page-designer analysis. HTMX is the first reference router implementation, while Vue, Svelte, and Angular remain sibling production viewers rather than samples or wrappers. The narrow member-metadata, diagnostics, collection-query-pushdown analysis, and parallel-execution analysis are useful but do not block the generic viewer routers unless implementation evidence reveals a new hard dependency. The two performance analyses must preserve the existing semantic contracts and produce separate implementation proposals rather than changing production behavior directly. No production semantic page-designer proposal will be drafted until its analysis selects an authoring model and artifact contract.

Shared generic-viewer routing contract

The four generic viewers preserve one architectural boundary:

canonical bookmark or application entry
                 |
                 v
       host framework router
       +---------------------+
       |                     |
exact logical-type page   no registration
       |                     |
       v                     v
framework custom page   generic route page
                             |
                             v
                    <cw-object>

• Routing and exact-logical-type page selection belong to the host viewer.
• <cw-object> remains a pure effective-grid or fallback object renderer and never discovers custom pages.
• Application-authored shell templates declare one stable <cw-graphql-client> rather than receiving a provider manufactured by the host adapter.
• Application-authored custom and generic page templates declare their route-level <cw-object-context> rather than receiving a context manufactured by the host adapter.
• Routers bind endpoint and canonical route identity to those declared elements and own deterministic replacement or reuse.
• <cw-menubars> remains beneath the shared client in a stable shell outside changing object pages.
• Semantic object navigation, home entries, and interaction results flow into replaceable viewer policy.
• HTMX uses server routes and HTML fragments.
• Vue uses Vue Router and registered Vue components or async components.
• Svelte uses SvelteKit routes and registered Svelte components or lazy loaders.
• Angular uses Angular Router and registered standalone components or lazy loadComponent routes.
• Canonical bookmark meaning and custom-before-generic precedence remain compatible across viewers.
• Framework-specific lifecycle, history, hydration, and rendering remain internal to each viewer.

No framework-neutral page provider is introduced inside the semantic component library.

Minimum generic-viewer prerequisite set

Before any generic viewer can be promoted, the programme must have:

• correct public object identity, polymorphic output, action argument conversion, and authoritative property mutation;
• valid and policy-separated same-origin structural and value resource links;
• accepted reversible value semantics for the reference-derived input set used by default pages;
• bounded collection windows for generic collection pages;
• application entry points for the effective menu resource and configured home-page object;
• completed <cw-object> and <cw-menubars> semantic components;
• stable semantic navigation and result events from the archived component interactions.

The generic viewers do not require the later designer, catalogue workbench, or a page-provider abstraction.

Page-authoring sequence

The catalogue and designer work are intentionally later:

generic HTMX, Vue, Svelte, and Angular viewers
                 |
                 v
 component catalogue and workbench
                 |
                 v
 semantic page-designer analysis
                 |
                 v
 separately reviewed implementation proposals, if justified

The catalogue publishes machine-readable element contracts and an interactive developer workbench. The designer analysis evaluates GrapesJS, a purpose-built semantic tree, and another viable approach before selecting direct HTML, an intermediate model, or a constrained hybrid. Any generated custom page uses ordinary HTML and public Causeway elements and registers at the host router. It does not replace Causeway grid XML or make <cw-object> aware of custom pages.

Programme constraints

• The rich GraphQL schema and standard GraphQL introspection are the application protocol.
• Generated rich-schema naming rules are accepted public client grammar rather than accidental implementation details.
• Components expose semantic Causeway APIs and do not expose GraphQL document construction to page composers.
• HTMX, Vue, Svelte, and Angular remain host viewer technologies; the component library remains framework-neutral.
• Each host binds values into application-authored <cw-graphql-client> and <cw-object-context> elements and does not manufacture those semantic boundaries.
• The programme does not add duplicate member-list, datatype-catalogue, grid, or menu metadata APIs.
• Effective grid and menu resources remain canonical structural sources.
• Rich-schema extensions are proposed only when executable evidence and a concrete semantic client requirement demonstrate missing behavior.
• Unsupported input values never silently promise reversible generic-string behavior.
• Passwords, hidden values, authorization rules, and sensitive resource content remain outside metadata, diagnostics, errors, fallback serialization, workbench fixtures, and designer artifacts.