@kitn.ai/ui 0.25.2 → 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. 80 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 80 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 80 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.25.2",
+  "version": "0.27.0",
   "nx": {
     "name": "ui",
     "targets": {
@@ -116,6 +116,18 @@
       "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"
+    },
     "./schemas": {
       "types": "./dist/schemas/index.d.ts",
       "default": "./dist/schemas.js"
@@ -140,9 +152,12 @@
     "!src/**/*.stories.tsx",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
+    "!src/**/*.testlib.ts",
+    "!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",
@@ -155,36 +170,46 @@
   "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.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-element-api.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 --check",
+    "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",
     "verify:dts:consumer": "node scripts/verify-dts-consumer.mjs",
     "verify:generated": "node scripts/verify-generated-sync.mjs --self-test && node scripts/verify-generated-sync.mjs",
     "verify:quarantine": "node scripts/verify-quarantine.mjs --self-test && node scripts/verify-quarantine.mjs",
     "verify:react-wrappers": "node scripts/verify-react-wrappers.mjs --self-test && node scripts/verify-react-wrappers.mjs",
     "verify:scaffold": "node scripts/verify-scaffold-compiles.mjs",
+    "gate:compiles": "node scripts/acceptance-gate-compiles.mjs",
+    "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",
     "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: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",
+    "lint:catalog-drift": "node scripts/lint-catalog-drift.mjs --self-test && node scripts/lint-catalog-drift.mjs",
+    "lint:gate-parity": "node scripts/lint-gate-parity.mjs --self-test && node scripts/lint-gate-parity.mjs",
+    "lint:thresholds": "node scripts/lint-threshold-derivation.mjs --self-test && node scripts/lint-threshold-derivation.mjs",
     "test": "vitest run",
     "test:react": "vitest run --config vitest.react.config.ts",
     "test:storybook": "vitest run --project=storybook",
@@ -195,15 +220,20 @@
     "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",
-    "build:css": "tailwindcss -i src/elements/styles.css -o src/elements/compiled.css --minify",
+    "build:css": "tailwindcss -i src/elements/styles.css -o src/elements/compiled.css --minify && npm run postprocess:css",
     "build:css:watch": "tailwindcss -i src/elements/styles.css -o src/elements/compiled.css --watch",
+    "postprocess:css": "node scripts/postprocess-element-css.mjs --self-test && node scripts/postprocess-element-css.mjs",
     "dev:provider": "vite ../../examples/internal/remote-provider --port 6007 --strictPort",
     "dev:host": "vite ../../examples/internal/remote-host --port 6006 --strictPort",
     "test:e2e": "playwright test",
     "test:composer-ivp": "playwright test --config playwright.composer.config.ts",
     "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:command-ivp": "playwright test --config playwright.command.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",
@@ -242,6 +272,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/express": "^5.0.6",
     "@types/node": "^26.0.0",
+    "@types/pngjs": "^6.0.5",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^4.7.0",
@@ -250,10 +281,12 @@
     "ai": "^7.0.59",
     "axe-core": "^4.12.1",
     "concurrently": "^10.0.3",
+    "esbuild": "^0.28.1",
     "express": "^5.2.1",
     "http-server": "^14.1.1",
     "jsdom": "^24.0.0",
     "playwright": "^1.59.1",
+    "pngjs": "^6.0.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "remark-gfm": "^4.0.1",

package/src/agent-tooling/archetypes.ts

@@ -41,9 +41,41 @@ export const archetypes: Archetype[] = [
     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',
@@ -99,10 +131,9 @@ export interface CapabilityGroup {
  * 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`).
+ * 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
@@ -113,7 +144,7 @@ export interface CapabilityGroup {
  * 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
+ * `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.
@@ -147,10 +178,11 @@ export interface SurfaceProbe {
  * 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
+ * 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.
  *