npm - @adia-ai/adia-ui-factory - Versions diffs - 0.2.2 → 0.2.4 - Mend

@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (95) hide show

package/.claude-plugin/plugin.json +12 -3
package/.mcp.json +1 -1
package/CHANGELOG.md +12 -0
package/README.md +24 -1
package/bin/adia-scaffold +93 -13
package/package.json +1 -1
package/references/shell-embed.md +10 -0
package/references/spa-architecture.md +7 -0
package/skills/adia-ui-kit/CHANGELOG.md +41 -0
package/skills/adia-ui-kit/SKILL.md +442 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/Guidelines.md +87 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/components.md +142 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/styles.md +118 -0
package/skills/adia-ui-kit/assets/figma-make/guidelines/tokens.md +120 -0
package/skills/adia-ui-kit/assets/team-scaffold/archive-README.md +30 -0
package/skills/adia-ui-kit/assets/team-scaffold/drafts-README.md +57 -0
package/skills/adia-ui-kit/assets/team-scaffold/inbox-README.md +76 -0
package/skills/adia-ui-kit/assets/team-scaffold/outbox-README.md +46 -0
package/skills/adia-ui-kit/assets/team-scaffold/team-root.README.md +51 -0
package/skills/adia-ui-kit/assets/team-scaffold/tickets-README.md +208 -0
package/skills/adia-ui-kit/assets/team-scaffold/tickets-REGISTRY.md +81 -0
package/skills/adia-ui-kit/assets/templates/AGENTS.template.md +128 -0
package/skills/adia-ui-kit/assets/templates/CLAUDE.template.md +1 -0
package/skills/adia-ui-kit/assets/templates/FEEDBACK-OMISSIONS-DEFENSE.template.md +150 -0
package/skills/adia-ui-kit/assets/templates/FEEDBACK.template.md +213 -0
package/skills/adia-ui-kit/assets/templates/RESPONSE.template.md +114 -0
package/skills/adia-ui-kit/assets/templates/figma-make-guidelines.md +90 -0
package/skills/adia-ui-kit/evals/adversarial-content-trust.json +83 -0
package/skills/adia-ui-kit/evals/evals.json +55 -0
package/skills/adia-ui-kit/evals/routing-corpus.json +121 -0
package/skills/adia-ui-kit/evals/teach-routing-cases.json +92 -0
package/skills/adia-ui-kit/references/capabilities.md +245 -0
package/skills/adia-ui-kit/references/catalog-lookup.md +186 -0
package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v1.md +8 -0
package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v2.md +3585 -0
package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v3.md +1899 -0
package/skills/adia-ui-kit/references/common-gotchas-consumer.md +522 -0
package/skills/adia-ui-kit/references/component-literacy.md +291 -0
package/skills/adia-ui-kit/references/composition.md +245 -0
package/skills/adia-ui-kit/references/correction-loop.md +462 -0
package/skills/adia-ui-kit/references/css-policy.md +343 -0
package/skills/adia-ui-kit/references/decision-model.md +158 -0
package/skills/adia-ui-kit/references/diagnostic-output.md +57 -0
package/skills/adia-ui-kit/references/docs-catalog.md +239 -0
package/skills/adia-ui-kit/references/exclusions.md +225 -0
package/skills/adia-ui-kit/references/feedback-authoring.md +466 -0
package/skills/adia-ui-kit/references/figma-make.md +244 -0
package/skills/adia-ui-kit/references/flows-auth.md +307 -0
package/skills/adia-ui-kit/references/flows-content.md +206 -0
package/skills/adia-ui-kit/references/flows-data.md +348 -0
package/skills/adia-ui-kit/references/flows-interaction.md +181 -0
package/skills/adia-ui-kit/references/flows-shells.md +336 -0
package/skills/adia-ui-kit/references/gap-detection.md +266 -0
package/skills/adia-ui-kit/references/harness.md +284 -0
package/skills/adia-ui-kit/references/loading-protocol.md +406 -0
package/skills/adia-ui-kit/references/local-link.md +198 -0
package/skills/adia-ui-kit/references/mcp.md +401 -0
package/skills/adia-ui-kit/references/migration.md +116 -0
package/skills/adia-ui-kit/references/mission.md +194 -0
package/skills/adia-ui-kit/references/mode-routing.md +298 -0
package/skills/adia-ui-kit/references/patterns-agent.md +223 -0
package/skills/adia-ui-kit/references/patterns-data.md +1065 -0
package/skills/adia-ui-kit/references/patterns-forms.md +223 -0
package/skills/adia-ui-kit/references/patterns-layout.md +326 -0
package/skills/adia-ui-kit/references/patterns-recipes.md +1416 -0
package/skills/adia-ui-kit/references/patterns-shells.md +1097 -0
package/skills/adia-ui-kit/references/patterns-traits.md +259 -0
package/skills/adia-ui-kit/references/patterns-wiring.md +339 -0
package/skills/adia-ui-kit/references/pev-rationale.md +137 -0
package/skills/adia-ui-kit/references/reasoning-gate.md +146 -0
package/skills/adia-ui-kit/references/reasoning-methodologies.md +112 -0
package/skills/adia-ui-kit/references/recon.md +192 -0
package/skills/adia-ui-kit/references/rendering-model.md +431 -0
package/skills/adia-ui-kit/references/response-authoring.md +398 -0
package/skills/adia-ui-kit/references/session-log-schema.md +203 -0
package/skills/adia-ui-kit/references/session-log-template.md +118 -0
package/skills/adia-ui-kit/references/setup.md +652 -0
package/skills/adia-ui-kit/references/skill-hygiene.md +135 -0
package/skills/adia-ui-kit/references/spec-to-ui-reasoning.md +394 -0
package/skills/adia-ui-kit/references/state.md +229 -0
package/skills/adia-ui-kit/references/teach-protocol.md +421 -0
package/skills/adia-ui-kit/references/theme.md +142 -0
package/skills/adia-ui-kit/references/version-check.md +69 -0
package/skills/adia-ui-kit/scripts/audit-decision-trace.mjs +198 -0
package/skills/adia-ui-kit/scripts/audit-kit-roster.mjs +366 -0
package/skills/adia-ui-kit/scripts/changelog-archive.mjs +126 -0
package/skills/adia-ui-kit/scripts/check-adia-versions.py +404 -0
package/skills/adia-ui-kit/scripts/run-skill-evals.mjs +358 -0
package/skills/adia-ui-kit/scripts/validate-session-log.mjs +242 -0
package/skills/adia-ui-kit/skill.json +102 -0
package/skills/adia-ui-migration/CHANGELOG.md +47 -0
package/skills/adia-ui-migration/SKILL.md +381 -0
package/skills/adia-ui-migration/skill.json +29 -0
package/skills/adia-ui-spa/SKILL.md +1 -1
package/skills/adia-ui-verify/SKILL.md +2 -2

