Files
HiveGrid-Wireframes/hivegrid-cloud/docs/ui-inventory/hot-swap-status.md
T

66 lines
4.4 KiB
Markdown

# 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
```