Wave 5c — fresh-ui end product: foundation (Run 1) + design system (Run 2) DELIVERED · scaffold revamp deferred to post-5d · READY TO MERGE

[rickylabs]

✅ STATUS (2026-06-12): Runs 1–2 COMPLETE & MERGED INTO THIS BRANCH — READY TO MERGE INTO THE UMBRELLA

This PR began as the 5c research + design + 3-run plan (original plan body preserved below). Since then:

• Run 1 — 5c1 ui-foundation: COMPLETE. Merged into this branch. Token pipeline (DTCG → Style Dictionary v5 → generated registry/theme/ artifacts with drift gate), registry v2 manifest/schema, platform-first runtime (native <dialog>, Popover API + CSS anchor positioning), ui:init/ui:add CLI path.
• Run 2 — 5c2 design-system (PR Run 5c2: Official design system #32): COMPLETE, IMPL-EVAL'd, MERGED into this branch. 12 slices: playground converted to a true ui:add consumer; living reference routes /design/{tokens,components,composition}; two new fitness gates (check-ds-no-raw-hex.ts, check-ds-color-utilities.ts, both with negative tests); reduced-motion policy across all animated registry CSS; copy-fidelity sweep (content identity modulo CRLF + island import depth); final-form README + docs/l0-conventions.md + docs/theme-authoring.md; root check/lint/fmt clean; deno publish --dry-run PASS incl. slow types.
• Reconciled with the umbrella (post-5a service + 5b sdk merges): umbrella merged into this branch, deno.json root-gate conflict resolved as the union (sdk and fresh-ui fmt both lifted into root gates; only packages/fresh + cli remain excluded; arch:check → check-doctrine.ts). Validated: root check 1431 files / 0 errors, fmt:check 933 / 0.
• Follow-up artifacts for the next runs are on this branch: doctrine cleanup plan (.llm/plans/2026-06-12-fresh-ui-doctrine-plan.md, C-1…C-12 incl. docs-scaffold/doctests and the Zag adoption ADR spike) and the follower-model playbook (.agents/skills/fresh-ui-horizontal/SKILL.md).

⚠️ Run 3 (5c3 scaffold revamp) is DEFERRED — intentionally NOT in this PR

The full CLI scaffold app — the frontend rewrite with a public-facing, TanStack-starter-level feature showcase — happens after Wave 5d (@netscript/fresh) merges. Rationale: the scaffolded app must compile all recent improvements together (5a service + 5b sdk + 5c fresh-ui design system + 5d fresh DSL/builders/forms/query/streams) in the most quality-structured and exhaustive way possible; scaffolding it against a pre-5d fresh surface would bake in a surface we are about to re-architect. The original 5c3 gate ("hard-gates on 5b merge") is superseded: it now gates on 5d merge and will run as its own sub-wave with the doctrine cleanup plan folded in.

Consequence: nothing else is pending on this branch → this PR can be merged into feat/package-quality-wave5-apps now. Merging it unblocks 5d, which consumes fresh-ui's form seams (5d-5) and the design-system surface.

---

Original plan hand-off (historical)

Generator hand-off for sub-wave 5c, rescoped by the user from "package quality pass over fresh-ui" to: plan the intended end product per RFC 06 + NETSCRIPT-UI-WHITEPAPER — composition system, official NetScript design system, and total revamp of the CLI-generated frontend output.

Artifacts (.llm/tmp/run/feat-package-quality-wave5-apps--5c-fresh-ui/)

• research.md — 3-tier current-state inventory (fresh-ui package / playground / CLI templates + legacy generated app) + external research with sources (Base UI 1.0, shadcn CLI 3.0 registry, DTCG 2025.10 + Style Dictionary v5, official @zag-js/preact, Popover API / anchor positioning Baseline status, Tailwind v4 @theme)
• design.md — the end-product architecture: one distribution chain (DTCG → SD v5 → generated CSS artifacts → registry v2 → ui:init/ui:add → apps); playground + starter app as two consumers of one registry; platform-first runtime behind Zag-shaped contracts
• plan.md — 13 decisions (D-1…D-13), 3-run split (5c1 foundation — 16 slices; 5c2 design system; 5c3 scaffold revamp — now deferred to post-5d, see status above), gates incl. two new fitness checks
• drift.md — 6 entries incl. two whitepaper amendments (Zag-everywhere → platform-first; literal L0 → contract), the resolved RFC 06 token statement, and the no-ui-primitives-split decision

Key decisions (all held through implementation)

1. D-2 runtime doctrine: platform engines (native <dialog>, Popover API + anchor positioning) for overlay/disclosure components; official @zag-js/preact only for machine-class components (post-spike, ADR in doctrine plan C-12); all behind one Zag-shaped prop-getter contract.
2. D-3 token pipeline: DTCG source → Style Dictionary v5 → checked-in generated artifacts with a CI drift gate; --ns-* consumer contract invariant. Resolves the RFC 06 deferred statement.
3. D-4/D-5 registry v2: shadcn-grade item schema, distributed inside the JSR package via netscript ui:init/ui:add (44 items shipped, manifest schema v2).
4. D-10/D-11 scaffold revamp: netscript init installs from the registry instead of shipping forked templates — deferred to post-5d (see status).
5. D-12 topology: one package, no @netscript/ui-primitives split (drift vs whitepaper, rationale recorded).

🤖 Generated with Claude Code

[rickylabs]

PLAN-EVAL Verdict: PASS (v2 LOCKED)

PLAN-EVAL session completed for Wave 5c. The proposed plan passes with three amendments.

Amendment list (one line each)

1. D-4 Registry schema v2: add cssVars?: { theme?, light?, dark? } and author?: string fields — aligns with proven shadcn model without sacrificing our simpler kind taxonomy.
2. D-2 Popover fallback decision: CSS position: fixed + inset fallback for non-anchor-positioning browsers — OddBird polyfill rejected due to dynamic-content caveat with Fresh partials and tens-of-KB cost.
3. D-11 Starter app spec: full scaffolded-app file tree, route table, dynamic contract, starter collection, playground-parity checklist, and glue whitelist provided in design-appendix.md.

Evidence highlights (5 strongest facts)

1. @zag-js/preact v1.41.2 is real and current — same monorepo as React/Vue/Svelte adapters, per-machine packaging means scoped bundle cost. Extract: .llm/tmp/docs/zagjs-preact-api.md.
2. Popover API is Baseline (Jan 2025) — all major browsers support popover, popovertarget, togglePopover(). Anchor positioning is 2/3 engines (Firefox flag). Extract: .llm/tmp/docs/popover-api-anchor.md.
3. Tailwind v4 @theme inline is the correct bridge for referencing :root custom properties — generates utilities while keeping semantic source separate. Extract: .llm/tmp/docs/tailwindcss-v4-theme.md.
4. DTCG 2025.10 color object format {colorSpace, components, hex} is supported by Style Dictionary v5 (zeroheight already runs it in production). Extract: .llm/tmp/docs/style-dictionary-dtcg.md.
5. Base UI 1.0 contract-first composition (data-attrs + prop merging, not ~40 wrappers) validates our L0-as-contract direction. Extract: .llm/tmp/docs/base-ui-contract.md.

What implementation runs 5c1–5c3 may now rely on

• Run 1 (foundation): 16 locked slices including SD v5 token pipeline, registry v2 schema, Zag×Fresh spike, Popover API migration with CSS fallback, ui:init/ui:add CLI commands.
• Run 2 (design system): 12 slices with gate-evidence columns — playground convergence, /design styleguide, DS lint gates.
• Run 3 (scaffold revamp): 16 slices — starter app as playground sibling, dynamic contract introspection, netscript init e2e gating on 5b merge.

Plan is LOCKED v2. No further planning needed before run 1 implementation begins.

[augmentcode]

This pull request is too large for Augment to review. The PR exceeds the maximum size limit of 75000 tokens (approximately 300000 characters) for automated code review. Please consider breaking this PR into smaller, more focused changes.