package/skills/adia-ui-kit/references/gap-detection.md ADDED Viewed

@@ -0,0 +1,266 @@
+---
+name: gap-detection
+load-when: During consultant-posture recon — when classifying gaps between consumer repo state and substrate's current shipped capability. Four gap classes + detection recipes.
+load-size-tokens: ~3,000
+required-for:
+  - mode 5 (consultant)
+  - audit output authoring
+  - remediation plan ranking
+---
+# §GapDetection — Four gap classes, four detection recipes
+Every finding from §Recon falls into one of four classes. Each class
+has a distinct mechanism, a distinct detection recipe, and a distinct
+remediation shape. **Gap class 0 is a build-blocker** — Gap classes
+1-3 only matter if class 0 passes.
+### Gap class 0 — Manifest gap (build-blocker)
+**Mechanism:** consumer's `src/` imports `@adia-ai/*` but
+`package.json` declares zero `@adia-ai/*` deps. `npm install` honors
+the manifest (which says nothing) → `node_modules/@adia-ai/` doesn't
+exist → vite's bare-specifier resolver fails at `npm run dev`. The
+error message ("Are they installed?") is misleading — they were never
+*declared*.
+This commonly happens when:
+- A new consumer repo is scaffolded (e.g. `claims-ui-v9`) but the agent
+  authored imports before the operator added the deps.
+- A consumer copies `src/main.ts` from a sibling repo without copying
+  the corresponding `package.json` entries.
+- A dep was removed from `package.json` (cleanup) but the imports
+  weren't swept first.
+**Detection:**
+```bash
+# (a) Are there @adia-ai/* imports in src/?
+grep -rEn "from ['\"]@adia-ai/" --include='*.ts' --include='*.js' \
+  --include='*.tsx' --include='*.jsx' --include='*.vue' --include='*.svelte' \
+  src/ 2>/dev/null | wc -l
+# (b) Are there @adia-ai/* declarations in package.json?
+node -e "const p=require('./package.json'); const deps={...p.dependencies, ...p.devDependencies}; console.log(Object.keys(deps).filter(k=>k.startsWith('@adia-ai/')).length)"
+# Gap class 0 fires iff (a) > 0 AND (b) === 0.
+```
+**Interpretation:**
+| (a) imports | (b) declared | Verdict |
+|---|---|---|
+| 0 | 0 | Clean (no use, no declarations) |
+| N>0 | M>0 | Normal — check Gap class 1 (version drift) |
+| 0 | M>0 | Unused declarations — sweep candidate (low priority) |
+| **N>0** | **0** | **Manifest gap — HALT before composing further UI** |
+**Remediation** — two paths, pick based on consumer intent:
+**Path A — bundler install** (default for production apps with Vite/webpack):
+```bash
+# Match the reference dep shape from a known-good sibling (e.g. claims-ui-v8):
+npm install @adia-ai/web-components@^0.6.X @adia-ai/web-modules@^0.6.X
+# (+ @phosphor-icons/core if main.ts imports icons; check src/main.ts imports)
+# Then verify:
+ls node_modules/@adia-ai/  # should now exist
+npm run dev                # vite resolves cleanly
+```
+**Path B — switch to CDN** (since v0.6.30, the zero-install escape hatch):
+If the consumer's intent is "quick prototype" / "CodePen demo" /
+"marketing page" / "static HTML site" — or if `package.json` shouldn't
+exist at all for the surface — **don't add `@adia-ai/*` deps**.
+Replace the `import` statements with HTML `<link>` + `<script>` tags
+pointing at the CDN bundles:
+```html
+<!-- In index.html <head>, NO npm install required -->
+<link rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.7/dist/web-components.min.css">
+<link rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.7/dist/shell/admin-shell.min.css">
+<script type="module"
+        src="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.7/dist/everything.min.js"></script>
+```
+This converts Gap class 0 from a hard-halt into a **mode choice** — the
+operator picks bundler-served OR CDN-served. The CDN path doesn't
+require ANY `package.json` deps for `@adia-ai/*`; the manifest gap
+becomes irrelevant for HTML-first surfaces. See §CSSPolicy → "CDN-bundle
+path" for the full 3-tier policy.
+**Path A vs Path B — choice tree**:
+| Signal | Choose |
+|--------|--------|
+| `vite.config.*` or `webpack.config.*` exists | Path A (install) |
+| `<script src=".../@adia-ai/...">` already in HTML | Path B (CDN) |
+| User said "quick" / "prototype" / "demo" / "CodePen" | Path B (CDN) |
+| User has production deployment story / "ship to prod" | Path A (install) |
+| Repo has zero `package.json` (greenfield static HTML) | Path B (CDN) |
+| User has a `src/main.ts` and is mid-Vite-build | Path A (install) |
+The bundler remediation is still the default for "I scaffolded a Vite
+app and need the deps" — Path B is for cases where the bundler itself
+is the wrong tool, not just for missing deps.
+The remediation is one `npm install` command (Path A) OR three CDN
+tags in `<head>` (Path B), but the **discipline is to detect the gap
+before authoring any further imports** — otherwise the "compose a
+screen" call ships code that won't start (Path A) OR ships imports
+the CDN page can't resolve (Path B).
+**Surfacing to operator:** if Gap class 0 fires, do not silently fix
+it — surface the gap with the exact reference shape (from a sibling
+repo if available), the install command, and a one-line explanation.
+The operator decides whether to add the deps or back out the imports.
+**Anti-pattern:** running `npm install` (no args) to "fix the gap." That
+only installs what's already declared. With zero declarations, it's a
+no-op and the build still fails. The fix is `npm install <package>` —
+which both declares AND installs.
+**Worked example (claims-ui-v9, 2026-05-23):** `src/main.ts` had 5
+`@adia-ai/*` imports (`web-components`, `web-components/css`,
+`web-components/core/icons`, `web-modules/shell`, `web-modules/shell/admin-shell.css`).
+`package.json` had `{}` for `@adia-ai/*` deps. `npm install` was a
+no-op for that scope; `node_modules/@adia-ai/` didn't exist; vite's
+dependency scanner halted dev-server boot with "could not be
+resolved / Are they installed?". Remediation: `npm install
+@adia-ai/web-components@^0.6.28 @adia-ai/web-modules@^0.6.28`. Sibling
+reference shape was `claims-ui-v8/package.json` (`^0.6.23` of the same
+two packages — same import surface, same publish layout).
+### Gap class 1 — Version drift
+**Mechanism:** consumer's installed `@adia-ai/*` versions trail the
+substrate's `latest` dist-tag. The substrate has shipped features /
+fixes the consumer hasn't picked up.
+**Detection:**
+```bash
+# Substrate's latest dist-tag (each of the 9 packages should match):
+for pkg in web-components web-modules llm a2ui-compose a2ui-corpus \
+           a2ui-mcp a2ui-retrieval a2ui-runtime a2ui-validator; do
+  echo -n "$pkg "; npm view "@adia-ai/$pkg" version 2>/dev/null
+done
+# Consumer's declared ranges:
+grep -E '"@adia-ai/' package.json
+# Consumer's installed actuals:
+for d in node_modules/@adia-ai/*; do
+  echo -n "$(basename $d) "; node -p "require('$d/package.json').version"
+done
+```
+**Interpretation:**
+| Declared / Installed / Latest | Drift | Remediation |
+|---|---|---|
+| `^0.6.0` / `0.6.18` / `0.6.19` | Minor PATCH lag | `npm install @adia-ai/web-components@^0.6.0` — picks up the latest 0.6.x. PATCH cuts are non-breaking. |
+| `^0.6.0` / `0.6.18` / `0.7.0` | Minor MINOR lag | Read v0.7.0 CHANGELOG; decide explicit bump (breaking changes possible). |
+| `^0.4.0` / `0.4.0` / `0.6.19` | Major-relative lag | Trigger §Migration phase — multi-cut breaking-change sweep. |
+| 9-pkg ranges inconsistent | Lockstep break | **Hard failure** — internal `^0.6.0` deps will resolve to mismatched siblings. Fix before any other work. |
+### Gap class 2 — Spec drift (ADR adoption)
+**Mechanism:** substrate ships an ADR (e.g. ADR-0024 retired legacy
+shell shapes; ADR-0023 introduced bespoke shell vocabulary). Consumer
+code predates the ADR and still uses the retired shape, or hasn't yet
+adopted the new canonical shape.
+**Detection:**
+For each ADR that introduces a vocabulary change, grep the consumer's
+codebase for the *retired* shape. AdiaUI's load-bearing ADRs and their
+grep signatures:
+| ADR | Introduced | Retired shape (grep target) | Canonical replacement |
+|---|---|---|---|
+| ADR-0023 (v0.4.0) | bespoke shells | `<chrome-shell`, `<chrome-rail`, `<chrome-canvas`, `<page-shell` | `<admin-shell>`, `<editor-shell>`, `<chat-shell>` |
+| ADR-0024 (v0.4.0) | strip JS legacy reads | `data-actions=` (in JS-set host attrs) | `slot="action"` on children |
+| ADR-0029 (v0.6.16) | sealed tsconfig substrate | un-tracked `// @ts-ignore` w/o `TS-MIG-NNN` | tracked override + entry in `.brain/notes/ts-mig-tracking.md` |
+| ADR-0030 (v0.6.10) | `/with-css` opt-in | implicit CSS side-effect imports | `/with-css` subpath OR explicit CSS import |
+| ADR-0032 (v0.6.13) | CSS bridges retired | `--agent-*` tokens, `AgentElement` | `--a-*` tokens, `UIElement` |
+**Generic grep recipe** (run from consumer repo root):
+```bash
+# Retired shells (ADR-0023):
+grep -rEn '<chrome-(shell|rail|canvas)|<page-shell' \
+  --include='*.html' --include='*.js' --include='*.jsx' \
+  --include='*.tsx' --include='*.vue' --include='*.svelte' .
+# Retired tokens / base class (ADR-0032):
+grep -rEn '--agent-|AgentElement|@agent-ui-kit' \
+  --include='*.css' --include='*.js' --include='*.ts' \
+  --include='*.json' .
+# Legacy authoring shapes (ADR-0024):
+grep -rEn 'data-actions=' \
+  --include='*.html' --include='*.js' .
+```
+**Interpretation:** every grep match is a spec-drift finding. The
+remediation is mechanical (find/replace) for most, except where the
+retired shape was carrying state that needs migration (rare; check the
+ADR's "migration notes" section).
+### Gap class 3 — Capability drift (hand-rolled-when-substrate-now-provides)
+**Mechanism:** consumer code hand-rolled a pattern (skeleton, toast,
+breakpoint grid, custom dialog) before the substrate shipped a
+first-class equivalent. The hand-rolled code now duplicates what
+substrate provides, drifts from it visually, and accumulates
+maintenance cost.
+**Detection:** the table in §Recon step 7 maps grep signatures to
+substrate replacements. Run each grep, count matches, and note the
+**leverage ratio**:
+```
+leverage = (N_locations × M_lines_per_location) / replacement_cost
+```
+High-leverage findings (>10 locations, >5 lines each, replaceable in a
+single PATCH cut) belong in the §DiagnosticOutput "high-priority"
+section. Low-leverage findings (1 location, deliberate carve-out)
+either get a first-principles audit (see §ReasoningMethodologies #4)
+or get accepted as deliberate.
+**Sniff test before declaring capability drift:**
+- Does the hand-rolled pattern *predate* the substrate capability? (Check
+  the consumer file's `git log` vs the substrate CHANGELOG entry.)
+- Is the hand-rolled pattern doing something the substrate can't? (Read
+  the substrate yaml for the prop's full surface; the consumer might
+  rely on a behavior the substrate primitive doesn't replicate.)
+- Is there a doc / changelog entry telling consumers to migrate? (If
+  yes, this is also a spec-drift finding; classify it once.)
+### Gap-detection output shape
+For each finding, capture:
+```yaml
+- class: manifest-gap | version-drift | spec-drift | capability-drift
+  evidence: <file:line> or <grep output>
+  count: <N locations>
+  substrate_answer: <component / token / ADR>
+  remediation: <one-line how-to>
+  leverage: high | medium | low
+  risk: low | medium | high  # behavior delta if remediated
+```
+Roll these up into §DiagnosticOutput. **Manifest-gap findings always
+sort first** — they're build-blockers and other findings can't be
+verified until they're resolved.
+---

package/skills/adia-ui-kit/references/harness.md ADDED Viewed

@@ -0,0 +1,284 @@
+---
+name: harness
+load-when: When wiring AdiaUI MCP server into a consuming app (Claude Desktop / Cursor / Windsurf / Claude Code) or when answering 'how do I add canvas-ui / a2ui-root / registerResolver?'
+load-size-tokens: ~2,700
+required-for:
+  - mode 7 (harness wiring)
+  - MCP install support
+---
+# §Harness — Inserting the MCP into your app
+> **⚠ Opt-in gate — read before continuing.** This section is only needed
+> if your app will have **runtime-generated UI from an LLM agent** (i.e. a
+> `<canvas-ui>` / `<a2ui-root>` rendering surface fed by an agent or a
+> stored A2UI document). For **product UIs built from AdiaUI primitives**
+> — dashboards, forms, data tables, auth flows, settings pages — your
+> setup is complete at §Setup. The harness adds no value when the UI is
+> hand-authored markup; it is the runtime substrate for **generative**
+> surfaces specifically. Return here only when adding a generative
+> surface to an existing AdiaUI app.
+Three integration modes, from simplest to most dynamic. Choose based on
+when generation happens relative to the user's session.
+---
+### Mode A — Author-time (IDE → static files)
+Generate at development time using the IDE MCP tools or CLI, then commit
+the output as static HTML page fragments. No runtime dependency on the
+MCP server.
+```bash
+# Generate from the CLI (instant mode, no LLM key)
+node packages/a2ui/mcp/scripts/generate.mjs "claims list table" > src/pages/claims.html
+# Or use the IDE MCP tool (Claude Code / Cursor)
+# → generate_ui("claims list with status badge and detail drawer", mode: "instant")
+# → copy the rendered HTML into src/pages/claims-list.html
+```
+The output is plain AdiaUI HTML that §Flows describes. Wire it into your
+admin shell via `router-ui` routing (see §Patterns → Admin shell anatomy).
+Zero runtime dependency.
+**When to use:** stable UI, content doesn't change at runtime, faster
+page load, no server needed.
+---
+### Mode B — Runtime rendering with `<canvas-ui>` API (no streaming, no server)
+If you have A2UI JSON in hand (from an API, local generation, or cached
+result), feed it directly to `<canvas-ui>`. No network transport, no
+streaming.
+```html
+<!-- In your HTML: the rendering surface -->
+<canvas-ui id="gen-canvas"></canvas-ui>
+```
+```js
+// In main.js — after generating or fetching A2UI messages
+// v0.6.7+: single import registers canvas-ui + a2ui-root + registerResolver
+import '@adia-ai/web-modules/generative';
+//
+// (Pre-v0.6.7 — still works but verbose:
+//   import '@adia-ai/web-modules/runtime/a2ui-root/a2ui-root.js';
+//   import '@adia-ai/web-components/components/canvas/canvas.js';)
+const canvas = document.getElementById('gen-canvas');
+// Option 1: render a complete set of messages at once
+canvas.reset();
+canvas.processAll([
+  { type: 'createSurface', surfaceId: 's1', components: [ /* ... */ ] },
+]);
+// ⚠ `canvas.doc = [...]` does NOT exist on <canvas-ui> — the `.doc`
+// property lives on <a2ui-root> (which <canvas-ui> internally hosts but
+// does not proxy). Assigning to a non-existent property is a silent
+// no-op; the canvas stays blank with no diagnostic. Use the method API
+// above (`reset()` + `processAll()`) for the canvas surface. If you
+// need the `.doc=` setter shape, target <a2ui-root> directly (Mode C).
+// Option 2: process messages one at a time (streaming simulation)
+canvas.reset();
+for (const msg of messages) {
+  canvas.process(msg);
+}
+// Option 3: call an endpoint yourself, then render
+const result = await fetch('http://localhost:3456/api/generate', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ intent: 'login form', mode: 'instant' }),
+}).then(r => r.json());
+canvas.reset();
+canvas.processAll(result.messages);
+```
+**`canvas-ui` API:**
+| Method / prop | What it does |
+|---|---|
+| `.reset()` | Clear the canvas, discard all components |
+| `.process(msg)` | Apply a single A2UI message to the current surface |
+| `.processAll(msgs)` | Apply an array of messages in order |
+| `.pushVersion(msgs)` | Save current messages to history (enables back/forward) |
+| `.back()` / `.forward()` | Navigate history. Return `false` at boundary |
+| `.historyLength` / `.historyIndex` | History stack inspection |
+| `.getHTML()` | Return formatted innerHTML of the inner `<a2ui-root>` |
+(For the `.doc=` setter shape, see `<a2ui-root>` in Mode C — `<canvas-ui>`
+is method-only by design.)
+**Registering resolvers (required for data-bound components):**
+Generated components that bind to real data use `resource://` and
+`api://` URIs. Without a resolver registered, those bindings return
+empty. Wire them in `main.js` before the canvas renders:
+```js
+import { registerResolver } from '@adia-ai/a2ui-runtime';
+// Resolve api:// URIs → your real backend endpoints
+registerResolver('api', async (uri) => {
+  // uri e.g. "api://claims?status=open"
+  const path = uri.replace('api://', '/api/');
+  const res = await fetch(path);
+  return res.json();
+});
+// Resolve resource:// URIs → static or lookup data
+registerResolver('resource', async (uri) => {
+  // uri e.g. "resource://claim-statuses"
+  return ['Open', 'In Review', 'Approved', 'Rejected'];
+});
+```
+**When to use:** single-page apps that generate UI on demand from user
+input, cached generation results, or test/preview environments.
+---
+### Mode C — Live streaming from MCP HTTP server
+For real-time generative UI where the page streams generated components
+as they arrive, wire `<a2ui-root>` or `<canvas-ui>` to the MCP HTTP
+server's streaming endpoint.
+**Step 1: start the HTTP MCP server**
+```bash
+MCP_HTTP_PORT=3460 node packages/a2ui/mcp/server.js
+# → listening on http://localhost:3460/mcp
+```
+Or via the proxy (which also serves the browser):
+```bash
+npm run dev   # Vite on :5173 + proxy on :3456
+# POST http://localhost:3456/api/generate → same pipeline
+```
+**Step 2: wire `<a2ui-root>` in your HTML**
+```html
+<!-- SSE streaming from /api/generate -->
+<a2ui-root
+  id="gen-surface"
+  transport="sse"
+  src="/api/generate">
+</a2ui-root>
+```
+Or use `<canvas-ui>` for history support:
+```html
+<canvas-ui id="gen-canvas"></canvas-ui>
+```
+**Step 3: trigger generation from user input**
+```js
+// v0.6.7+: one barrel for everything
+import { registerResolver } from '@adia-ai/web-modules/generative';
+import '@adia-ai/web-modules/generative';
+// Register resolvers before any generation triggers
+registerResolver('api', async (uri) => {
+  return fetch(uri.replace('api://', '/api/')).then(r => r.json());
+});
+const canvas = document.getElementById('gen-canvas');
+const input = document.getElementById('prompt-input');
+document.getElementById('generate-btn').addEventListener('press', async () => {
+  const intent = input.value.trim();
+  if (!intent) return;
+  canvas.reset();
+  // Call the proxy's generate endpoint
+  const result = await fetch('http://localhost:3456/api/generate', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ intent, engine: 'monolithic', mode: 'instant' }),
+  }).then(r => r.json());
+  canvas.processAll(result.messages);
+  canvas.pushVersion(result.messages);
+});
+```
+**`<a2ui-root>` events for observability:**
+```js
+const root = document.querySelector('a2ui-root');
+root.addEventListener('a2ui-connected', () => console.log('stream connected'));
+root.addEventListener('a2ui-message',   e  => console.log('message:', e.detail.message));
+root.addEventListener('a2ui-action',    e  => console.log('action:', e.detail.name, e.detail.params));
+root.addEventListener('a2ui-error',     e  => console.error('error:', e.detail.error));
+root.addEventListener('a2ui-closed',    () => console.log('stream closed'));
+```
+---
+### Complete harness wiring (Mode B — recommended starting point **for generative surfaces**)
+```js
+// main.js — full harness for a generative UI surface
+import '@adia-ai/web-components/css';
+import '@adia-ai/web-components';
+import '@adia-ai/web-modules/shell';         // per-cluster — the full '@adia-ai/web-modules' barrel ships broken absolute paths at v0.6.7
+import '@adia-ai/web-modules/shell/admin-shell.css';  // REQUIRED — see §CSSPolicy
+// v0.6.7+: single import for canvas-ui + a2ui-root + registerResolver
+import '@adia-ai/web-modules/generative';
+import { installIconLoadersForRegistered } from '@adia-ai/web-components/core/icons';
+import { registerResolver } from '@adia-ai/web-modules/generative';
+// Icon loader
+installIconLoadersForRegistered(
+  import.meta.glob('../node_modules/@phosphor-icons/core/assets/regular/*.svg',
+    { query: '?raw', import: 'default', eager: true })
+);
+// Wire data resolvers BEFORE any generation trigger
+registerResolver('api', async (uri) => {
+  const res = await fetch(uri.replace('api://', '/api/'));
+  if (!res.ok) return [];
+  return res.json();
+});
+registerResolver('resource', async (uri) => {
+  // Return static lookup data for resource:// URIs
+  const key = uri.replace('resource://', '');
+  const lookups = {
+    'claim-statuses':   ['Open', 'In Review', 'Approved', 'Rejected'],
+    'policy-types':     ['Auto', 'Home', 'Life', 'Health'],
+  };
+  return lookups[key] ?? [];
+});
+```
+```html
+<!-- index.html — the rendering surface -->
+<canvas-ui id="gen-canvas"></canvas-ui>
+<script type="module" src="/src/main.js"></script>
+```
+---
+### Harness checklist
+- [ ] `@adia-ai/web-modules/generative` imported (v0.6.7+ — registers
+      `canvas-ui` + `a2ui-root` + re-exports `registerResolver` in one barrel)
+- [ ] `registerResolver('api', ...)` wired before first generation trigger
+- [ ] `registerResolver('resource', ...)` wired for static lookup data
+- [ ] `canvas.reset()` called before each new generation (clears prior surface)
+- [ ] `canvas.pushVersion(msgs)` called after each successful generation (enables history)
+---