# Nexamas UI Showcase Runtime Contract

Current route after Phase 15 Legacy / Dead Path Cleanup (2026-06-22):

- The Showcase startup shell uses one `MASApplicationWindow` and `MASApplicationWindow.Pages` as the official same-window route.
- `ShowcaseNavigationCatalog` is metadata-only: page id, title, summary, category, and command id.
- `ShowcasePageHostContentBuilder` owns every active PageHost body and consumes only public Nexamas.UI controls, public application/layout verbs, and narrow Nexamas.UI-owned host gateways.
- The Showcase no longer compiles the old Form-per-page sample files, the old local `ProductShowcaseSystem` window host, or the old `ShowcasePresentationPageBuilder` page skeleton.
- Historical markdown reports remain for lineage, but current runtime ownership is defined by this README, the active PageHost files, `SHOWCASE_COVERAGE_GATE_2026_06_22.md`, and `SHOWCASE_PHASE15_LEGACY_DEAD_PATH_CLEANUP_2026_06_22.md`.

## Active files

- `NexamasUIShowcase.vb` — thin launcher state and constructor only.
- `TestForms/Shell/NexamasUIShowcase.Navigation.vb` — MAS shell route, TopBar commands, direct PageHost registration for Home, guided journeys, area overviews, and capability pages; the standalone Catalog route is intentionally removed.
- `TestForms/Pages/Home` and `Pages/Areas` — compact Overview and area overviews as consumer composition. Searchable capability metadata is absorbed into the DataGrid guided journey instead of a standalone Catalog page.
- `TestForms/Composition` — Showcase-only composition helpers that assemble Nexamas.UI controls; no custom controls, renderers, layout engines, or theme engines.
- `TestForms/NexamasUIShowcaseWindowBase.vb` — shared host lifetime, theme menu, close-safe cleanup, input activation, and Nexamas UI dialog error route.
- `TestForms/ShowcaseNavigationCatalog.vb` plus `TestForms/Data/ShowcaseNavigationCatalog.*.vb` — metadata-only single source of truth for categories, page ids, command ids, presentation lanes, search, and guided tour order.
- `TestForms/ShowcasePageHostContentBuilder.vb` plus `TestForms/Pages/*/ShowcasePageHostContentBuilder.*.vb` — active capability bodies that consume public Nexamas.UI controls and public application/layout verbs.
- `TestForms/ShowcaseConsumerContentContract.vb` — host-window sizing only.

## Active PageHost coverage

The active PageHost covers:

- Certification Center through a consumer-safe commercial summary page; Showcase does not call Friend/internal certification hosts.
- Application Architecture through public PageHost/ApplicationPage/layout builder routes plus AppLayout and SplitView visual workspace surfaces.
- Workflow Foundations through public ActionGroup, input, validation-visual, FormValidationSummary, and service routes.
- Commercial Foundations as Report / Print and Plugin / Module capability decisions without opening public runtime hosts.
- Localization / RTL through `MASLocalizationRtl.AttachPage(window, page)`.
- Theme / Readability Preview through `Window.Theme` only; Theme Studio internals are not a Showcase API surface.
- Core Documentation Map, Licensing / Evaluation, and Packaging / Consumer Proof pages so the Showcase mirrors the Phase 7 documentation set.
- Surface Materials through public surface-material gateways.
- DataGrid / DataView with Advanced SearchBox binding.
- Data Analytics through MetricCard, DashboardGrid, FilterBuilder, AppliedFiltersBar, TreeGrid, and PivotTable public control routes.
- Chart Dashboard through `Window.Controls.AddChart(...)`.
- PropertyGrid / Inspector through `Window.Controls.AddPropertyGrid(...)`.
- Motion through public motion consumers.
- Render Verification through `MASRenderVerification.AttachDashboard(window, page)`.
- Diagnostics Dashboard through a consumer-safe commercial summary while diagnostics internals remain Nexamas.UI-owned.
- Virtualization through public heavy controls and large item counts.
- Services through `Window.Services`.
- Buttons, Inputs, Selection, Lists / Tree, Tiles, Visual editors, File surfaces, and Settings / Sizing through public Window.Controls and application services.

## Product Hub presentation rules

