@kitn.ai/ui 0.28.0 → 0.29.0

package/dist/mcp.es.js

@@ -9331,7 +9331,7 @@ const RULES = [
       t
     ),
     title: "tsc errors inside node_modules/@kitn.ai/ui/src (SolidJS source compiled under React)",
-    cause: "The package currently ships TypeScript/TSX source, and a type entry value-re-exports from it, so the consumer's `tsc` resolves and compiles the library's SolidJS internals (`src/ui/*.tsx`) under the app's React JSX config — `Show`/`Portal`/`Dynamic` aren't React components, causing TS2786 / \"cannot be used as a JSX component\" errors. `vite`/esbuild build fine (they strip types); only `tsc` breaks. `skipLibCheck` does not help (these are `.tsx` source, not `.d.ts`).",
+    cause: "On versions <=0.27.x, the package shipped TypeScript/TSX source, and a type entry value-re-exports from it, so the consumer's `tsc` resolves and compiles the library's SolidJS internals (`src/ui/*.tsx`) under the app's React JSX config — `Show`/`Portal`/`Dynamic` aren't React components, causing TS2786 / \"cannot be used as a JSX component\" errors. `vite`/esbuild build fine (they strip types); only `tsc` breaks. `skipLibCheck` does not help (these are `.tsx` source, not `.d.ts`). Fixed for newer releases: the package no longer ships that source tree (`files` in package.json narrowed to `dist/` plus two reachable JSON exports) — if you're still hitting this, check your installed version first (`npm ls @kitn.ai/ui`) and upgrade before reaching for the workaround below.",
     fix: 'Redirect the type resolution for that subpath in your tsconfig (Vite ignores tsconfig `paths`, so runtime is unaffected):\n\n```jsonc\n// tsconfig (app)\n"baseUrl": ".",\n"paths": { "@kitn.ai/ui/elements": ["./src/stubs/kitn-elements.d.ts"] }\n```\n\n```ts\n// src/stubs/kitn-elements.d.ts\nexport {}\n```\n\n(This is a known packaging gap being tracked upstream.)'
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitn.ai/ui",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "nx": {
     "name": "ui",
     "targets": {
@@ -68,7 +68,8 @@
   "jsdelivr": "./dist/kai.es.js",
   "customElements": "dist/custom-elements.json",
   "bin": {
-    "kai-mcp": "./bin/mcp.js"
+    "kai-mcp": "./bin/mcp.js",
+    "kai": "./bin/mcp.js"
   },
   "exports": {
     ".": {
@@ -133,6 +134,10 @@
       "default": "./dist/schemas.js"
     },
     "./schemas/*": "./dist/schemas/*",
+    "./construct": {
+      "types": "./dist/agent-tooling/construct/public.d.ts",
+      "default": "./dist/construct.js"
+    },
     "./provider": {
       "types": "./dist/remote/provider.d.ts",
       "default": "./dist/kai-provider.es.js"
@@ -142,25 +147,19 @@
     "*": {
       "schemas": [
         "./dist/schemas/index.d.ts"
+      ],
+      "construct": [
+        "./dist/agent-tooling/construct/public.d.ts"
       ]
     }
   },
   "files": [
     "dist",
-    "src",
+    "src/elements/element-meta.json",
+    "src/elements/icon-names.json",
     "bin",
-    "!src/**/*.stories.tsx",
-    "!src/**/*.test.ts",
-    "!src/**/*.test.tsx",
-    "!src/**/*.testlib.ts",
+    "!bin/**/*.test.js",
     "!dist/**/*.testlib.*",
-    "!src/**/*.mdx",
-    "!src/stories",
-    "!src/wire/fixtures",
-    "!src/agent-tooling/catalog/derived.json",
-    "!src/elements/logos",
-    "!src/elements/card-media.jpg",
-    "!src/elements/video-poster.jpg",
     "frameworks",
     "theme.css",
     "llms.txt",
@@ -170,7 +169,7 @@
   "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.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": "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 && vite build --config vite.config.construct.ts && npm run build:elements && npm run dedupe:shiki && 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",
@@ -193,13 +192,14 @@
     "gate:compiles:self-test": "node scripts/acceptance-gate-compiles.mjs --self-test",
     "verify:schemas": "node scripts/verify-schemas-exported.mjs --self-test && node scripts/verify-schemas-exported.mjs",
     "verify:shader-lazy": "node scripts/verify-shader-lazy.mjs --self-test && node scripts/verify-shader-lazy.mjs",
+    "dedupe:shiki": "node scripts/dedupe-shiki-chunks.mjs --self-test && node scripts/dedupe-shiki-chunks.mjs",
     "verify:solid-coverage": "node scripts/verify-solid-coverage.mjs --self-test && node scripts/verify-solid-coverage.mjs",
     "verify:tool-schemas": "node scripts/verify-tool-schemas.mjs",
     "verify:ssr": "node scripts/verify-ssr-imports.mjs && node scripts/verify-ssr-render.mjs",
     "verify:diagnostics-wiring": "node scripts/verify-diagnostics-wiring.mjs",
     "verify:ssr:imports": "node scripts/verify-ssr-imports.mjs",
     "verify:ssr:render": "node scripts/verify-ssr-render.mjs",
-    "verify:pack": "node scripts/verify-pack-weight.mjs",
+    "verify:pack": "node scripts/verify-pack-weight.mjs --self-test && node scripts/verify-pack-weight.mjs",
     "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",

package/bin/route.test.js

@@ -1,58 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { execFileSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { decideEntry, CONSTRUCT_COMMANDS, KNOWN_COMMANDS } from './route.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const binPath = join(__dirname, 'mcp.js');
-
-describe('decideEntry (pure routing decision)', () => {
-  it('no args -> mcp (byte-compatible historical behavior)', () => {
-    expect(decideEntry(undefined)).toEqual({ kind: 'mcp' });
-  });
-
-  it('"mcp" -> mcp (byte-compatible historical behavior)', () => {
-    expect(decideEntry('mcp')).toEqual({ kind: 'mcp' });
-  });
-
-  it.each(CONSTRUCT_COMMANDS)('%s -> construct', (cmd) => {
-    expect(decideEntry(cmd)).toEqual({ kind: 'construct' });
-  });
-
-  it('unknown/typo\'d command -> error naming the valid commands', () => {
-    const decision = decideEntry('frobnicate');
-    expect(decision.kind).toBe('error');
-    for (const known of KNOWN_COMMANDS) {
-      expect(decision.message).toContain(known);
-    }
-  });
-});
-
-describe('bin/mcp.js dispatcher (spawned, real process)', () => {
-  it('unknown subcommand exits 2 with stderr naming valid commands, never falling through to the server', () => {
-    let status = 0;
-    let stderr = '';
-    try {
-      execFileSync('node', [binPath, 'frobnicate'], { timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-    } catch (err) {
-      status = err.status;
-      stderr = err.stderr;
-    }
-    expect(status).toBe(2);
-    expect(stderr).toMatch(/valid commands/i);
-  });
-
-  it('a typo\'d valid-ish command (validat) also exits 2, not a hang', () => {
-    let status = 0;
-    let stderr = '';
-    try {
-      execFileSync('node', [binPath, 'validat'], { timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-    } catch (err) {
-      status = err.status;
-      stderr = err.stderr;
-    }
-    expect(status).toBe(2);
-    expect(stderr).toMatch(/valid commands/i);
-  });
-});

package/src/agent-tooling/README.md

@@ -1,192 +0,0 @@
-# `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/archetypes.ts

@@ -1,205 +0,0 @@
-import type { Archetype } from './types';
-
-/**
- * The archetypes are PRESETS over a components list, not the surface axis.
- *
- * `renderSurface({ framework, components, integration })` renders any components
- * list; each entry below is a named point in that space plus a default placement.
- * Read the table as "components + placement" and the CLI's feature multi-select
- * falls out of it: placement is the layout question, `components` is the features.
- *
- * Adding an entry here adds a PRESET. It does not add a capability, and it is not
- * how a new component reaches the renderers — that is `components` at the call
- * site. See `listCapabilityGroups` below for what this catalog does still decide.
- */
-export const archetypes: Archetype[] = [
-  {
-    id: 'drop-in-chat',
-    title: 'Drop-in chat',
-    components: ['kai-chat'],
-    defaultPlacement: 'full-page',
-    docsSlug: 'examples/drop-in-chat',
-  },
-  {
-    id: 'support-widget',
-    title: 'Support widget',
-    components: ['kai-chat'],
-    defaultPlacement: 'docked-widget',
-    docsSlug: 'examples/support-widget',
-  },
-  {
-    id: 'knowledge-base',
-    title: 'Knowledge base / RAG',
-    components: ['kai-chat', 'kai-sources'],
-    defaultPlacement: 'full-page',
-    docsSlug: 'examples/knowledge-base',
-  },
-  {
-    id: 'agentic',
-    title: 'Agentic assistant',
-    components: ['kai-chat', 'kai-tool', 'kai-reasoning'],
-    defaultPlacement: 'side',
-    docsSlug: 'examples/agentic-assistant',
-  },
-  /**
-   * THE FIRST OFFICIAL BLOCK (recast spec 2026-08-20 § 3b; F-16).
-   *
-   * This preset used to carry `kai-artifact` + `kai-resizable` — an UNWIRED
-   * artifact split — while omitting the conversation rail, the one thing its
-   * name promised (rung-3 finding F-16). It now names the workspace BLOCK: the
-   * chat-agnostic `kai-workspace` layout shell, a WIRED `kai-conversations`
-   * rail, `kai-chat` in the main region, and the `@kitn.ai/ui/state` thread
-   * helpers (bindThreadMessages / createThreadSessions / createSaveScheduler /
-   * parseStoredThread) with the persistence POLICY left in consumer-owned
-   * lines. `examples/apps/workspace/` is the block's reference implementation.
-   *
-   * The artifact split did not vanish — it moved to `artifact-split` below, so
-   * its renderer branch keeps its cells in `verify:scaffold`.
-   */
-  {
-    id: 'workspace',
-    title: 'Agentic workspace',
-    components: ['kai-chat', 'kai-workspace', 'kai-conversations'],
-    defaultPlacement: 'full-page',
-    docsSlug: 'examples/workspace',
-  },
-  /**
-   * THE PRESET THAT KEEPS A CAPABILITY ON THE AXIS — the same reason the
-   * `attachments` preset exists (see its comment below): `listCapabilityGroups`
-   * derives the gate's surface axis from this table, so when the recast moved
-   * the artifact pair off `workspace`, this entry is what kept
-   * `kai-artifact`+`kai-resizable` compiling in `verify:scaffold` instead of
-   * silently losing every cell. The pair is ONE capability because `isArtifactSplit`
-   * in scaffold.ts requires both: a split with no preview pane is an empty
-   * panel, and a preview with no split has nowhere to sit.
-   */
-  {
-    id: 'artifact-split',
-    title: 'Artifact preview split',
-    components: ['kai-chat', 'kai-artifact', 'kai-resizable'],
-    defaultPlacement: 'side',
-    docsSlug: 'examples/workspace',
-  },
-  {
-    id: 'voice',
-    title: 'Voice assistant',
-    components: ['kai-chat', 'kai-voice-input'],
-    defaultPlacement: 'full-page',
-    docsSlug: 'examples/voice-assistant',
-  },
-  /**
-   * THE PRESET THAT EXISTS TO MAKE A CAPABILITY REACHABLE, not to name a product
-   * shape someone asked for.
-   *
-   * `kai-file-upload` and `kai-attachments` were registered elements that NO
-   * preset composed, and `listCapabilityGroups` derives its answer from this
-   * table — so the attachments capability reached neither `listSurfaceProbes`
-   * nor `verify:scaffold`, and `renderSurface` had no branch that emitted either
-   * tag. A caller could pass them in `components` (the axis takes any list) and
-   * get two bare `<kai-file-upload></kai-file-upload>` / `<kai-attachments>`
-   * siblings with nothing wired to them: on screen, inert, silent.
-   *
-   * The pair is ONE capability for the same reason `kai-artifact` +
-   * `kai-resizable` are: a dropzone with no list is a black hole, and a list
-   * with no dropzone can never fill. `hasAttachments` in scaffold.ts requires
-   * both for exactly that reason.
-   *
-   * The components match the create-kai spec's own feature table
-   * (`attachments` -> `kai-file-upload`, `kai-attachments`), so the CLI's
-   * multi-select and this preset name the same surface rather than two.
-   */
-  {
-    id: 'attachments',
-    title: 'File attachments',
-    components: ['kai-chat', 'kai-file-upload', 'kai-attachments'],
-    defaultPlacement: 'full-page',
-    docsSlug: 'examples/attachments',
-  },
-];
-
-/** The component every surface composes around, so never a capability by itself. */
-export const BASE_COMPONENT = 'kai-chat';
-
-/** One capability: the components a preset adds on top of `BASE_COMPONENT`. */
-export interface CapabilityGroup {
-  /** derived from the components, e.g. `tool+reasoning` — not a preset name */
-  id: string;
-  components: string[];
-}
-
-/**
- * The distinct capabilities the presets know about, DERIVED from them.
- *
- * A capability is one preset's components minus `kai-chat`, deduped across the
- * catalog (run `listCapabilityGroups()` for the current list — `drop-in-chat`
- * and `support-widget` collapse onto the same empty capability because both add
- * nothing and differ only in `defaultPlacement`).
- *
- * Derived rather than listed for the reason the verify script's other axes are:
- * a hand-written list would have to be edited by the same hand that adds a
- * preset, so a new capability could land with nothing covering it and nothing
- * failing to say so. Registering a preset whose components are new moves the
- * cell count in `verify:scaffold` by itself.
- *
- * The grouping is real and not an artifact of the derivation: `kai-tool` and
- * `kai-reasoning` are one capability because a tool panel with no reasoning
- * disclosure is not a surface anyone asks for, `kai-artifact` /
- * `kai-resizable` are one because `isArtifactSplit` in scaffold.ts only fires when BOTH are present
- * — split them and the renderer emits a bare artifact with no pane to put it in
- * — and `kai-file-upload` / `kai-attachments` are one because `hasAttachments`
- * fires the same way, for the same kind of reason.
- */
-export function listCapabilityGroups(): CapabilityGroup[] {
-  const seen = new Map<string, CapabilityGroup>();
-  for (const a of archetypes) {
-    const components = a.components.filter((c) => c !== BASE_COMPONENT);
-    if (components.length === 0) continue;
-    const key = [...components].sort().join(',');
-    if (seen.has(key)) continue;
-    seen.set(key, { id: components.map((c) => c.replace(/^kai-/, '')).join('+'), components });
-  }
-  return [...seen.values()];
-}
-
-/** One surface the scaffolder's gate compiles across every integration × framework. */
-export interface SurfaceProbe {
-  id: string;
-  components: string[];
-}
-
-/**
- * The surface axis for `verify:scaffold`: each capability ALONE, plus none, plus
- * ALL of them.
- *
- * WHY THESE AND NOT THE PRESETS. The presets are seven cells covering six
- * distinct components lists (`support-widget` repeats `drop-in-chat`'s, and the
- * matrix holds `placement` at one value, so that pair compiled the same types
- * twice). More importantly they cover no combination at all — every preset is
- * exactly one capability — so the surfaces the multi-select makes reachable,
- * which is most of them, had nothing compiling them.
- *
- * WHY NOT THE POWER SET. 2^groups x integrations x frameworks is thousands of
- * cells to exercise no new branch. The renderers compose capabilities
- * INDEPENDENTLY: each companion tag is emitted on its own terms, and the
- * multi-component predicates (`isArtifactSplit`, `isWorkspaceBlock`) each read
- * components from within a single group. So
- * "every capability alone" reaches every branch, and "all capabilities together"
- * makes every PAIR of capabilities co-occur, which is what proves they compose.
- *
- * THE LIMIT, STATED: a defect needing exactly two capabilities and masked by a
- * third would survive this. That is a real gap and the honest reason it is
- * accepted is cost, not safety — no such branch exists in the renderers today,
- * and `assertSurfacesAreDistinct` fails if the axis ever degenerates so that this
- * reasoning is quietly checking less than it claims.
- */
-export function listSurfaceProbes(): SurfaceProbe[] {
-  const groups = listCapabilityGroups();
-  return [
-    { id: 'chat-only', components: [BASE_COMPONENT] },
-    ...groups.map((g) => ({ id: g.id, components: [BASE_COMPONENT, ...g.components] })),
-    {
-      id: 'every-capability',
-      components: [BASE_COMPONENT, ...groups.flatMap((g) => g.components)],
-    },
-  ];
-}