@kitn.ai/ui 0.26.0 → 0.28.0

package/llms.txt

@@ -1,7 +1,7 @@
 <!-- AUTO-GENERATED by scripts/gen-llms.mjs — do not edit by hand. Run `npm run build`. -->
 # @kitn.ai/ui
 
-> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 83 custom elements, every one prefixed `kai-` (e.g. `<kai-chat>`, `<kai-artifact>`): streaming responses, markdown + code rendering, reasoning/tool panels, attachments, conversation sidebar, voice input. Zero framework dependency for consumers; the SolidJS runtime it is authored in is bundled in, so the host needs nothing.
+> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 89 custom elements, every one prefixed `kai-` (e.g. `<kai-chat>`, `<kai-artifact>`): streaming responses, markdown + code rendering, reasoning/tool panels, attachments, conversation sidebar, voice input. Zero framework dependency for consumers; the SolidJS runtime it is authored in is bundled in, so the host needs nothing.
 
 ## Install
 
@@ -35,7 +35,7 @@ Drop an element into any framework (React, Vue, plain HTML). Data in via JS prop
 - `<kai-prompt-input>` — standalone composer with send button.
 
 **Layer 2 — composable primitives** (`import { … } from '@kitn.ai/ui'`):
-All 83 elements are also exported individually. Use them for custom layouts or features `<kai-chat>` does not expose (ChainOfThought, FeedbackBar, ThinkingBar, VoiceInput, …). Your bundler tree-shakes the rest.
+All 89 elements are also exported individually. Use them for custom layouts or features `<kai-chat>` does not expose (ChainOfThought, FeedbackBar, ThinkingBar, VoiceInput, …). Your bundler tree-shakes the rest.
 
 ## Key rules for the web components
 
@@ -149,7 +149,10 @@ For Tailwind builds: `@import "@kitn.ai/ui/theme.css"` in your CSS.
 
 ## Docs
 
-- Full element reference (all 83 elements, every prop/event): ./llms-full.txt — https://kitn.dev/llms-full.txt
+- Element reference (all 89 elements, every prop/event/method/slot/part): the "Element reference" section of ./llms-full.txt — https://kitn.dev/llms-full.txt
+- Programmatic layer (`@kitn.ai/ui/state` + `@kitn.ai/ui/wire`: streaming folds, the mock responder, the SSE readers/encoders): the "Programmatic layer" section of llms-full.txt
+- How to build a chat app in 5 steps (install → pick a layer → handle submit + stream → wire features → theme, with working code): the "How to build a chat app in 5 steps" section of llms-full.txt
+- Streaming recipe (the two rules that bite: reassign new references per chunk, fold deltas onto the trailing text part): the "Streaming recipe" section of llms-full.txt
 - Machine-readable Custom Elements Manifest: https://unpkg.com/@kitn.ai/ui/dist/custom-elements.json
 - Working examples: https://github.com/kitn-ai/ui/tree/main/examples
 - Storybook: https://storybook.kitn.dev

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitn.ai/ui",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "nx": {
     "name": "ui",
     "targets": {
@@ -116,6 +116,14 @@
       "types": "./dist/wire/index.d.ts",
       "default": "./dist/wire.js"
     },