- The first impression is compact `Overview`, not a second catalog made of dozens of cards and buttons.
- The fixed left PageHost index is hidden to preserve workspace width; direct capability routes remain registered in `MASApplicationWindow.Pages`, but the shell-owned full-width `MASMenuBar` now exposes only Start, focused guided Journeys, and compact Area overviews. Capability discovery is Wizard-first.
- Home and Area pages are orientation surfaces only: short narrative and curated live previews. They must not add broad route-opening shortcut hubs.
- The former Catalog quick-search surface is no longer a standalone route. Its metadata grid is absorbed into the DataGrid journey as a capability discovery matrix, without route-opening buttons.
- Product pages open directly as full PageHost pages and lead with their real Nexamas.UI controls/proof content before optional collapsed developer metadata.
- Capability route order is body-first: shared menu, route summary, `ShowcasePageHostContentBuilder.Build(...)`, a collapsed `BuildCapabilityContextWorkspace(...)` developer metadata expander, a collapsed consumer-boundary note plus Previous / Area / Next, and then the bottom `MASBreadcrumb` route trail. Catalog, Related, and duplicate shortcut access stay out of the footer.
- All active routes use the shared `ApplyShowcaseWorkspaceSurface(page)` consumer composition contract so Home, Area, and Capability bodies share one full-width spacing policy instead of page-local dashboard max-width presets. Route summaries are rendered by `BuildShowcaseRouteSummary(...)` inside the same body layout as the rest of the page copy; the PageHost description slot stays empty to avoid a second text gutter.
- Showcase must not add controls, renderers, layout engines, theme engines, card systems, command-palette routers, duplicated shortcut groups, or a competing navigation framework.

## Runtime rules

- Do not add Form-per-page navigation.
- Do not add a second navigation registry.
- Do not add local ProductShowcase windows.
- Do not import Friend-only Nexamas.UI systems into Showcase.
- Do not create native WinForms dialogs, wrappers, adapters, bridges, or parallel service/layout/render/certification/diagnostics/localization hosts.
- Heavy scrollable content must use Nexamas.UI controls that own scrolling, such as `MASDataGrid`, `MASListView`, `MASTreeView`, `MASTileBox`, and `MASFileExplorerView`.

## Gate chain

Run the Showcase gates from this project root:

```powershell
.\eng\tests\Invoke-NexamasUIShowcaseProductHubGate.ps1
.\eng\tests\Invoke-NexamasUIShowcaseCoverageGate.ps1
.\eng\tests\Invoke-NexamasUIShowcaseDocumentationAlignmentGate.ps1
.\eng\tests\Run-NexamasUIShowcaseConsumerAudit.ps1
```

Then run the Nexamas.UI gates required by the current phase from the Nexamas.UI project root.

## Guided tour and capability discovery rules

- Product journey metadata still lives in `ShowcaseNavigationCatalog.Journeys.vb`, and `Tours.vb` delegates the Executive tour to the `executive` journey so there is one source of truth for catalog/tour membership. The shell `Journeys` menu now exposes the five focused exploration lanes: controls, systems, data workspaces, theme/RTL, and quality proof.
- Focused Journeys open the `MASApplicationWindow.Pages` guided exploration route first. That route uses the official `MASWizard` as the visible focus target and shows one live work area for the current step. It intentionally does not show an `Open detailed page` escape action inside the journey; broader capability pages remain registered for internal proof, footer navigation, and regression comparison, but they are not duplicated as primary MASMenuBar entries. It does not create Form-per-page navigation, a second shell, or another router.
- Wizard step clicks and Previous / Next share the same guided journey state; the live stage is rebuilt through `BuildGuidedJourneyLiveStage(...) -> BuildSharedScenario(...)`. Focused steps use registry-owned `BuildGuidedStage...(...)` builders, while canonical steps reuse the documentation-backed direct route builder. A step context banner and current-step live work area title make the interaction target explicit after every step change.
- Guided journey step transitions use official PageHost navigation re-entry instead of `Window.Pages.Refresh()`, because PageHost caches page builders and repaint-only refresh does not rebuild the current route.
- Catalog search is metadata-only and lives in `ShowcaseNavigationCatalog.Search.vb`.
- Search results are rendered with Nexamas.UI `MASDataGrid`; Showcase does not create a custom overlay, router, or search UI framework.
- `MASSearchTextBox` owns the input behavior, suggestions, recent searches, filter tokens, and commit event.
- Search results may still resolve catalog metadata, but primary user-facing discovery is the focused Wizard journey rather than a second capability-page menu tree.

