Declarative UI Architecture Implementation Audit
- Date: 2026-11-13
- Branch:
feat/declarative-ui-architecture-phase0-4 - Base:
3e3a9b5a(migration branch plus main4977e308), latest main merged asd92a2f93(1b1ffbba) - Scope: all 85 plugins, plus
packages/core,packages/integrations/honox,packages/ui,packages/diagram,packages/runtime,packages/spa, themes, and the scaffold - Reference: Declarative UI migration ledger
Verdict
| Phase | Status | Evidence |
|---|---|---|
| Phase 0: presence selectors | PASS | 19 client entries gained selectors; the four global entries are allowlisted; pnpm check:client-entries passes |
| Phase 1: resolved component props | PASS | deferUntilManifest finalizes props after manifest hooks with manifest/diagnostic context; image-compare is a deferred component |
| Phase 2: HAST transforms | PASS | code-tabs renders its tab markup through CodeTabsGroup; the official browser suite exercises the result |
| Phase 3: app placement | PASS | AppSlot exposes head, bodyStart, articleAfter, and app; the website uses bodyStart, and the existing lifecycle keeps one mount per page |
| Phase 4: shared external renderer lifecycle | PASS | Every external renderer now uses renderPendingDiagrams; Mermaid browser coverage passes |
No new fully declarative migration candidate was missed. The migration ledger is now 1 A, 17 B, 15 C, and 52 D: image-compare moved to VERIFIED and code-tabs moved from C to B.
Phase 0
scripts/check_client_entry_presence.mjsparses pluginindex.tsfiles with the TypeScript AST and requires a seventhpresenceSelectorargument.- The only entries without a selector are
analytics,color-mode,text-fragment, andux, which are intentionally global.text-fragmentmust observe selections on every article;color-modeanduxare page-level effects;analyticshas no interactive UI. - The check is available as
pnpm check:client-entries.
Phase 1
PluginMarkdownComponentacceptsresolveProps(props, { sourceSlug, resolveAssetUrl, manifest, diagnostics }).deferUntilManifestemits a base64-encoded deferred marker instead of rendering during the Markdown pass. The encoded props avoid HTML attribute escaping changing the JSON.finalizeDeferredMarkdownComponentsruns after manifest hooks and beforesynchronizeHtml, decodes props, resolves them with the manifest context, and replaces the marker with the rendered component.- Markdown component errors use
renderErrorwhen defined, soimage-comparekeeps its accessible error block andimage-compare-invaliddiagnostics. image-comparenow registers the deferredImageComparecomponent and no longer uses theonManifestCreatedplaceholder replacement. Its pointer/range controller remains.- Core tests cover manifest context, diagnostics, and deferred rendering; image-compare's manifest handling tests pass unchanged.
Phase 2
packages/core/src/plugin_hast_transform.tsregistershastTransformsanddefineHastTransform.- HAST transforms run after the sanitizers and after plugin Rehype plugins, so they can consume generated UI while still receiving sanitized nodes. They have no client entry or hydration.
code-tabsregistersCodeTabsand renders the tablist, panels, ARIA state, and labels throughCodeTabsGroupwith Hono JSX. The Rehype phase only groups the code blocks and provides the data.- The package test builds a manifest with two tabbed fences and checks the rendered structure and code content. The official browser suite checks tab switching and panel visibility.
Phase 3
packages/ui/src/overlay/index.tsxprovidesOverlayHost,findOverlayHost,AppSlot, andfindAppSlot.AppSlotsupportshead,bodyStart,articleAfter, andappnames and an optional semantic element.- The website renderer wraps the text-fragment overlay in the
bodyStartslot. ExistingClientLifecyclebehavior keeps one initializer per page/name/root, and UI tests cover SPA scroll restoration, focus, dialog, and drawer behavior. - The text-fragment client uses the app-owned overlay host and removes only a host it created itself.
Phase 4
packages/diagram/src/client.tscentralizes pending-node discovery,aria-busy, lifecycle state, error handling, cleanup, and fallback opening. It accepts a custom selector and fallback selector.- Migrated renderers:
graphviz,chartjs,mermaid,d2,wavedrom,vega-lite,markmap,map, andexcalibrain. - Renderer-specific behavior such as Mermaid security, Vega finalization, Leaflet cleanup, WaveDrom skins, and Markmap asset loading remains inside each renderer callback.
- The Mermaid browser test covers rendering and SVG sanitization. The diagram tests cover selector handling, cleanup, and failure fallback.
Final re-audit after the main merge
- The repository still contains 85 plugin directories and 32 plugins with
createClientEntry. pnpm check:client-entriespasses, so every non-global client entry is gated.- Main added content-mutation and derived-view changes only; no plugin UI changed.
- The migration ledger now records 1 A, 17 B, 15 C, and 52 D.
image-compareis VERIFIED in B, andcode-tabsmoved from C to B because it renders through a HAST transform. - B records keep declarative markup and browser effects separate.
- No assertions were deleted or weakened. The Mermaid browser expectation now also asserts the shared
data-diagram-status="rendered"state. The Excalidraw browser test covers the public docs embed instead of the intentionally private/assets/HWroute; standalone rendering remains covered by the Excalidraw page tests.
Verification
| Check | Result |
|---|---|
pnpm test:e2e:external |
PASS; external site built from published artifacts |
node --import tsx --test tests/interactive-runtime/official.test.ts |
PASS 9/9 |
pnpm --filter @riebeckite/web build |
PASS; 1,042 pages |
pnpm typecheck |
PASS; 3 projects |
pnpm check |
PASS; 1,818 files |
pnpm check:packages |
PASS; 117 packages |
pnpm check:docs |
PASS |
pnpm check:client-entries |
PASS |
pnpm --filter @riebeckite/core test |
PASS 565/565 |
pnpm --filter @riebeckite/node test |
PASS 92/92 |
pnpm --filter @riebeckite/plugin-image-compare test |
PASS 13/13 |
pnpm --filter @riebeckite/plugin-code-tabs test |
PASS 2/2 |
pnpm --filter @riebeckite/plugin-search test |
PASS 32/32 |
pnpm --filter @riebeckite/plugin-mdx test |
PASS 11/11 |
| UI tests | PASS 13/13 |
| Diagram tests | PASS 8/8 |
| Mermaid tests | PASS 17/17 |
| Text-fragment tests | PASS 21/21 |
| Changelog tests | PASS 9/9 |
The Graphviz package has no test files of its own; the shared lifecycle is covered by packages/diagram/test/client.test.ts. A workspace-wide pnpm test was not run; the packages affected by this branch and the merge were tested individually.
Remaining work
Phase 1-4 have no remaining implementation item. Optional follow-up: run the complete workspace test suite and add browser coverage for external renderers other than Mermaid and Graphviz.
Merge readiness
All verification gates pass on the final branch, including the external scaffold E2E, the 9-case official browser suite, and the 1,042-page website build. Phase 0-4 are complete on this branch. Merge, push, and deploy were intentionally not performed and remain the reviewer's decision.
Powered by Riebeckite