4.4 KiB
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-subframeis 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 inapps/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.jsondepends on@toolctrl/ui-app,@toolctrl/ui-mock,@toolctrl/foundation,@toolctrl/view-models.apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.tsxbridges the descriptor shape from@toolctrl/ui-mockto RR7 JSX usingcreateShellRegistries()from@toolctrl/ui-app.apps/web/app/routes/hot-swap-demo.tsxrenderscreateHotSwapDrillPage()through the renderer. The route is gated toNODE_ENV !== "production"so production surface area is unchanged.apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.test.tsxasserts 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-modelsinto 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-subframebecomes a non-empty bridge. - A second consumer app (admin shell, partner portal) needs to share
apps/webcomponents 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
- ✓ Add
@toolctrl/ui-app,@toolctrl/ui-mock,@toolctrl/foundation,@toolctrl/view-modelstoapps/web/package.jsondependencies. — done. - ✓ Pick one low-risk route and refactor it to consume from
@toolctrl/ui-app's page registry. — done atapps/web/app/routes/hot-swap-demo.tsx, dev-only. - ☐ Add
@toolctrl/ui-subframetoapps/web/package.jsononce it becomes a non-empty bridge. - ☐ Promote the mock fixture in
packages/ui-mock/src/index.ts(createHotSwapDrillPage) to a non-mock descriptor source once a design tool is wired. - ☐ Refactor a second real consumer surface (admin shell or tenant dashboard) through the renderer to prove cross-surface reuse.
- ☐ Update
docs/ui-inventory/surface-map.mdto claim the new surfaces as hot-swappable.
Related verification
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