94 lines
10 KiB
Markdown
94 lines
10 KiB
Markdown
# Phase 6 — agent design operations and page conformance
|
||
|
||
Date: 2026-10-19. Delivered locally on the existing engine and 104 component contracts. Published-package delivery remains part of the later release work.
|
||
|
||
## Delivered
|
||
|
||
- Opt-in `@wrnexus/mcp` design tools. Existing eight framework tools and default startup behavior stay intact. `design: true` enables inspection; `designWrite: true` additionally exposes mutations. The service is loaded only when a design tool is called.
|
||
- Agent context version 1: resolved tokens and origins, mode/density, locks, selected component props/events, axes, parts, slots, support boundaries and composition examples. Select up to 12 components; capabilities lists the complete catalog. No AI provider or credentials are required.
|
||
- Recoverable local agent drafts: raw source, last valid system, decision locks, 25 source-history entries, saved page specifications and one swappable previous workspace checkpoint. Every mutation needs the latest draft revision. Invalid source and lock violations remain recoverable and keep the last valid preview.
|
||
- Literal page specifications generate compilable `.wrn` component tags (compiled into existing mount markup) and semantic-token layout CSS. Up to 12 pages, each containing 1–12 contracted component instances. Unknown props/axes, style escape hatches, non-JSON values, prototype keys, dangerous URL schemes and excessive nesting/size are rejected.
|
||
- Static conformance detects parse failures, unknown component APIs, invented literal variants, unverifiable dynamic axes, color literals, common foundation literals and common utility-class bypasses. Exact warning code/path exceptions require a written reason; errors cannot be waived.
|
||
- Page previews render trusted shipped components with the selected system. They return static HTML with a restrictive CSP; arbitrary agent-submitted source/imports/loads/functions are never executed by analysis or preview.
|
||
- Draft/application conflict checks, immutable design bundles, application pointer reversal, export and diffs. An application writer lock now serializes Studio and MCP apply/rollback across processes without changing their APIs.
|
||
|
||
## Setup and workflow
|
||
|
||
From this workspace:
|
||
|
||
```sh
|
||
bun packages/mcp/src/stdio.ts --root=E:/path/to/application --design
|
||
# Draft/bundle mutations explicitly enabled at startup:
|
||
bun packages/mcp/src/stdio.ts --root=E:/path/to/application --design-write
|
||
```
|
||
|
||
Programmatic integration:
|
||
|
||
```ts
|
||
const server = createFrameworkMcpServer(applicationRoot, {
|
||
design: true,
|
||
designWrite: true,
|
||
});
|
||
```
|
||
|
||
Use the same NDJSON JSON-RPC transport and `tools/list` / `tools/call` interface as the existing MCP server. Do not install this project into another account or agent environment implicitly. The new extension currently requires this monorepo workspace; standalone packaging is deferred with the private Studio package.
|
||
|
||
All names below start with `wrnexus_design_`:
|
||
|
||
| Operation | Inputs and behavior |
|
||
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `inspect` | Current draft/application revisions, source, valid system, diagnostics, locks, pages and source history |
|
||
| `capabilities` | Catalog, tool boundaries and limits |
|
||
| `context` | Optional `components`, `mode`, `density`; generation guidance for the last valid system |
|
||
| `create` | `baseRevision`, optional canonical JSON `source`; initialize/stage a draft |
|
||
| `propose` | `baseRevision` and either `source` or up to 48 `{path,value}` JSON-pointer patches |
|
||
| `locks` | `baseRevision`, `locks` such as `/tokens/color.primary` |
|
||
| `page` | `baseRevision`, `page: {id,title,components:[{component,props}]}`; validated source is returned in `result` |
|
||
| `validate` | Draft diagnostics and per-page conformance |
|
||
| `preview` | Saved `pageId`, optional mode/density; static HTML for last valid system |
|
||
| `conformance` | `source`, optional exact `{code,path,reason}` warning exceptions |
|
||
| `diff` | Applied-baseline design changes and saved page ids |
|
||
| `export` | Raw recovery source/locks/diagnostics, valid-system artifacts and page filename/source map |
|
||
| `apply` | `baseRevision`, `baseApplicationRevision`, optional mode/density; save design bundle and advance pointer |
|
||
| `revert` | `baseRevision`; default draft undo, `target: "checkpoint"` to swap workspace checkpoint, or `target: "application"` plus `baseApplicationRevision` |
|
||
|
||
Typical agent sequence: inspect → context → propose → inspect/validate/diff → save page specifications → preview/conformance → export. Reinspect after conflicts. Mutation responses include the new revision, diagnostics and affected paths. Application writes additionally require the independently observed application revision. Failed page proposals return diagnostics without advancing the revision.
|
||
|
||
Example page:
|
||
|
||
```json
|
||
{
|
||
"id": "account",
|
||
"title": "Account settings",
|
||
"components": [
|
||
{ "component": "Input", "props": { "id": "display-name", "label": "Display name" } },
|
||
{ "component": "Button", "props": { "label": "Save changes", "variant": "default" } }
|
||
]
|
||
}
|
||
```
|
||
|
||
Patch paths use canonical document pointers, for example `/tokens/color.primary/value`. Locked decisions protect effective alias and recipe dependencies through the existing session engine. Source edit errors are saved as diagnostic-bearing drafts. They cannot be applied.
|
||
|
||
## Storage and recovery
|
||
|
||
The server's configured application root is the only filesystem boundary; tools accept no output paths. Agent state is stored in `.wrnexus/design-studio/agent/STATE.json`, written through a uniquely named temporary file and atomic rename. Managed ancestors/files are checked for links. A workspace `LOCK` directory protects the read/check/write sequence. Studio application writes independently use `APPLY.lock`.
|
||
|
||
If a process dies while holding a lock, stop all writers, back up `STATE.json` and the managed directory, then remove the empty lock directory. Locks are never timed out or stolen automatically. Do not edit stored JSON while writers are active. Export preserves invalid raw source separately from valid build artifacts. Studio browser local-storage drafts and agent workspace drafts remain separate; exchange canonical source explicitly.
|
||
|
||
Draft state is bounded to 12 MB, requests to 2 MB, static conformance source to 128,000 characters, exceptions to 64. Session recovery retains the prior limits. Local filesystem owners are trusted; link checks do not claim adversarial OS-level race protection. Theme application and agent-state persistence are two separate atomic operations: after a disk failure, inspect both revisions before retrying.
|
||
|
||
## Adoption boundaries
|
||
|
||
`apply` saves the existing immutable design bundle and application pointer; it does not modify configuration or page routes. Import the reviewed `theme.json` through the existing app theme API. Exported page sources use the existing `data-component` mounting convention; integrate them into the application's routes with the matching UI component registry. Event handlers, application data loading, custom nested layouts, slots and provider integrations require normal application implementation. Page previews intentionally have no hydration, network requests or form submission.
|
||
|
||
The page specification is a bounded composition format, not a substitute for arbitrary application source. Arbitrary `.wrn` may be analyzed, but cannot be executed as an agent preview. Conformance is heuristic and does not resolve imported CSS, named colors, computed expressions, every utility framework, custom components or external assets. Passing does not certify accessibility, contrast or complete visual quality. Native/provider/content-owned regions keep their contracts. No provider calls, route rewrites, publishing or deployment happen implicitly.
|
||
|
||
## Verification
|
||
|
||
- Regression: **307 tests pass, 0 fail**, 49 files, 3,986 assertions and one snapshot, covering Studio, MCP, engine, compiler, SSR and design-system component/theme suites.
|
||
- Agent evaluation: `bun run scripts/evaluate-design-agents.ts` produces **6 page sources and 12 previews** using actual MCP calls: account and support pages × Square, Soft and Angular × light/dark. Sources compile and pass static conformance. Output: `output/design-system-phase-6/report.json`.
|
||
- Browser checks confirmed the exported previews display real inputs, headings, alerts and buttons. Soft uses a 16 px button radius and its green brand color; Square uses 0 px radius; Angular preserves its tilted outlined button in dark mode. Screenshots are saved beside the evaluation report.
|
||
- Focused TypeScript, ESLint and formatting checks cover changed Studio/MCP code and the evaluation script. Public API baseline changes are confined to Studio's new explicit subpaths and MCP's existing entry points; unrelated prior baseline drift is not accepted.
|
||
|
||
Tests cover opt-in/default compatibility, read-only behavior, real stdio structured context, recovery after service recreation, stale draft/application bases, locks, invalid source, checkpoint restoration, busy writers, compilation and preservation of string/boolean/structured mount props, all three designs in both modes, invalid page props/variants and justified warning exceptions. No paid model calls are used.
|