## Navigation deduplication rules

- The shell-owned full-width `MASMenuBar` is intentionally limited to Start, Journeys, and compact Area overviews.
- `Quick Access`, `Current`, `Related`, `Tour`, and `Proof` must not return as separate global menu groups.
- Home does not host a route-opening `MASCommandPalette`; the DataGrid journey owns searchable capability metadata without reopening a broad page tree.
- Area pages stay preview-only and do not add broad open buttons.
- Capability footers keep only Previous / Area / Next.
- Bottom breadcrumbs do not re-open the current page segment.
- `SHOWCASE_NAVIGATION_DEDUPLICATION_LOCKDOWN_2026_07_08.md` is the active record for this cleanup.


## Phase 8 gate-alignment rules

- `Invoke-NexamasUIShowcaseProductHubGate.ps1` protects the Product Hub structure after the split shell refactor.
- The existing coverage and consumer audit gates now read split partial files instead of assuming the shell, catalog, and PageHost content live in single large files.
- The Product Hub gate fails if a physical `.vb` file is missing from the project, if a `<Compile Include>` points to a missing file, or if non-designer source grows back above 1000 lines.
- The Product Hub gate fails if Showcase introduces folders or source patterns that imply a parallel UI framework, renderer, layout engine, theme engine, local Form-per-page launcher, command palette router, or tour page system.
- Nexamas.UI remains unchanged by this phase; the gate alignment only keeps the Showcase consumer boundary verifiable.

## Phase 10 balanced PageHost restore rules

- Phase 10 intentionally rolls back the over-expanded card/button/evidence-lane presentation while preserving the useful file split and metadata catalog.
- Direct capability pages remain registered as real MAS PageHost pages, but primary discovery now happens through the Wizard journeys. The shell-owned full-width MASMenuBar exposes only launch points and compact Area overviews so the workspace avoids a second page tree.
- Removed detail-route and evidence-lane source files must not remain as dead project paths.
- Nexamas.UI remains unchanged by this phase.

## Phase 11 strong consumer rebalance rules

- The fixed left PageHost index is intentionally hidden with `WithNavigationVisible(False)`; navigation remains Nexamas.UI-owned through `MASApplicationWindow.Pages`, `MASMenuBar`, and metadata-backed route commands rather than a Showcase list widget.
- A shared shell-owned full-width `MASMenuBar` is attached once below the TopBar through `Window.Controls.AddMenuBar(...)`. It is not placed inside Home, Area, Catalog, or Capability PageHost content. It routes only to existing `MASApplicationWindow.Pages` registrations, is now limited to global discovery groups and does not introduce native WinForms menus, a second router, current/related shortcut groups, proof/tour shortcut groups, or a command-palette overlay.
- The Overview is now a focused journey launchpad instead of an explanatory DataGrid page or two separate wizard areas: it keeps the pure-consumer message at the top, offers start buttons for Controls, Systems, Data, Theme/RTL, and Proof, then the guided route uses the same Wizard plus Previous/Next/Back controls for every journey. The journey no longer offers per-step detail escape buttons; the DataGrid family is shown with a `MASSearchTextBox` companion so the table is experienced as a practical work surface rather than a silent table.
- Systems/productivity routes now follow the same body-first rule: Services and Motion lead with live buttons, status changes, floating surfaces, timelines, and operation feedback; developer service maps, motion boundary notes, and productivity coverage matrices are collapsed behind `MASExpander` so the user sees the system behavior first. Controls pages now follow that rule too: Inputs, Feedback / Status, and File surfaces show their live families before collapsed developer input/feedback/file boundary notes. Data and business pages now follow the rule as well: Planning, Data Analytics, Chart Dashboard, Productivity Navigation, and PropertyGrid/MasterDetail lead with live surfaces, while developer route, boundary, and ownership notes are collapsed behind `MASExpander`. Theme / RTL, Surface Materials, Output, Diagnostics, and Quality/Foundation proof pages now use the same product-first discipline: live theme/material/output actions and proof matrices appear first, while catalog, boundary, diagnostics, packaging, licensing, documentation, and certification explanatory cards are collapsed behind `MASExpander`.
- Area previews may use richer Nexamas.UI controls, but they must remain previews. They must not duplicate every capability as cards/buttons and must not hide the direct strong capability pages.
- The Showcase still owns only metadata, copy, sample values, route choices, and composition. Nexamas.UI continues to own controls, layout, rendering, theme, RTL, menu popups, floating UI, output, and proof engines.

