WRNexusJS/docs/plans/2026-10-19-design-system-phase-7-implementation.md

Phase 7 — shared packages, upgrades and release preparation

Update: Release blocker clearance subsequently cleared the repository-wide production gates and reverified the installed packages. Publication remains held at the user’s request. The initial Phase 7 verification record below is retained for context.

Date: 2026-10-19. Initial status: local packaging candidate verified; publication remains gated by existing repository-wide type/API/visual failures and registry/version checks. Nothing was published, deployed or made public. Source package versions were not bumped.

Delivered

Standalone package boundaries

Studio now imports declared public package entry points rather than sibling source files. The engine exposes @wrnexus/design-system/package; Studio exposes @wrnexus/design-studio/upgrades; styles exposes the additive browser-safe @wrnexus/styles/theme entry. Existing exports remain available.

The staged engine ships its exported schema.json. Studio ships compiled JS/declarations, a prebuilt browser asset and the installed wrnexus-design-studio binary. The repository's existing bun run design:studio launcher calls the same CLI implementation. Published server startup reads the packaged browser asset; source development retains on-demand compilation. Preview compilation resolves the installed core package, and temporary component modules are separated by installation location.

MCP loads Studio through its public agents entry as an optional peer. The staged manifest preserves peerDependenciesMeta, so an MCP-only installation keeps the existing eight tools without pulling in Studio. An explicit design call without compatible Studio fails with WRN-MCP-DESIGN-INSTALL. Read-only versus write-enabled startup options remain unchanged.

The standard staging tool now supports an isolated, validated --stage-root=.publish-NAME and explicit --with-dependencies. It includes local dependencies/optional peers in dependency order, preserves optional-peer metadata and generates Studio's browser asset. The default .publish behavior remains available. The new design workflow uses .publish-design, leaving existing .publish output intact. Staging removes only a validated direct workspace staging directory before rebuilding it.

Shared design packages and explicit upgrades

createDesignPackage(system, notes?) produces a self-contained schema-v1 design envelope with format version 1, contract version 1 and a SHA-256 content digest. Stable object-key ordering yields the same pin in separate applications. The envelope retains modes, densities, aliases, recipes and supported metadata. A digest detects changed bytes/content; it is not a publisher signature. Package source is bounded and must use a semantic release version; unresolved external inheritance is rejected.

readDesignPackage(source) verifies the envelope and digest. Existing canonical schema-v1 JSON can be wrapped explicitly, with a reported canonical-v1-to-package-v1 migration. Unsupported future formats/contracts and changed content are rejected. This introduces no automatic renaming or lossy token conversion.

planDesignUpgrade(session, source) returns the verified package, migration list, changes, lock diagnostics and exact current design/lock revision without changing the draft. applyDesignUpgrade verifies again and stages the adoption through existing history/autosave. Source errors, identity changes, stale revisions and locked effective decisions block adoption. Undo/redo restores previous designs. No registry fetch, dependency update or application change occurs automatically; explicit supported-version adoption also supports deliberate rollback.

MCP adds three operations:

Tool	Behavior
wrnexus_design_package	Export the last valid system as a pinned package; optional bounded notes
wrnexus_design_upgrade_plan	Review incoming source, returning the draft revision and upgrade plan
wrnexus_design_upgrade	Adopt incoming source using the latest baseRevision; recheck identity, digest and locks

Existing design operations, application revisions, default MCP APIs and component behavior remain intact. The new package/upgrade APIs are programmatic; Phase 7 adds no new Studio controls.

Recoverable storage migration

Existing unversioned browser drafts and agent state remain readable. Subsequent saves add storage version 1 without dropping raw invalid source, valid preview, locks, history or saved pages. The browser storage key is unchanged.

Unknown future/faulty browser storage is retained byte-for-byte and exposed as session.recoverySource. Automatic writes stay blocked until the saved data has been backed up and storage deliberately reset. In-memory edits and exports remain usable. Future agent state also fails closed without rewriting STATE.json. Existing application pointers and immutable revision bundles require no migration. Separate browser and agent storage boundaries are retained.

