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

# Phase 7 — shared packages, upgrades and release preparation

Update: [Release blocker clearance](2026-10-19-release-blocker-clearance.md) 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

```sh
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.