## Phase 12 final consumer-purity audit rules

- The shared shell-owned MASMenuBar must be metadata-backed and deduplicated. It must not add separate Tour, Proof, Current, Related, Quick Access, or per-capability category groups; capability discovery is handled by focused Journeys, compact Area overviews, and DataGrid-backed metadata search inside the Data journey.
- The per-capability footer is a consumer-boundary footer only. It may explain that Showcase owns metadata/copy/demo data, but it must not become an evidence lane, detail route, proof engine, or duplicate navigation surface.
- `ShowcasePageHostContentBuilder.ConsumerBoundaryFooter.vb` replaces the old detail-presentation naming so the active file names match the restored direct PageHost architecture.

## Phase 13 workspace-first navigation rebalance rules

- TopBar menu is reserved for global environment controls: theme, surface material, runtime density/size, reset, about, and window commands.
- Shell-owned full-width MASMenuBar below the TopBar owns only global launch points: Start, Journeys, and Area overviews. Capability pages are Wizard-covered and are not repeated as menu entries.
- The fixed left navigation tree remains hidden so DataGrid, dashboards, SplitView, RTL previews, and large dataset pages receive the full application width.
- Showcase still registers every capability as a direct `MASApplicationWindow.Pages` route; it only changes how the user discovers those routes.
- Nexamas.UI was not modified for this rebalance; Showcase consumes existing `WithNavigationVisible(False)`, `MASMenuBar`, `MASApplicationSurfaceMaterialGateway`, and `Window.Sizing` APIs.

## Phase 16 quick-access command palette rules

- Superseded by the navigation deduplication lockdown: Home no longer hosts `MASCommandPalette` as a route-discovery surface; the DataGrid journey owns searchable capability metadata.
- Quick Access commands are superseded by Wizard-first discovery; existing direct capability routes remain registered but are no longer exposed as primary menu shortcuts.
- Quick Access must not create a second router, command registry, keyboard hook, popup service, or WinForms navigation fallback.
- The available navigation model is now: shell-owned full-width `MASMenuBar` with Start/Journeys/Areas only, focused PageHost Journeys, DataGrid-backed capability discovery inside the Data journey, bottom route trail, and a small Previous / Area / Next footer sequence.
- Nexamas.UI remains unchanged; the Showcase consumes the official `Window.Controls.AddCommandPalette(...)` gateway.

## Phase 17 contextual workspace rules

- Home intentionally does **not** include repeated explanatory DataGrid maps. Product exploration is handled by one live family-based Journey Host; proof/documentation is a selectable journey inside the same host, not a second visible wizard.
- Area pages include compact previews and remain curated entry surfaces. They must not recreate the old left catalog.
- Capability pages show the real page body first. Developer route metadata and consumer-boundary notes are collapsed behind `MASExpander`; the shared route breadcrumb is appended as the bottom route trail.
- Journey membership is metadata-only in `ShowcaseNavigationCatalog.JourneyMembership.vb`; it must not become a router or side navigation system.
- Context workspace is metadata-only; it does not own route actions.


## Phase 18 — Breadcrumb Path Trail

The contextual workspace now uses the official `MASBreadcrumb` component for Home, Area, and Capability route orientation. Breadcrumb segments are metadata-only route hints wired to the existing `MASApplicationWindow.Pages` routes through `Window.Pages.NavigateTo(...)`. The fixed left ListTree remains hidden, and no Router, NavigationRail, TreeView, or custom path renderer is introduced.

## Phase 19 — Visible Path Trail Placement

