@kitn.ai/ui 0.26.0 → 0.27.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.27.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/catalog/invariants.ts

@@ -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,131 @@
+/**
+ * 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)
+`;
+
+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})`);
+      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;
+  }
+}