+    "./define": {
+      "types": "./dist/define.d.ts",
+      "worker": "./dist/define.server.js",
+      "browser": "./dist/define.js",
+      "deno": "./dist/define.server.js",
+      "node": "./dist/define.server.js",
+      "default": "./dist/define.js"
+    },
     "./diagnostics": {
       "types": "./dist/diagnostics/index.d.ts",
       "default": "./dist/diagnostics.js"
@@ -162,16 +170,17 @@
   "scripts": {
     "prepublishOnly": "npm run build",
     "prebuild": "npm run build:css && npm run build:card-validation",
-    "build": "vite build --config vite.config.ts && vite build --config vite.config.provider.ts && vite build --config vite.config.react.ts && vite build --config vite.config.barrel.ts && vite build --config vite.config.barrel.server.ts && vite build --config vite.config.solid.ts && vite build --config vite.config.solid.server.ts && vite build --config vite.config.state.ts && vite build --config vite.config.wire.ts && vite build --config vite.config.diagnostics.ts && vite build --config vite.config.schemas.ts && vite build --config vite.config.mcp.ts && npm run build:elements && npm run verify:elements-bundle && npm run verify:react-wrappers && npm run verify:shader-lazy",
+    "build": "vite build --config vite.config.ts && vite build --config vite.config.provider.ts && vite build --config vite.config.react.ts && vite build --config vite.config.barrel.ts && vite build --config vite.config.barrel.server.ts && vite build --config vite.config.solid.ts && vite build --config vite.config.solid.server.ts && vite build --config vite.config.state.ts && vite build --config vite.config.wire.ts && vite build --config vite.config.define.ts && vite build --config vite.config.define.server.ts && vite build --config vite.config.diagnostics.ts && vite build --config vite.config.schemas.ts && vite build --config vite.config.mcp.ts && vite build --config vite.config.construct-cli.ts && npm run build:elements && npm run verify:elements-bundle && npm run verify:react-wrappers && npm run verify:shader-lazy",
     "build:elements": "node scripts/gen-elements-manifest.mjs && vite build --config vite.config.elements.ts && node scripts/gen-element-dts.mjs",
     "postbuild": "npm run build:theme && npm run build:api && npm run build:schemas && npm run build:subpath-dts && npm run verify:dts",
     "build:theme": "node scripts/build-theme-tokens.mjs",
-    "build:api": "node scripts/gen-elements-manifest.mjs && node scripts/gen-element-api.mjs && node scripts/gen-element-nonscalar.mjs && node scripts/gen-catalog.mjs",
+    "build:api": "node scripts/gen-elements-manifest.mjs && node scripts/gen-element-api.mjs && node scripts/gen-element-nonscalar.mjs && node scripts/gen-catalog.mjs && node scripts/gen-construct-schema.mjs",
     "build:schemas": "node scripts/copy-card-schemas.mjs",
     "build:card-validation": "node scripts/gen-card-validation-schemas.mjs",
     "build:subpath-dts": "node scripts/emit-subpath-dts.mjs",
     "verify:card-validation": "node scripts/gen-card-validation-schemas.mjs --self-test && node scripts/gen-card-validation-schemas.mjs --check",
     "verify:consumer": "node scripts/verify-consumer-sideeffects.mjs",
+    "verify:construct": "node scripts/verify-construct.mjs --self-test && node scripts/verify-construct.mjs",
     "verify:dts": "node scripts/verify-dts-boundaries.mjs --self-test && node scripts/verify-dts-boundaries.mjs",
     "verify:elements-bundle": "node scripts/verify-elements-bundle.mjs --self-test && node scripts/verify-elements-bundle.mjs",
     "verify:fresh": "node scripts/verify-artifact-fresh.mjs --self-test && node scripts/verify-artifact-fresh.mjs",
@@ -194,6 +203,7 @@
     "verify:starters": "node scripts/verify-starters.mjs",
     "lint:attachment-object-urls": "node scripts/lint-attachment-object-urls.mjs --self-test && node scripts/lint-attachment-object-urls.mjs",
     "lint:cdn-pins": "node scripts/lint-cdn-pins.mjs --self-test && node scripts/lint-cdn-pins.mjs --check-release-wiring && node scripts/lint-cdn-pins.mjs",
+    "lint:llms-size": "node scripts/lint-llms-size.mjs --self-test && node scripts/lint-llms-size.mjs",
     "lint:pack-parse": "node scripts/lint-pack-json-parse.mjs --self-test && node scripts/lint-pack-json-parse.mjs",
     "fix:cdn-pins": "node scripts/lint-cdn-pins.mjs --fix",
     "lint:silent-drops": "node scripts/lint-silent-drops.mjs --self-test && node scripts/lint-silent-drops.mjs",
@@ -220,7 +230,10 @@
     "test:slots-ivp": "playwright test --config playwright.slots.config.ts",
     "test:menu-ivp": "playwright test --config playwright.menu.config.ts",
     "test:command-ivp": "playwright test --config playwright.command.config.ts",
-    "test:focus-ring": "playwright test --config playwright.focus-ring.config.ts"
+    "test:focus-ring": "playwright test --config playwright.focus-ring.config.ts",
+    "test:input-mask-ivp": "playwright test --config playwright.input-mask.config.ts",
+    "test:message-text-token": "playwright test --config playwright.message-text-token.config.ts",
+    "test:content-brand-bleed": "playwright test --config playwright.content-brand-bleed.config.ts"
   },
   "dependencies": {
     "@floating-ui/dom": "^1.7.6",

package/src/agent-tooling/README.md

@@ -0,0 +1,192 @@
+# `agent-tooling/`
+
+The kit's machine-facing front door: everything that makes AI coding agents
+and CLIs fluent building with `@kitn.ai/ui`. It is packaging and tooling on
+top of the library, not part of it — `grep -rn "agent-tooling"
+packages/ui/src/components packages/ui/src/elements` returns no imports (only
+a code comment and a test's `UNSCANNED_DIRS` entry mention the directory by
+name). Nothing a consumer's chat UI renders depends on anything in here.
+
+## The four parts
+
+```
+                 ┌─────────────────────────┐
+                 │   kai MCP server (mcp/)  │
+                 │  construct · scaffold ·  │
+                 │  reference · theme ·     │
+                 │  debug                   │
+                 └───────┬─────────┬────────┘
+                         consumes  consumes
+                          │         │
+                          ▼         ▼
+              ┌────────────────┐ ┌──────────────────┐
+              │ construct/      │ │ catalog/          │
+              │ (schema→codegen │ │ (invariants,      │
+              │  →cli engine)   │ │  surfaces,        │
+              └────────▲────────┘ │  fabrications, …) │
+                       │          └───────────────────┘
+                  standalone,
+                  no MCP involved
+                       │
+              ┌────────┴────────┐
+              │ bin/mcp.js CLI   │
+              │ validate/dev/    │
+              │ compile/eject    │
+              └──────────────────┘
+```
+
+- **`mcp/`** — the `kai` MCP server. The tools in `mcp/tools/`:
+  - `construct.ts` — turn-by-turn authoring of a construct JSON file (one
+    JSON file → one web component); stateless, the harness owns the file.
+  - `scaffold.ts` — generates a full chat integration (framework + backend
+    route + integration wiring) from `agent-tooling/registry.ts` and
+    `agent-tooling/archetypes.ts` (backed by `agent-tooling/integrations/`).
+  - `reference.ts` — component/element/card lookup for an agent deciding what
+    to use.
+  - `theme.ts` — produces a `--kai-*` CSS token override block from a brand
+    color or description, resolved against the kit's own `theme.css`.
+  - `debug.ts` — diagnoses common `kai-*` integration failures from a
+    symptom/snippet, sourced from `apps/docs/src/content/docs/guides/for-ai-agents.mdx`.
+- **`construct/`** — the construct engine: a declarative JSON format compiled
+  to a self-registering web component. Pipeline is `schema.ts` (Zod, single
+  source of truth) → `codegen.ts` (the one generation path — `kai dev`,
+  `kai compile`, and `kai eject` all call the same `generateProject`) →
+  `cli.ts` (the `validate | eject | dev | compile` subcommands). Fixtures
+  live in `construct/fixtures/` (`demo-widget`, `ops-console`,
+  `owner-widget`). The published JSON Schema artifact is
+  `construct/construct.v1.schema.json`, mirrored byte-identical at
+  `apps/docs/public/schemas/construct/v1.json`; both are guarded against
+  drift from the Zod source by `construct/schema-artifact.test.ts` (asserts
+  the checked-in artifact equals `z.toJSONSchema(ConstructSchema)` right now)
+  and regenerated by `scripts/gen-construct-schema.mjs` via `build:api`.
+- **`catalog/`** — Zod-typed reference data, mostly independent of the
+  construct engine, each file feeding a specific consumer:
+  - `catalog-types.ts` — the shared Zod types (`SurfaceArchetype`,
+    `DeliveryTarget`, `WireReader`, `Backend`, …) the rest of the catalog is
+    built from.
+  - `invariants.ts` — the composition invariants an agent must hold, each
+    with an `enforcedBy` path and a `lint` script name; feeds
+    `invariants.test.ts` and the acceptance harness.
+  - `surfaces.ts` — the sorted inventory of product-shaped surfaces vs.
+    ingredients vs. corpus; feeds `surfaces.test.ts` and `derived.json`.
+  - `fabrications.ts` — tags agents have invented while working from an
+    acceptance pack (and what they should have used instead); renders the
+    pack's `FABRICATED.md`, checked against `derived.json` in both directions
+    by `fabrications.test.ts`.
+  - `scenarios.ts` — the acceptance deck (spec §6): prompts + what each
+    needs, written before the catalog it measures.
+  - `labs-titles.ts` — parses the real `Labs/…` story titles registered by
+    story files (TypeScript AST, not a regex), used to keep the catalog's
+    story inventory honest.
+  - `derived.json` — generated inventory of elements/props read by
+    `catalog-types.ts`, `fabrications.ts`, and `surfaces.ts` (and their
+    tests) rather than by anything outside the catalog.
+  - `catalog/README.md` — the catalog's own deeper documentation.
+
+How they relate: the MCP's `construct` and `scaffold` tools **consume** the
+construct engine and the catalogs — they don't reimplement authoring logic,
+they call into `construct/schema.ts` / `construct/codegen.ts` and read the
+registry/catalog data. The construct CLI (`bin/mcp.js validate|dev|compile|eject`,
+built from `construct/cli-entry.ts` → `dist/construct-cli.es.js`) runs the
+engine standalone, with no MCP server involved at all.
+
+## Usage
+
+- **`npx @kitn.ai/ui mcp`** starts the MCP server (the historical default
+  subcommand). For wiring it into a multi-harness setup, see the docs site's
+  agents guide: `apps/docs/src/content/docs/guides/for-ai-agents.mdx`.
+- **CLI form**, no MCP: `node bin/mcp.js validate|dev|compile|eject <construct.json>`
+  (`bin/mcp.js` dispatches `dev`/`compile`/`eject`/`validate` to the construct
+  CLI and anything else, including `mcp` or no argument, to the MCP server;
+  an unrecognized subcommand is a loud error, not a silent fallthrough).
+  `eject` writes a real Solid project you own; `dev` gives a live-reload
+  preview; `compile` emits one self-registering `.js`.
+- **Acceptance harness** (`packages/ui/scripts/acceptance-*.mjs`:
+  `acceptance-pack.mjs`, `acceptance-run.mjs`, `acceptance-eval.mjs`,
+  `acceptance-gate-compiles.mjs`) — builds and grades a coding agent's
+  from-scratch attempt at using the catalog with no kit source, per the
+  scenarios in `catalog/scenarios.ts`; this is how the catalog's own claims
+  get checked against a real agent rather than asserted.
+
+## Worked example
+
+`construct/fixtures/owner-widget.construct.json`, field by field:
+
+- `"$schema"` — points at the published schema URL for editor validation.
+- `"name": "acme-support"` — the construct's name; also the emitted custom
+  element's tag basis.
+- `"layout": "widget"` — a floating launcher widget, not full-screen or docked.
+- `"provider": { "mode": "mock" }` — no backend; canned responses (vs.
+  `mode: "endpoint"`, the consumer's own chat route).
+- `"userId": "user_123"` — the identity value threaded through for
+  history/persistence.
+- `"header": { "title": "Acme Support" }` — the chat header's title text.
+- `"theme": { "unreadColor": "#38BDF8" }` — one branded token override.
+- `"empty": { "title": ..., "description": ... }` — the empty-state copy
+  shown before the first message.
+- `"widget": { "position": "top-start", "defaultOpen": true }` — widget-layout
+  placement and initial open state.
+- `"capabilities.attachments.accept"` — allowed MIME patterns for uploads.
+- `"capabilities.history.persistence": "local"` — history persisted in the
+  browser, not the consumer's backend.
+- `"capabilities.starters"` — suggested first prompts.
+- `"capabilities.reasoningOpen": true` — reasoning panels start expanded.
+- `"capabilities.conversations": true` — enables the conversations sidebar.
+
+`codegen.ts` turns this into a small, deterministic (no dates, no randomness,
+fixed key order) Solid project: pure Solid interior composing
+`@kitn.ai/ui/solid` components, provider glue built on `@kitn.ai/ui/state` +
+`@kitn.ai/ui/wire` (never a hand-rolled SSE reader), and one
+`defineWebComponent` facade carrying the tag, theme default, and slots. The
+facade injects the kit's compiled CSS into the shadow root, so the generated
+project needs no Tailwind and no CSS build step. `kai dev`, `kai compile`,
+and `kai eject` all go through this same generation path — the preview is
+the artifact, there is no separate interpreter to drift from it.
+
+## Rules that bind changes here
+
+- **Vocabulary never logic** — the construct format has no handlers and no
+  expressions; it describes, it doesn't script. `schema.ts` is `.strict()`
+  everywhere, so an unknown key is a loud rejection.
+- **Widen, never restructure `schema.ts`** — it's the single source of truth;
+  never hand-edit the generated JSON Schema artifacts or restate an enum
+  elsewhere, read it off `ConstructSchema.shape` or the generated artifact.
+- **Derive, don't type** — the published schema artifact is generated from
+  Zod (`scripts/gen-construct-schema.mjs`, run by `build:api`) and pinned by
+  `construct/schema-artifact.test.ts`; `verify:construct`'s layout and
+  capability axes are read off that same drift-guarded artifact rather than
+  hand-listed, so adding a layout or capability to the Zod schema moves what
+  the gate covers on its own.
+- **`verify:construct`** (`scripts/verify-construct.mjs`) drives the real CLI
+  end to end against this checkout's own packed tarball — eject, install,
+  compile under the emitted tsconfig, build, and bundle inside a real
+  consumer app — for every layout/capability combination the schema
+  currently declares. No unit test in this tree leaves the process; this is
+  the one that does.
+- **`verify:scaffold`** (`scripts/verify-scaffold-compiles.mjs`) compiles the
+  scaffolder's emitted front ends and backend routes under `tsc --strict`
+  across the integration × surface × framework axes derived from the
+  registry, plus structural checks (e.g. the Solid emit branches on every
+  `MessagePart` variant).
+- **`verify:generated`** (`scripts/verify-generated-sync.mjs`) re-runs
+  `build:api` and fails if any derived artifact in the tree (including
+  catalog/manifest files this directory reads) differs from what the
+  generator produces right now — catches drift `nx build ui`'s NX cache can
+  hide.
+- **The schema-artifact test pair** (`construct/schema-artifact.test.ts`)
+  catches a `schema.ts` edit that shipped without a regen, in the unit suite
+  itself rather than only in CI's `verify:generated`.
+
+## Where deeper docs live
+
+- Repo root [`CLAUDE.md`](../../../../CLAUDE.md)'s **Map** section for how
+  this directory sits relative to `primitives/`, `ui/`, `components/`, and
+  `elements/`.
+- [`.claude/README.md`](../../../../.claude/README.md) for the project-local
+  skills/agents that exercise this tooling (notably `/consumer-regression`).
+- The docs site's agents guide,
+  `apps/docs/src/content/docs/guides/for-ai-agents.mdx` — the rules
+  `debug.ts` and the MCP's contract enforcement are sourced from.
+- `docs/superpowers/specs/2026-08-25-construct-engine-design.md` — the
+  construct engine's design spec (decisions ledger, format rules, success
+  criteria).

package/src/agent-tooling/catalog/invariants.ts

@@ -142,9 +142,9 @@ export const invariants: TInvariant[] = [
     ],
     examples: [
       {
-        wrong: 'chat.conversations = rows;',
+        wrong: 'chat.conversationRows = rows;',
         right: 'conversations.conversations = rows;',
-        note: 'kai-chat has no conversations prop — the sidebar is its own element. One element never holds the whole app state.',
+        note: "kai-chat's own `conversations` prop is a boolean flag (turns the built-in list panel on); it has no `conversationRows`-shaped data prop, and the sidebar is its own element. One element never holds the whole app state.",
       },
       {
         wrong: "chat.addEventListener('kai-conversation-select', (e) => load(e.detail.id));",
@@ -199,7 +199,7 @@ export const invariants: TInvariant[] = [
         wrong: "window.open(card.url, '_blank');",
         right:
           "const isNavigable = (u) => { try { return ['http:', 'https:', 'mailto:'].includes(new URL(u, location.href).protocol); } catch { return false; } };\nif (isNavigable(card.url)) window.open(card.url, '_blank', 'noopener,noreferrer');",
-        note: "THE try/catch IS NOT OPTIONAL: new URL() THROWS on an unparseable input like 'http://[', and an uncaught throw here crashes the render instead of blocking the link — worse than the bug you are fixing. Returning false is the whole contract. Resolving against location.href is deliberate: a relative or fragment href inherits http: and is allowed, which is what makes ordinary links keep working. REPO-INTERNAL ONLY: contributors inside this package use isSafeUrl/SAFE_SCHEMES from src/primitives/card-routing.ts, which has this exact shape — neither is reachable from the published package, so never emit an import for them.",
+        note: "THE try/catch IS NOT OPTIONAL: new URL() THROWS on an unparseable input like 'http://[', and an uncaught throw here crashes the render instead of blocking the link — worse than the bug you are fixing. Returning false is the whole contract. Resolving against location.href is deliberate: a relative or fragment href inherits http: and is allowed, which is what makes ordinary links keep working. REPO-INTERNAL ONLY: contributors inside this package use isSafeUrl/SAFE_SCHEMES from src/primitives/url-scheme-policy.ts (re-exported from src/primitives/card-routing.ts for the existing call sites), which has this exact shape — neither is reachable from the published package, so never emit an import for them.",
       },
       {
         wrong: '<a href={source.url}>{source.title}</a>',

package/src/agent-tooling/catalog/surfaces.ts

@@ -239,6 +239,78 @@ export const surfaceRecipes: TSurfaceRecipe[] = [
     ],
     corpus: ['packages/ui/README.md'],
   },
+  {
+    // The hand-composed thread (rung-6 F-49): kai-chat deliberately absent —
+    // kai-thread renders the transcript, kai-composer takes input, and the
+    // HOST is every line of wiring between them. This record is the catalog
+    // half; the full compiling host module is the `composed-thread` CODE
+    // recipe (../recipes/composed-thread.ts, served by component_reference
+    // { name: "composed-thread" } and compiled by verify:scaffold), which is
+    // also this record's corpus. Ingredients with no wiring edge below are
+    // still real members of the composition: kai-feedback-bar's events
+    // terminate in the host rather than setting another element's property.
+    // (kai-conversation-item used to be in that list as "presentational
+    // standalone"; since F-45 tier 2 a standalone row activates itself, so
+    // the rail is a real kai-select edge below.)
+    id: 'composed-thread',
+    intent:
+      'A full chat surface composed by hand from standalone elements — no <kai-chat>. ' +
+      'The host module owns the store, streams through createAssistantStream + the wire ' +
+      'reader, stages attachments as data: URIs, and drives the toast region as data.',
+    archetypes: ['full-screen'],
+    targets: ['bundler'],
+    ingredients: [
+      'kai-thread',
+      'kai-composer',
+      'kai-attachments',
+      'kai-toast-region',
+      'kai-conversation-item',
+      'kai-feedback-bar',
+    ],
+    backend: { endpoint: 'consumer-owned', reader: 'readOpenAIStream' },
+    wiring: [
+      {
+        from: 'kai-composer',
+        event: 'kai-submit',
+        to: 'kai-thread',
+        property: 'messages',
+        note: 'detail is {doc, text, entities} — read detail.text (NOT detail.value, which is kai-chat/kai-prompt-input\'s shape). The host appends the user turn plus any staged file parts and assigns a NEW array; the reply then streams onto the same property via createAssistantStream',
+      },
+      {
+        from: 'kai-attachments',
+        event: 'kai-remove',
+        to: 'kai-attachments',
+        property: 'items',
+        note: 'detail is {id}; the tray never mutates its own list — the host filters and reassigns items, and a data: URI needs no revocation on removal (attachment-blob-url is the rule this recipe corrects: F-44)',
+      },
+      {
+        from: 'kai-toast-region',
+        event: 'kai-dismiss',
+        to: 'kai-toast-region',
+        property: 'toasts',
+        note: 'detail is {id}; the region is driven as DATA because this app places its own and owns the array — the imperative toast() would ADOPT this markup-placed region (it mounts its own only when none exists) and bind its store over the toasts property, so pick one API per region',
+      },
+      {
+        from: 'kai-conversation-item',
+        event: 'kai-select',
+        to: 'kai-thread',
+        property: 'messages',
+        note: 'detail is {id}; STANDALONE rows only (F-45 tier 2) — outside <kai-conversations> the row body is a tabbable button and click / Enter / Space fire kai-select on the item (non-bubbling: listen on the row). Inside a container this never fires; the container\'s kai-conversation-select is the one activation event. The container\'s list story (roving tabindex, arrow keys) stays the host\'s job in a hand-rolled rail',
+      },
+    ],
+    invariants: [
+      'reactivity-two-halves',
+      'props-not-attributes',
+      'events-non-bubbling',
+      'host-coordinates',
+      'kit-parses-consumer-fetches',
+      'untrusted-model-output',
+    ],
+    corpus: [
+      'packages/ui/src/agent-tooling/recipes/composed-thread.ts',
+      'packages/ui/src/agent-tooling/catalog/surfaces.test.ts',
+    ],
+  },
 ];
 
 /**

package/src/agent-tooling/construct/cli-entry.ts

@@ -0,0 +1,8 @@
+/** Build entry for dist/construct-cli.es.js (vite.config.construct-cli.ts).
+ *  bin/mcp.js imports this with the subcommand argv; process handling stays in
+ *  the bin (this file stays free of exit calls, same split as mcp/stdio.ts). */
+import { runCli } from './cli';
+
+runCli(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+});

package/src/agent-tooling/construct/cli.ts

@@ -0,0 +1,147 @@
+/**
+ * The kai construct CLI: validate | eject | dev | compile.
+ * Launched by bin/mcp.js (the package's one bin) via dist/construct-cli.es.js.
+ * Every subcommand goes through validateConstruct first — a validation failure
+ * never reaches codegen; the problems print with paths and the exit code says so.
+ */
+import { readFileSync, mkdirSync, copyFileSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { validateConstruct, type Construct } from './schema';
+import { accentContrastNotice, emitTypes, generateProject, writeProject } from './codegen';
+
+export interface CliIo {
+  log: (s: string) => void;
+  error: (s: string) => void;
+}
+
+const defaultIo: CliIo = { log: (s) => console.log(s), error: (s) => console.error(s) };
+
+const USAGE = `usage: kai <command>
+
+  kai validate <construct.json>          check a construct, print problems with paths
+  kai eject <construct.json> <outDir>    write the generated Solid project (it's yours)
+  kai dev <construct.json>               live preview with reload-on-edit (Task 5)
+  kai compile <construct.json> [outDir]  one self-registering .js (Task 6)
+`;
+
+/** H-3, decide loudly: `home.recentConversation` renders nothing without
+ *  `capabilities.conversations` to draw the card from — never fatal (the
+ *  schema explicitly does NOT require conversations for `home`, see
+ *  schema.ts's own doc on `home`), just a non-blocking heads-up at validate
+ *  time, the same idiom `validate`'s success line already uses (io.log, not
+ *  a bare console call). Extracted so it can be unit-tested without going
+ *  through the CLI's stdout wiring. */
+export function homeRecentConversationWarning(construct: Construct): string | null {
+  if (construct.home?.recentConversation && !construct.capabilities?.conversations) {
+    return 'warning: home.recentConversation is set but capabilities.conversations is not — the recent-conversation card will render nothing without it.';
+  }
+  return null;
+}
+
+export function loadConstruct(path: string, io: CliIo): Construct | null {
+  const abs = resolve(path);
+  let raw: string;
+  try {
+    raw = readFileSync(abs, 'utf8');
+  } catch {
+    io.error(`cannot read ${abs}`);
+    return null;
+  }
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    io.error(`${abs} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+  const out = validateConstruct(json);
+  if (!out.ok) {
+    io.error(`${abs} is not a valid construct:`);
+    for (const p of out.problems) io.error(`  ${p.path || '(root)'}: ${p.message}`);
+    return null;
+  }
+  return out.construct;
+}
+
+/** `--ui <spec>` extraction shared by `dev` and `compile`. NB: guard the -1
+ *  case — `i !== uiFlag + 1` with uiFlag === -1 would drop index 0. */
+function parseUiFlag(rest: string[]): { uiSpec: string | undefined; positional: string[] } {
+  const uiFlag = rest.indexOf('--ui');
+  const uiSpec = uiFlag >= 0 ? rest[uiFlag + 1] : undefined;
+  const positional = uiFlag >= 0 ? rest.filter((_, i) => i !== uiFlag && i !== uiFlag + 1) : rest;
+  return { uiSpec, positional };
+}
+
+export async function runCli(argv: string[], io: CliIo = defaultIo): Promise<number> {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case 'validate': {
+      const construct = loadConstruct(rest[0] ?? '', io);
+      if (!construct) return 1;
+      io.log(`valid construct: <${construct.name}> (layout: ${construct.layout}, provider: ${construct.provider.mode})`);
+      const warning = homeRecentConversationWarning(construct);
+      if (warning) io.log(warning);
+      return 0;
+    }
+    case 'eject': {
+      const { uiSpec, positional } = parseUiFlag(rest);
+      const [path, outDir] = positional;
+      if (!path || !outDir) {
+        io.error(USAGE);
+        return 2;
+      }
+      const construct = loadConstruct(path, io);
+      if (!construct) return 1;
+      const overwritten = writeProject(generateProject(construct, { uiSpec }), resolve(outDir));
+      if (overwritten.length > 0) {
+        io.log(`overwriting ${overwritten.length} existing file(s)`);
+      }
+      const notice = accentContrastNotice(construct);
+      if (notice) io.log(notice);
+      io.log(`ejected <${construct.name}> to ${resolve(outDir)} — npm install && npm run dev. The source is yours.`);
+      return 0;
+    }
+    case 'dev': {
+      const { uiSpec, positional } = parseUiFlag(rest);
+      const path = positional[0];
+      if (!path) {
+        io.error(USAGE);
+        return 2;
+      }
+      const { dev } = await import('./dev');
+      await dev(path, { io, uiSpec });
+      return 0; // unreachable; dev() never resolves
+    }
+    case 'compile': {
+      const { uiSpec, positional } = parseUiFlag(rest);
+      const [path, outArg] = positional;
+      if (!path) {
+        io.error(USAGE);
+        return 2;
+      }
+      const construct = loadConstruct(path, io);
+      if (!construct) return 1;
+      const outDir = resolve(outArg ?? 'dist-construct');
+      const { workDirFor, ensureInstalled } = await import('./dev');
+      const dir = workDirFor(construct.name, process.cwd());
+      const files = generateProject(construct, { uiSpec });
+      writeProject(files, dir);
+      await ensureInstalled(dir, files, io);
+      await new Promise<void>((done, fail) => {
+        const child = spawn('npm', ['run', 'build'], { cwd: dir, stdio: 'inherit' });
+        child.on('exit', (code) => (code === 0 ? done() : fail(new Error(`vite build exited ${code}`))));
+      });
+      mkdirSync(outDir, { recursive: true });
+      copyFileSync(join(dir, 'dist', `${construct.name}.js`), join(outDir, `${construct.name}.js`));
+      writeFileSync(join(outDir, `${construct.name}.d.ts`), emitTypes(construct));
+      writeProject(files, join(outDir, 'source'));
+      io.log(`compiled <${construct.name}> → ${outDir}/${construct.name}.js (source beside it in source/).`);
+      io.log(`endpoint backends: the kai MCP scaffold tool emits a matching route — see its output for your framework.`);
+      return 0;
+    }
+    default:
+      io.error(USAGE);
+      return 2;
+  }
+}