The official `MASBreadcrumb` is now placed immediately below the shell-owned full-width `MASMenuBar` and before every page title for Home, Area, and Capability routes. Phase 18 used the right element, but the placement could be missed because it was injected inside contextual content sections. Phase 19 makes the path trail a first-class route-orientation row without reintroducing a left tree, NavigationRail, or custom path renderer.

## Phase 20 — PageHost Breadcrumb Slot

Phase 18 and 19 used the correct `MASBreadcrumb` control but placed it inside page content, which could be visually missed because `MASApplicationWindow.Pages` owns the workspace prelude. Phase 20 moved the breadcrumb slot to Nexamas.UI's PageHost itself through `WithBreadcrumbVisible(True)` and `WithBreadcrumbRootText("Showcase")`.

## Phase 21 — Bottom Route Trail

The commercial wide Showcase now starts each page directly with page content instead of a permanent top route indicator. The PageHost breadcrumb slot is disabled with `WithBreadcrumbVisible(False)`, and a dedicated `NexamasUIShowcase.RouteTrail.vb` partial appends one official `MASBreadcrumb` at the bottom of Home, Area, and Capability pages. Navigation remains routed through existing `MASApplicationWindow.Pages` ids. Showcase does not introduce a router, custom breadcrumb renderer, TreeView, ListTree, NavigationRail replacement, or WinForms fallback.


## Phase 8 documentation-alignment rules

- Every major Phase 7 Core Documentation page has a visible Showcase route: Core Documentation Map, Application Architecture, Controls, Theme / Readability, Surface Materials, DataGrid / DataView, Localization / RTL, Motion, Diagnostics, Packaging / Consumer Proof, and Licensing / Evaluation.
- Showcase copy may explain internal ownership boundaries, but active runtime code must not consume Friend/internal engines, snapshots, catalog internals, renderer internals, native dialogs, or parallel routing/layout/theme systems.
- The seven-day evaluation is documented as a legal/commercial term only. Showcase must not claim automatic runtime expiry, online activation, telemetry metering, or hidden enforcement.
- Packaging proof is shown as maintainer evidence and command guidance; the runtime UI does not pack, restore, or execute gates.

## Phase 5 — Remove detail escape action, stage 1

- The guided route footer now contains only `Previous step`, `Next step`, and `Back to Overview`.
- The per-step `Open detailed page` / `Open <Capability>` button was removed because it weakened the journey by implying that the real content lives outside the guided stage.
- Non-live redirect steps such as `Open system details`, `Open data details`, `Open Theme / RTL details`, and `Open proof details` were removed from the journey definitions.
- Direct capability routes still exist for proof, regression comparison, and footer navigation, but they are no longer discoverable as duplicated primary MASMenuBar entries. The journey itself is now the primary guided experience.
- Follow-up stages will fill the remaining compact/banner-only guided steps with live Nexamas.UI content instead of redirecting the user to another page.

## Phase 5 — Fill journey gaps, stage 2

- Controls journey gaps from the former detail-button policy were moved into the guided route itself for the most visible control families.
- Actions now include subtle intent, dialog-style OK/Cancel/Yes/No/Delete actions, richer MASSplitButton menu behavior, command feedback, and a visible SplitButton status label.
- Text inputs now include field validation messages, neutral helper text, path and multiline inputs, and a compact `MASDataForm` / `MASFormBuilder` summary so the user no longer needs an Inputs detail escape to understand the family.
- Search/filter/value controls now include SearchBox helper messaging, a broader ComboBox, TagInput live status, and Slider live status.
- Date/time now includes a second optional date, range preview, calendar preview, a reminder time input, and live preview labels.
- Feedback now includes danger and dot-only badges, read-only rating, more semantic status banners, and two empty-state variants.
- People/activity now includes AvatarGroup, Timeline, and NotificationPanel status labels plus Mark all read / Clear notifications actions.
- Selection now includes overflow tabs and TransferList status/event feedback inside the journey step.

## Phase 5 — Fill journey gaps, stage 3