Recovery instructions ship inside each of the engine, Studio and MCP tarballs as RELEASE.md; package READMEs link to that local guide. Back up the managed directory and browser storage before changing authoring versions. Stop writers before clearing crash-held lock directories. Keep a compatible tool version alongside saved data; older binaries cannot promise to read future formats.

Reproducible local release workflow

bun run design:release:plan
bun run design:release:stage
bun run design:release:check
bun run design:release:gate

• plan: record the current local dependency closure and versions without contacting a registry.
• stage: build and integrity-check the 16-package closure under .publish-design.
• check: verify staged versions and integrity, create npm tarballs, install them into isolated temporary consumers with lifecycle scripts disabled, and test actual installed packages. Report success is set only after all consumer/type/MCP-only checks pass; a new run first clears stale success status.
• gate: require the existing full check:production workflow before the installed-consumer check. It currently fails on the repository blockers below and cannot be treated as a publication approval.

The staging closure includes engine, Studio, MCP and their actual local framework dependencies. Existing source versions remain: engine/Studio 0.1.0, MCP 0.8.8, with the existing UI/styles/framework versions recorded in release-plan.json. The workflow does not guess an unused registry version, authenticate, change access, bump versions or publish. Before an actual release, resolve the full gates, confirm unused versions and target-registry permissions, use the existing version process intentionally, restage and reverify. Restricted access remains the staging default.

Outputs: output/design-system-phase-7/release-plan.json, tarballs.json, tarballs/, consumer-report.json and release-readiness.json. The integrity manifest is .publish-design/PACKAGE-INTEGRITY.json. The readonly readiness report explicitly sets readyToPublish: false while blockers remain. Installed-browser QA can retain a disposable consumer using check --keep-consumer; the default check cleans up its verified temporary paths.

Validation

• 311 tests pass, 0 fail, 50 files, 4,015 assertions and one snapshot across Studio, MCP, engine, compiler, SSR and theme/component design-system suites.
• Focused TypeScript and ESLint pass for changed Studio/engine/MCP code and release scripts. Installed-package declarations also pass a separate TypeScript consumer check.
• Existing staging-integrity probes and workspace repair checks pass. The 16-package candidate stages successfully with JS, declarations, schema, component sources, browser assets and local release guides.
• Real npm tarballs install into a consumer outside the source checkout. Two independent app roots adopt the same pin and generate the same applied revision without changing their existing configuration.
• Installed-consumer checks exercise reviewed upgrades, unfinished-draft reload, locks/history/undo/redo, browser-safe root and upgrade bundling, the source-free prebuilt Studio client, real composed and agent component previews, all preset compilation, installed Studio CLI startup and MCP stdio.
• Native browser QA against the installed Studio binary confirmed the prebuilt client, Soft component styling (16 px radius and green brand color), three guided alternatives and draft/alternative recovery after reload. Evidence: output/design-system-phase-7/installed-studio.jpg. The disposable installed demo is available on loopback port 4327.
• A separate installation containing only MCP proves the default eight tools work without Studio and explicit design calls return an actionable missing-peer error.
• API baseline additions are limited to the new engine package, Studio upgrade and styles theme subpaths. Existing unrelated baseline drift is left for review.

Gates recorded at initial handoff

Historical record: the repository-wide failures below were subsequently cleared by the linked clearance report. Registry/version verification remains deferred until an authorized publication. At the initial handoff, these failures were not blanket-accepted:

• Repository TypeScript errors in CLI configuration, CSR/dev-server tests and UI canvas tests. The changed package/release scope passes its focused check.
• Public API drift in auth, block-editor, blocks, CLI, core, dnd, email-renderer, payment, syntax, UI and viewer.
• UI visual hashes for packages/ui/styles/SelectStyles.wrn and packages/ui/ui.css.
• Registry version availability, release access and publication have not been checked or exercised.

See the machine-readable readiness report for exact affected files. Passing local packaging checks does not erase these repository-wide gates. No source outside the packaging/design scope was repaired or its baseline accepted implicitly.