51 lines
7.4 KiB
Markdown
51 lines
7.4 KiB
Markdown
# Phase 4 — Local Design Studio
|
||
|
||
Date: 2026-10-19. Delivered: non-AI authoring, isolated previews, local history, import/export, review and local application revisions on the existing engine and 104 component contracts.
|
||
|
||
## What shipped
|
||
|
||
A new private workspace package, `@wrnexus/design-studio`, separates its browser-safe state model from the filesystem/compiler/SSR server entry. Run `bun run design:studio`; optionally pass `--app-root <existing application directory>` to enable application bundles. The default URL is `http://127.0.0.1:4320/`.
|
||
|
||
The editor supports blank creation, presets, duplication, system identity, searchable foundation tokens and semantic bindings, base/mode/density layers, token aliases, additional tokens/layers, contract inspection for all 104 components, allowed part defaults, complete per-component recipe JSON, and canonical source editing. Variants, sizes, states and compound rules use the same engine schema; no second styling schema was introduced.
|
||
|
||
The Swiss authoring shell uses white surfaces, Helvetica typography, hairline grid divisions and blue actions. Its draft remains visually separate from the design being authored. The paired editor/source model is the main interaction: structured controls edit the canonical document, and invalid source remains recoverable while previews use its last valid revision.
|
||
|
||
Previews compile trusted shipped `.wrn` components and use the normal SSR document renderer, theme adapter and browser behavior runtime. They include a composed form/dialog page and seven catalog pages covering all 104 default component states. Controls select mode, density, width, direction, comparison and catalog page. Comparison uses identical authored content and can show a preset or last applied design. No AI provider is involved.
|
||
|
||
## Drafts, history and imports
|
||
|
||
Autosave stores the raw canonical draft, last valid preview, applied baseline and up to 25 revisions in local browser storage. Undo/redo preserves invalid revisions and supports branching. Reload recovery is tested with realistic full-preset histories. Corrupt storage and quota failures are reported; raw draft export remains available.
|
||
|
||
Import inspection reports preserved, ambiguous and unsupported values before accepting a document. Canonical JSON round-trips losslessly. Legacy import maps known literal theme suffixes and reports unmapped fields. Exchange import supports a documented scalar/alias subset with group type inheritance and descriptions; composite/structured values are reported as unsupported, and missing WrNexus semantic bindings are marked ambiguous. Imports never execute configuration files, fetch assets or infer missing inheritance parents.
|
||
|
||
Exports include canonical JSON, standalone compiled CSS, existing-adapter theme configuration, resolved flat exchange tokens, compatibility reports and raw invalid drafts. Canonical JSON is the editable source of truth; exchange export is intentionally resolved and lossy. See the [package guide](../../packages/design-studio/README.md) for exact fidelity limits.
|
||
|
||
## Review, application and rollback
|
||
|
||
Review shows affected paths and before/after values. Foundation changes are described as potentially affecting all contracted components; component recipe changes identify their component names.
|
||
|
||
Local apply writes immutable version directories containing system JSON, CSS, theme configuration, exchange tokens, compatibility report and integration guidance. A single atomic `CURRENT.json` pointer selects the active local revision. Base revisions detect conflicts. Rollback swaps the current and previous pointers, including undoing a first apply to `none`. Existing app configuration is preserved.
|
||
|
||
Applications explicitly import a reviewed generated `theme.json` into their existing configuration. Explicit app theme overrides and instance props retain their established precedence. Changing a Studio pointer alone does not rebuild an app pinned to an earlier import, publish a package or deploy anything. `/application-preview` verifies the selected on-disk system through the existing adapter. Browser verification used only `output/design-system-phase-4/application-demo`, not an existing user application.
|
||
|
||
## Verification
|
||
|
||
- Combined regression: **358 pass, 0 fail**, 33 files, 6,965 assertions across Studio, engine, CLI, styles, UI, SSR and theme runtime.
|
||
- Focused TypeScript check includes all Studio sources, tests and launcher and passes. Targeted lint passes.
|
||
- Model tests cover invalid drafts, reload recovery, undo/redo/branching/history bounds, storage failure, canonical round trips, legacy/exchange fidelity, malicious/oversized/missing/cyclic imports and applied snapshot detachment.
|
||
- Application/server tests cover immutable bundles, existing config preservation, adapter consumption, conflicts, rollback including initial application, same-origin/local-host restrictions, request bounds, read-only startup and browser-safe bundling.
|
||
- Preview tests cover three presets × two modes, RTL, SSR control registries, real component hooks and all 104 catalog defaults. Preview scripts do not try to load external controller bundles.
|
||
- Native browser verified six composed preset/mode combinations with expected fonts and radii: Square 0px/mono, Soft 16px/serif, Angular 0px/sans. Those tested desktop pages had no horizontal overflow.
|
||
- Native browser verified token editing, recipe editing (8px Button override), invalid source/reload/undo recovery, import diagnostics, comparisons, dark mode, RTL and width selection; switch, InputNumber and dialog interactions worked. Fresh composed previews had no console errors after the SSR registry repair.
|
||
- Native browser applied two revisions to the demonstration folder, rolled back to the earlier 12px-radius revision, and displayed a precise 12px → 16px remaining draft diff. Application files and existing config preservation are also checked by tests.
|
||
|
||
Evidence: `output/design-system-phase-4/` contains browser results and screenshots. Existing Phase 3 catalog verification remains applicable to the component sources, which this phase does not modify.
|
||
|
||
## Boundaries and follow-on work
|
||
|
||
The shell has responsive CSS, and preview frames support narrow widths. The current native browser viewport override did not change the shell's measured 1280px width; full mobile-shell certification is not claimed. External provider pixels, native popups, user-owned content and all populated interaction states retain their contract limitations. During exploratory DatePicker interaction, its existing client expression parser emitted a diagnostic; its source/API is unchanged and it remains in the default-state gallery. The composed preview focuses on core form controls, InputNumber and dialogs.
|
||
|
||
Preview frames allow scripts without same-origin privileges, use bounded server-generated documents, and block network, forms and remote fonts. The loopback server rejects foreign hosts/origins and only writes to its configured root. The draft store is local and single-user; multiple tabs do not merge concurrent drafts. Local history is not collaborative storage or a backup.
|
||
|
||
Guided generation, natural-language edits, decision locks, MCP mutation tools, collaborative storage and package publication remain later phases. The Studio is private and repository-local in this phase. Existing public API and visual-hash drift outside this delivery is preserved; only the new Studio package is added to the API baseline. No existing component source, runtime or theme API was changed for this phase.
|