- Data workspace journey gaps from the former detail-button policy were moved into the guided route itself.
- DataGrid now includes advanced SearchBox suggestions, recent searches, filter tokens, commit/clear behavior, sorting, inline edit entry, copy-preview, reset, and live row/filter/sort status.
- Dashboard metrics now include the additional blocked/risk metric and selected-widget status.
- FilterBuilder and AppliedFiltersBar now include the third Owner rule plus live rule/chip status feedback.
- TreeGrid and PivotTable now include richer rows, score columns, selection status, and pivot grand-total feedback.
- Charts now render live `MASChart` line/bar surfaces plus `MASChartLegend` inside the journey instead of a banner-only redirect message.
- Planning now includes `MASContentCarousel` with previous/next actions alongside KanbanBoard and AgendaView.
- Inspector now includes `MASPropertyGrid`, `MASMasterDetailView`, EmptyState, editable rows, status labels, and action buttons inside the journey.
- Virtualization now includes a compact `MASListView` consumer matrix, a live large-row list, and load actions inside the journey.

## Phase 5 — Fill journey gaps, stage 4

- Systems journey gaps were moved into the guided route itself. Shell/PageHost, Services, Theme, RTL, Motion, Sizing, and Output now contain live public Nexamas.UI surfaces instead of banner-only explanations.
- Theme/RTL journey gaps were moved into the guided route itself. Readability, surface material, language switching, RTL preview, feedback states, motion feel, forms, and output readiness now have visible controls or proof matrices inside the journey.
- Proof journey gaps were moved into the guided route itself. Documentation alignment, element coverage, render verification, output proof, package proof, certification, diagnostics, and consumer-boundary evidence are now represented by compact live matrices, lists, metrics, timelines, and status surfaces.
- The added `NexamasUIShowcase.GuidedJourneySystemsStages.vb` partial keeps the focused journey stage split by responsibility and below the 1000-line source gate.
- The guided route still exposes only `Previous step`, `Next step`, and `Back to Overview`; direct capability pages remain registered but are no longer duplicated from MASMenuBar or as escape buttons inside each journey step.

## Phase 5 — self-contained guided journey lockdown, stage 5

- The guided route is now guarded as a complete exploration surface, not a teaser for detailed pages.
- `Invoke-NexamasUIShowcaseProductHubGate.ps1` now compares every `GuidedJourneyStep` group key with the shared `BuildSharedScenario(...)` registry.
- Redirect/detail group keys are forbidden inside guided journeys.
- Focused `BuildGuidedStage...(...)` functions are protected so every remaining implementation is registry-owned; canonical journey steps reuse the documentation-backed direct route builder.
- The footer remains `Previous step`, `Next step`, and `Back to Overview` only.
- PageHost cached-page invalidation remains official navigation through `Window.Pages.NavigateTo(...)`; no custom router or Nexamas.UI change is introduced.

## Phase 6 — Catalog route absorption

The standalone Catalog page, Overview catalog button, and `Catalog` MASMenuBar group were removed. The useful Catalog metadata is not lost: the canonical shared DataGrid scenario contains a second read-only `Capability discovery matrix` using `MASSearchTextBox` + `MASDataGrid` over `ShowcaseNavigationCatalog.SearchEntries(...)`. Direct DataGrid navigation and its Wizard step inherit that same matrix without adding another PageHost route or route-opening button.
## Guided journey visual feedback pass

The current guided journey uses label-fit navigation buttons, two-column feedback sample grids, and richer Systems journey evidence matrices for Theme, RTL, Motion, Sizing, and Output. The Showcase keeps this as a consumer composition rule: no Nexamas.UI changes and no hard-coded Showcase widths.
## Guided journey Actions natural-row fix

The first Controls journey step now reuses the canonical Buttons route builder, whose button-intent, dialog-action, SplitButton, and choice-control examples remain in compact MAS layout grids. This prevents the Actions step from regressing into full-width button bands while preserving the semantic sizing rule: action controls hug their labels; real workspace surfaces may fill the stage.


## Phase 6 — Wizard-first menu deduplication

- Every catalog capability route is now represented inside a focused Wizard journey before any menu cleanup.
- The shell-owned full-width `MASMenuBar` no longer repeats all 35 capability routes. It exposes only `Start`, the five focused `Journeys`, and compact `Areas` overview entries.
- Direct capability pages remain registered in `MASApplicationWindow.Pages` as internal proof/regression/fallback surfaces, but they are not primary navigation targets.
- Area overview pages remain orientation surfaces only. They preview each area and must not reintroduce cards, buttons, or menu entries for every capability route.
- Nexamas.UI remains unchanged; this is a Showcase navigation-composition cleanup only.


