@kitn.ai/ui 0.20.1 → 0.22.0

package/llms.txt

@@ -17,7 +17,7 @@ This is the single most common mistake. Arrays and objects (`messages`, `models`
 
 ```js
 const chat = document.querySelector('kai-chat');
-chat.messages = [{ id: '1', role: 'assistant', content: 'Hi!' }]; // ✅ property
+chat.messages = [{ id: '1', role: 'assistant', parts: [{ type: 'text', text: 'Hi!' }] }]; // ✅ property
 ```
 ```html
 <kai-chat messages="[...]"></kai-chat>  <!-- ❌ never works -->
@@ -47,18 +47,70 @@ All 80 elements are also exported individually. Use them for custom layouts or f
 
 ## ChatMessage schema (required for `<kai-chat>`)
 
+A message's content is an **ordered `parts` array**. There is no `content` string: it was removed in 0.20.0. Text, reasoning, tool calls, generative-UI cards, citations and file attachments all live in `parts`, in the order the model produced them, so a post-tool answer renders below its tool panel instead of being glued onto the pre-tool text.
+
 ```ts
 interface ChatMessage {
   id: string;
   role: 'user' | 'assistant';
-  content: string;
-  reasoning?: { text: string; label?: string };
-  tools?: ToolPart[];
-  attachments?: AttachmentData[];
+  /** The ONLY content channel. Ordered. */
+  parts: MessagePart[];
+  /** Action buttons under the message. Chrome, not content. */
   actions?: ('copy' | 'like' | 'dislike' | 'regenerate' | 'edit')[];
+  avatar?: { src?: string; fallback?: string; alt?: string };
+  feedback?: 'like' | 'dislike';
+}
+
+/** Six variants, one per kind of content. Every variant may also carry `raw`
+ *  (`{ source, payload }`), the untranslated provider block the part was
+ *  normalized from, for echoing a turn back to the model verbatim. */
+type MessagePart =
+  | { type: 'text'; text: string; raw?: RawOrigin }
+  | { type: 'reasoning'; text: string; label?: string; index?: number; signature?: string; raw?: RawOrigin }
+  | { type: 'tool'; tool: ToolPart; raw?: RawOrigin }
+  | { type: 'card'; envelope: CardEnvelope; raw?: RawOrigin }
+  | { type: 'source'; source: MessageSource; raw?: RawOrigin }
+  | { type: 'file'; attachment: AttachmentData; raw?: RawOrigin };
+
+interface ToolPart {
+  type: string;
+  /** Rendering classification. Derived from `type` when you omit it; an explicit
+   *  value you set is preserved across later patches. */
+  kind?: 'command' | 'file-change' | 'search' | 'fetch' | 'mcp' | 'image' | 'generic';
+  state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
+  input?: Record<string, unknown>;
+  /** Raw accumulated argument fragments, for character-level streaming. */
+  rawInput?: string;
+  output?: Record<string, unknown>;
+  toolCallId?: string;
+  errorText?: string;
+  raw?: RawOrigin;
+}
+
+/** A citation. Exported as `MessageSource` (the bare `Source` name belongs to
+ *  the citation-chip component). */
+interface MessageSource { id?: string; url?: string; title?: string; snippet?: string; index?: number }
+```
+
+The simplest possible message, and one with reasoning + a tool call before its answer:
+
+```js
+{ id: '1', role: 'assistant', parts: [{ type: 'text', text: 'Hi!' }] }
+
+{
+  id: '2',
+  role: 'assistant',
+  parts: [
+    { type: 'reasoning', text: 'I should search for current pricing.' },
+    { type: 'tool', tool: { type: 'search', state: 'output-available', toolCallId: 'tc_1',
+        input: { query: 'current pricing' }, output: { results: ['A', 'B'] } } },
+    { type: 'text', text: 'Here is what I found.' },
+  ],
 }
 ```
 
+Types are importable: `import type { ChatMessage, MessagePart, MessageSource } from '@kitn.ai/ui'` (also from `'@kitn.ai/ui/react'` and `'@kitn.ai/ui/state'`).
+
 ## Framework wiring
 
 **Plain HTML / CDN**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitn.ai/ui",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "nx": {
     "name": "ui",
     "targets": {
@@ -100,15 +100,39 @@
       "types": "./dist/react/index.d.ts",
       "default": "./dist/react.js"
     },
+    "./solid": {
+      "types": "./dist/solid.d.ts",
+      "worker": "./dist/solid.server.js",
+      "browser": "./dist/solid.js",
+      "deno": "./dist/solid.server.js",
+      "node": "./dist/solid.server.js",
+      "default": "./dist/solid.js"
+    },
     "./state": {
       "types": "./dist/state/index.d.ts",
       "default": "./dist/state.js"
     },
+    "./wire": {
+      "types": "./dist/wire/index.d.ts",
+      "default": "./dist/wire.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "default": "./dist/schemas.js"
+    },
+    "./schemas/*": "./dist/schemas/*",
     "./provider": {
-      "types": "./dist/kai-provider.d.ts",
+      "types": "./dist/remote/provider.d.ts",
       "default": "./dist/kai-provider.es.js"
     }
   },
+  "typesVersions": {
+    "*": {
+      "schemas": [
+        "./dist/schemas/index.d.ts"
+      ]
+    }
+  },
   "files": [
     "dist",
     "src",
@@ -118,7 +142,10 @@
     "!src/**/*.test.tsx",
     "!src/**/*.mdx",
     "!src/stories",
+    "!src/wire/fixtures",
     "!src/elements/logos",
+    "!src/elements/card-media.jpg",
+    "!src/elements/video-poster.jpg",
     "frameworks",
     "theme.css",
     "llms.txt",
@@ -127,22 +154,37 @@
   ],
   "scripts": {
     "prepublishOnly": "npm run build",
-    "prebuild": "npm run build:css",
-    "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.state.ts && vite build --config vite.config.mcp.ts && npm run build:elements && node scripts/verify-elements-bundle.mjs && node scripts/verify-react-wrappers.mjs && node scripts/verify-shader-lazy.mjs",
+    "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.schemas.ts && vite build --config vite.config.mcp.ts && npm run build:elements && node scripts/verify-elements-bundle.mjs && node scripts/verify-react-wrappers.mjs && node scripts/verify-shader-lazy.mjs",
     "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",
+    "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-element-api.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 --check",
     "verify:consumer": "node scripts/verify-consumer-sideeffects.mjs",
-    "verify:ssr": "node scripts/verify-ssr-imports.mjs",
+    "verify:dts": "node scripts/verify-dts-boundaries.mjs",
+    "verify:dts:consumer": "node scripts/verify-dts-consumer.mjs",
+    "verify:generated": "node scripts/verify-generated-sync.mjs",
+    "verify:quarantine": "node scripts/verify-quarantine.mjs",
+    "verify:scaffold": "node scripts/verify-scaffold-compiles.mjs",
+    "verify:schemas": "node scripts/verify-schemas-exported.mjs",
+    "verify:solid-coverage": "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: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:starters": "node scripts/verify-starters.mjs",
     "test": "vitest run",
     "test:react": "vitest run --config vitest.react.config.ts",
     "test:storybook": "vitest run --project=storybook",
     "test:storybook:ci": "node scripts/run-storybook-tests.mjs",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.react.json && tsc --noEmit -p tsconfig.react.test.json && tsc --noEmit -p tsconfig.mcp.json",
-    "examples": "echo 'Serving repo root on http://localhost:8000 — open http://localhost:8000/examples/demos/composable/index.html' && python3 -m http.server 8000",
+    "typecheck": "npm run verify:quarantine && tsc --noEmit && tsc --noEmit -p tsconfig.react.json && tsc --noEmit -p tsconfig.react.test.json && tsc --noEmit -p tsconfig.mcp.json && tsc --noEmit -p tsconfig.tests.json",
+    "examples": "echo 'Serving repo root on http://localhost:8000 — open http://localhost:8000/examples/demos/composable/index.html' && python3 -m http.server 8000 --directory ../..",
     "dev": "npm run build:css && storybook dev -p 6006",
     "storybook": "npm run build:css && storybook dev -p 6006",
     "build-storybook": "npm run build:css && storybook build",
@@ -169,6 +211,12 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@angular/ssr": "^22.0.0",
+    "@cloudflare/workers-types": "^5.20260810.1",
+    "@langchain/core": "^1.2.5",
+    "@langchain/langgraph": "^1.4.9",
+    "@langchain/openai": "^1.5.6",
+    "@mastra/client-js": "^1.38.0",
     "@playwright/test": "^1.60.0",
     "@shikijs/langs": "^4.2.0",
     "@shikijs/themes": "^4.2.0",
@@ -177,19 +225,25 @@
     "@storybook/addon-docs": "^10.3.5",
     "@storybook/addon-themes": "^10.3.5",
     "@storybook/addon-vitest": "^10.3.5",
+    "@sveltejs/kit": "^2.70.2",
     "@tailwindcss/cli": "^4.3.0",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/typography": "^0.5.19",
+    "@tanstack/react-router": "^1.170.25",
+    "@tanstack/react-start": "^1.168.42",
     "@testing-library/jest-dom": "^6.0.0",
     "@testing-library/react": "^16.3.2",
+    "@types/express": "^5.0.6",
     "@types/node": "^26.0.0",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^4.7.0",
     "@vitest/browser-playwright": "4.1.2",
     "@vitest/coverage-v8": "4.1.2",
+    "ai": "^7.0.59",
     "axe-core": "^4.12.1",
     "concurrently": "^10.0.3",
+    "express": "^5.2.1",
     "http-server": "^14.1.1",
     "jsdom": "^24.0.0",
     "playwright": "^1.59.1",

package/src/agent-tooling/archetypes.ts

@@ -1,5 +1,17 @@
 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',
@@ -43,4 +55,119 @@ export const archetypes: Archetype[] = [
     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. Today that is five: `sources`, `tool+reasoning`, `artifact+resizable`,
+ * `voice-input`, `file-upload+attachments` — and the seven presets collapse onto
+ * them because `drop-in-chat` and `support-widget` both add nothing (they 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 `isWorkspace` 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^5 x 11 integrations x 8 frameworks is 2816 cells to
+ * exercise no new branch. The renderers compose capabilities INDEPENDENTLY: each
+ * companion tag is emitted on its own terms, and the one multi-component
+ * predicate (`isWorkspace`) reads 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)],
+    },
+  ];
+}