# UI Hot-Swap Status ## What's wired The boilerplate ships three UI adapter packages under `packages/`: | Package | Purpose | Current state | | --- | --- | --- | | `@toolctrl/ui-app` | App-shell registries (sidebar, breadcrumb, mobile shell, portals) | Skeleton + registry types, no concrete component bindings. | | `@toolctrl/ui-subframe` | Subframe (design-tool) component placeholder bridge | Placeholder factory only — `createSubframePlaceholder()` returns `{ status: "empty" }`. | | `@toolctrl/ui-mock` | Fixture-driven mock surface for visual/hot-swap testing | Has `createHotSwapDrillPage()` and is consumed by `scripts/verify-ui-hot-swap.ts`. | `packages/foundation` and `packages/view-models` provide the contract these adapters compose against. ## What is NOT wired - `@toolctrl/ui-subframe` is still a placeholder bridge — no real design-source binding. - Outside the activation reference route (see below), `apps/web/app/routes/**` does not render through any `@toolctrl/ui-*` registry — concrete components still live in `apps/web/app/components/`. - The majority of consumer surfaces (admin shell, tenant dashboard, marketing) have not been refactored to consume from `@toolctrl/ui-app`'s page registry. ## What IS wired (activation reference) A minimal hot-swap activation now lives in `apps/web`: - `apps/web/package.json` depends on `@toolctrl/ui-app`, `@toolctrl/ui-mock`, `@toolctrl/foundation`, `@toolctrl/view-models`. - `apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.tsx` bridges the descriptor shape from `@toolctrl/ui-mock` to RR7 JSX using `createShellRegistries()` from `@toolctrl/ui-app`. - `apps/web/app/routes/hot-swap-demo.tsx` renders `createHotSwapDrillPage()` through the renderer. The route is gated to `NODE_ENV !== "production"` so production surface area is unchanged. - `apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.test.tsx` asserts the descriptor → DOM mapping (sidebar, breadcrumbs, header, cards, activity). This is the first activation milestone: the registry path is alive end-to-end against a real consumer route, but is still fixture-driven (no Subframe binding yet). ## Why this is intentional (Settings API Onboarding-era) The adapter packages were introduced in the Phase-C boundary work to lock down what a **whitelabel-friendly** UI swap can look like without forcing a big-bang component rewrite. Boundaries are enforced by `scripts/verify-phase-c-boundaries.mjs` so any future activation cannot accidentally cross a runtime line. Until an activation milestone explicitly enables Subframe (or another design source), the registries stay as a structural placeholder. The cost of registering them in `apps/web` without a real binding would be: - pulling `@toolctrl/foundation` + `@toolctrl/view-models` into the web bundle for no consumer, - adding registry warm-up code paths to SSR + hot-swap tests with no real fixture to exercise, - noise in the hot-swap verifier (`verify:ui-hot-swap`) that would have to allowlist “empty registry” permanently. ## When to activate Activate the hot-swap path when **at least one** is true: - A real Subframe/Figma source is being integrated and `ui-subframe` becomes a non-empty bridge. - A second consumer app (admin shell, partner portal) needs to share `apps/web` components through a registry instead of importing relative paths. - A whitelabel deployment needs to swap the dashboard surface per-tenant without forking the codebase. ## Activation checklist 1. ✓ Add `@toolctrl/ui-app`, `@toolctrl/ui-mock`, `@toolctrl/foundation`, `@toolctrl/view-models` to `apps/web/package.json` `dependencies`. — done. 2. ✓ Pick one low-risk route and refactor it to consume from `@toolctrl/ui-app`'s page registry. — done at `apps/web/app/routes/hot-swap-demo.tsx`, dev-only. 3. ☐ Add `@toolctrl/ui-subframe` to `apps/web/package.json` once it becomes a non-empty bridge. 4. ☐ Promote the mock fixture in `packages/ui-mock/src/index.ts` (`createHotSwapDrillPage`) to a non-mock descriptor source once a design tool is wired. 5. ☐ Refactor a second real consumer surface (admin shell or tenant dashboard) through the renderer to prove cross-surface reuse. 6. ☐ Update `docs/ui-inventory/surface-map.md` to claim the new surfaces as hot-swappable. ## Related verification ```sh pnpm run verify:phase-c-boundaries # boundaries that future activation must not cross pnpm run verify:ui-visual # current mock visual baseline pnpm run test:hot-swap # mock-driven hot-swap drill ```