## Shared scenario and route-matrix gate

- Direct capability routes and guided journey steps now resolve through one active `BuildSharedScenario(...)` registry.
- `BuildSharedRouteScenarios(...)` uses an explicit matrix-pinned composition policy: 30 routes render one canonical full-route scenario, while 5 routes compose all focused Wizard scenarios.
- `eng/showcase-route-conformance-matrix.json` maps all 35 capability routes to classification, documentation, recipe/example, exact public API references, shared scenario keys, direct composition mode/keys, build proof, runtime-proof state, and parallel-code result.
- `lib/Nexamas.UI/Nexamas.UI.documentation-contract.json` pins 103 mapped Nexamas.UI documentation and recipe files by SHA-256.
- `Invoke-NexamasUIShowcaseRouteMatrixGate.ps1` validates 170 API references against the pinned assembly inventory and fails the build when a catalog route, guided scenario, matrix row, documentation mapping, classification, composition policy, or shared dispatch case is missing or inconsistent. It also forbids unreferenced `BuildGuidedStage...` implementations.
- Runtime and DPI proof remain explicitly pending until the later smoke/hardening phases; the matrix must not claim those checks have passed early.

- This pass removed 27 obsolete parallel guided-stage functions and their orphaned helpers; the remaining 18 focused builders are all registry-owned.

## Coverage gaps and classification (2026-07-11)

The Showcase now includes public consumer routes for icon resolution, multi-window/lifetime ownership, and DPI/text/accessibility evidence. Every direct route and guided journey stage displays an explicit Stable/Advanced/Preview/Evidence/Compat classification. Screen Reader/UI Automation remains explicitly **Not claimed** until a documented public Nexamas.UI automation facade exists.


## Runtime route, lifecycle, and DPI smoke (2026-07-11)

- `NexamasUIShowcase.RuntimeSmoke.vb` is an opt-in test mode of the real Showcase executable; normal launches are unchanged.
- The harness drives Home, Guided landing, seven Area routes, 35 capability routes, and 48 guided-step routes through `MASApplicationWindow.Pages.NavigateTo(...)`.
- Every route is exercised at minimum, standard, and expanded host sizes where the display working area permits distinct sizes.
- It checks public geometry, PageHost identity, control count, layout-refresh failures, diagnostics deltas, shared multi-window cleanup, and explicit `IsDisposed` proof for the final host window and shared application.
- `Invoke-NexamasUIShowcaseRuntimeSmoke.ps1` launches the built executable, validates exact 35/48/7 route baselines and unique ids, enforces resize/lifecycle/disposal evidence, and optionally requires Home plus all 35 capability pages as existing PNG evidence.
- DPI is never simulated. Run the harness separately at Windows scales 1, 1.25, and 1.5 with `-ExpectedDpiScale` to create honest 100% / 125% / 150% proof.
- The route matrix remains `BuildMapped` until the Windows runtime reports are actually produced and reviewed.

## Final acceptance workflow (2026-07-11)

The final Showcase closure is deliberately split into real Windows DPI capture and a final acceptance gate. DPI is never simulated. Set Windows Display scaling to the requested value and run one command per scale:

```powershell
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\eng\tests\Run-NexamasUIShowcaseDpiProof.ps1 -ExpectedDpiScale 1
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\eng\tests\Run-NexamasUIShowcaseDpiProof.ps1 -ExpectedDpiScale 1.25
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\eng\tests\Run-NexamasUIShowcaseDpiProof.ps1 -ExpectedDpiScale 1.5
```

Each proof opens all 92 runtime routes, tests minimum/standard/expanded sizes, verifies multi-window and disposal behavior, and captures 36 PNG files. An isolated boundary-only route result may be accepted only through a visible focused-route reconciliation in a fresh process at the same DPI.

After all three scales exist, run:

```powershell
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\eng\tests\Run-NexamasUIShowcaseFinalAcceptance.ps1
```

The final command also enforces commercial truth: sales are not currently open, no purchase/payment/license-delivery route is exposed, the evaluation is not presented as an automatic runtime lockout, and unavailable PDF/Print, plugin loading, Screen Reader, or UI Automation capabilities are not marketed as present.