@kitn.ai/ui 0.20.1 → 0.22.0

package/src/schemas/tool-defs.ts

@@ -0,0 +1,492 @@
+// Card schemas -> provider tool definitions.
+//
+// THE PROBLEM THIS SOLVES
+// -----------------------
+// A developer who wants a model to produce a `confirm` card today hand-writes a tool
+// definition that approximates a schema they cannot import, then hand-writes a mapper
+// from the model's arguments back to a CardEnvelope. This repo's own reference
+// harness does exactly that and says so in a comment
+// (examples/internal/openrouter-spike/src/tools.ts). That is the same shape written
+// in five places. This file removes two of them: the tool definition is GENERATED
+// from the schema the card already validates against, so it cannot drift.
+//
+// WHAT THIS FILE IS NOT
+// ---------------------
+// It is not a provider client and it never becomes one. No `openai`, no
+// `@anthropic-ai/sdk`, no `fetch`. The provider envelope shapes below are declared
+// here as plain structural types, which is what lets `@kitn.ai/ui` keep its rule that
+// nothing under `src/` depends on a provider SDK. The kit PARSES and PROJECTS; the
+// consumer FETCHES.
+//
+// THE HEADLINE, MEASURED, NOT RECALLED
+// ------------------------------------
+// `strict: true` currently throws for EVERY built-in card on BOTH providers. That is
+// not a bug in this file, it is what the schemas say when you hold them against the
+// two documented subsets (see provider-subsets.ts for the two source docs). The
+// authored schemas use `minLength` (confirm/choice/tasks), `maxLength` +
+// `format: "uri"` (link/embed/artifact), `minimum` (tasks/embed/artifact),
+// `maxItems` (confirm/artifact), `pattern` (embed), `if`/`then` (embed), `oneOf`
+// (artifact), a free-form object (form) and untyped `payload`/`allowOther` members
+// (confirm/choice). Non-strict is therefore not merely the default, it is currently
+// the only working mode, and it is also the mode the five-configuration conformance
+// spike actually proved cards in.
+//
+// The alternative was to silently drop the offending keywords. That is rejected for
+// the reason the plan gives: a dropped `maxItems: 4` means the model emits six
+// actions and the card renders six buttons, with nothing anywhere saying the contract
+// was quietly loosened. A throw that NAMES the card, the path and the keyword is a
+// signal on the developer's own machine, which is the whole point.
+
+import { toolNameForCardType } from './from-tool-call';
+import { cardSchemas } from './index';
+import type { CardSchema, CardSchemaName } from './index';
+import {
+  ANTHROPIC_STRICT,
+  OPENAI_STRICT,
+  checkProviderSubset,
+  type ProviderSubset,
+  type StrictProviderId,
+  type SubsetViolation,
+} from './provider-subsets';
+
+// THE TOOL NAME IS NOT SPELLED HERE
+// ---------------------------------
+// `kai_confirm` is produced by `toolNameForCardType()` in ./from-tool-call, which
+// also owns the inverse (`cardTypeFromToolName`). Both directions come off one
+// string in one module on purpose. If this file wrote `'kai_' + type` instead, the
+// two halves could drift, and the symptom would be a model dutifully calling
+// `kai_confirm` while the loop's parser looks for something else and routes it to
+// `runTool`, where it disappears with no error anywhere.
+//
+// A `toolPrefix` OVERRIDE IS NOT SHIPPED, AND THAT IS A DECISION.
+// The plan reserves `createCardRegistry({ toolPrefix })` for Phase 2. It is
+// deliberately NOT stubbed in here, because the inverse hard-codes the `kai_` prefix:
+// a `toolPrefix` honoured on this side alone would generate tools the parser cannot
+// recognise, which is a worse failure than not having the option. The seam is the
+// `CardToolSource` interface below; the override lands in both directions in one
+// change, or not at all.
+
+// ---------------------------------------------------------------------------
+// Provider envelope shapes, declared here rather than imported from an SDK
+// ---------------------------------------------------------------------------
+
+/** A projected schema. Deliberately loose: `type` may become `['string','null']`. */
+export type ToolParameters = Readonly<Record<string, unknown>>;
+
+/** `POST /v1/chat/completions` and `/v1/responses` tool entries. */
+export interface OpenAIToolDef {
+  readonly type: 'function';
+  readonly function: {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: ToolParameters;
+    readonly strict?: true;
+  };
+}
+
+/** `POST /v1/messages` tool entries. Note `input_schema`, NOT `function.parameters`. */
+export interface AnthropicToolDef {
+  readonly name: string;
+  readonly description: string;
+  readonly input_schema: ToolParameters;
+  readonly strict?: true;
+}
+
+/**
+ * The bare form, for the Vercel AI SDK and anything else that wants the schema
+ * without a provider envelope: `tool({ inputSchema: jsonSchema(def.schema) })`.
+ *
+ * First-class, not a fallback. A developer on `ai@7` defines tools with Zod, and
+ * handing them an OpenAI-shaped envelope they have to unwrap makes our JSON Schema an
+ * awkward second source of truth instead of the one they use.
+ */
+export interface JsonSchemaToolDef {
+  readonly name: string;
+  readonly description: string;
+  readonly schema: ToolParameters;
+}
+
+export type ToolProvider = 'openai' | 'anthropic' | 'jsonschema';
+
+export type ToolDefFor<P extends ToolProvider> = P extends 'openai'
+  ? OpenAIToolDef
+  : P extends 'anthropic'
+    ? AnthropicToolDef
+    : JsonSchemaToolDef;
+
+export type ToolDef = OpenAIToolDef | AnthropicToolDef | JsonSchemaToolDef;
+
+export interface CardToolOptions<P extends ToolProvider = ToolProvider> {
+  readonly provider: P;
+  /**
+   * Opt in to the provider's grammar-constrained mode.
+   *
+   * Default `false`, because that is the mode the conformance sweep proved cards in
+   * and because, today, `true` throws for every built-in card on both providers.
+   * When it throws it names the card, the path and the keyword.
+   */
+  readonly strict?: boolean;
+}
+
+/**
+ * Where the card types come from.
+ *
+ * Phase 1 hands this the built-in `cardSchemas` map directly. Phase 2's
+ * `createCardRegistry()` returns an object that is structurally a `CardToolSource`,
+ * so `cardTools(registry, opts)` starts working on custom card types without this
+ * signature changing. That is the seam, left open on purpose and not built yet.
+ */
+export interface CardToolSource {
+  readonly schemas: Readonly<Record<string, CardSchema>>;
+  /** Tool descriptions by card type. Falls back to the built-in copy, then the schema's own. */
+  readonly descriptions?: Readonly<Record<string, string>>;
+}
+
+export type CardToolInput = CardToolSource | Readonly<Record<string, CardSchema>>;
+
+// ---------------------------------------------------------------------------
+// Tool descriptions
+// ---------------------------------------------------------------------------
+
+/**
+ * What each card is FOR, addressed to a model.
+ *
+ * This is not a sixth copy of a shape. The shape stays in the JSON Schema and is
+ * never restated here; these are one sentence each of purpose, which exists nowhere
+ * else, and which a schema's own `description` ("Data payload for a `confirm` card")
+ * does not provide because it is written for a developer reading the contract.
+ *
+ * Typed as an exhaustive `Record<CardSchemaName, string>`, so adding an eighth card
+ * type fails `tsc` here rather than silently shipping a tool with no description.
+ */
+export const CARD_TOOL_DESCRIPTIONS: Readonly<Record<CardSchemaName, string>> = Object.freeze({
+  confirm:
+    'Show the user an approval card and wait for their decision before you act. Use this whenever you are about to do something consequential, destructive or irreversible.',
+  choice:
+    'Ask the user to pick exactly one option from a list of rich choices. Use this instead of asking in prose when the options are known and finite.',
+  tasks:
+    'Show the user a checklist they can tick, either to select several items for you to act on or to track progress through a sequence of steps.',
+  form: 'Ask the user for structured input by rendering a form. The data is itself a JSON Schema describing the fields to collect.',
+  link: 'Show a rich preview of a web page: title, description, image and domain. The card renders what you supply and never fetches the page itself.',
+  embed: 'Embed a video player (YouTube, Vimeo, or a direct player URL) inline in the conversation.',
+  artifact:
+    'Show something you built (a page, an app, a set of files) in a framed preview with its source alongside, so the user can look at both.',
+});
+
+// ---------------------------------------------------------------------------
+// The error
+// ---------------------------------------------------------------------------
+
+export interface UnsupportedCardTool {
+  readonly cardType: string;
+  readonly toolName: string;
+  readonly violations: readonly SubsetViolation[];
+}
+
+/**
+ * Thrown by `cardTools(..., { strict: true })` when a card cannot be expressed in the
+ * provider's strict subset.
+ *
+ * Carries the structured detail as well as the message, so a build script can render
+ * it however it likes rather than parsing prose.
+ */
+export class UnsupportedCardToolSchemaError extends Error {
+  override readonly name = 'UnsupportedCardToolSchemaError';
+  readonly provider: StrictProviderId;
+  readonly source: string;
+  readonly cards: readonly UnsupportedCardTool[];
+
+  constructor(subset: ProviderSubset, cards: readonly UnsupportedCardTool[]) {
+    super(formatUnsupported(subset, cards));
+    this.provider = subset.id;
+    this.source = subset.source;
+    this.cards = cards;
+  }
+
+  /** Every distinct keyword named across every failing card, deduped, in order. */
+  get keywords(): string[] {
+    const seen = new Set<string>();
+    for (const card of this.cards) for (const v of card.violations) seen.add(v.keyword);
+    return [...seen];
+  }
+}
+
+function formatUnsupported(subset: ProviderSubset, cards: readonly UnsupportedCardTool[]): string {
+  const lines: string[] = [];
+  const plural = cards.length === 1 ? 'card type' : 'card types';
+  lines.push(`${cards.length} ${plural} cannot be a STRICT tool definition under ${subset.label}:`);
+  for (const card of cards) {
+    lines.push('');
+    lines.push(`  ${card.toolName} (card type "${card.cardType}") — ${card.violations.length} problem(s):`);
+    for (const v of card.violations) {
+      lines.push(`    ${v.path}: \`${v.keyword}\` — ${v.reason}`);
+    }
+  }
+  lines.push('');
+  lines.push(`  subset source: ${subset.source} (read ${subset.checkedOn})`);
+  lines.push(
+    '  Fix: drop `strict: true`. Non-strict is the default and is the mode the kit\'s cards are proven in; both providers accept a loose schema there and ignore what they do not compile. Rewriting a built-in card schema to fit a strict subset would change what a valid card IS, which is a card-contract change, not a projection setting.',
+  );
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// The projection
+// ---------------------------------------------------------------------------
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/**
+ * Keywords stripped from every projection, strict or not.
+ *
+ * `$schema` and `$id` are meta: they address the document, they do not describe the
+ * instance, and neither provider's subset lists them. `x-kai-*` are our own UI hints
+ * (`x-kai-control: "tone"` tells a renderer to draw a tone picker); a model has no
+ * use for them, they cost tokens in every request, and under strict they are an
+ * unlisted keyword. Stripping them is not a downgrade of the contract, because they
+ * never constrained an instance in the first place.
+ */
+function isStrippedKeyword(key: string): boolean {
+  return key === '$schema' || key === '$id' || key.startsWith('x-');
+}
+
+const SUBSCHEMA_KEYS = ['items', 'if', 'then', 'else', 'not', 'contains', 'propertyNames', 'unevaluatedItems', 'additionalItems'];
+const SUBSCHEMA_MAP_KEYS = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas'];
+const SUBSCHEMA_LIST_KEYS = ['allOf', 'anyOf', 'oneOf', 'prefixItems'];
+
+interface ProjectOptions {
+  /** Force `additionalProperties: false` on every object. Both strict subsets demand it. */
+  readonly closeObjects: boolean;
+  /** Put every property in `required`, widening the newly-required ones with `null`. OpenAI only. */
+  readonly requireEveryProperty: boolean;
+}
+
+/**
+ * Rewrite a schema for the wire.
+ *
+ * Only ever REMOVES metadata or ADDS what a provider mandates. It never drops a
+ * constraint, which is the invariant that keeps a projected tool definition and the
+ * card's own validator describing the same set of valid cards.
+ */
+function project(node: unknown, opts: ProjectOptions): unknown {
+  if (!isRecord(node)) return node;
+
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(node)) {
+    if (isStrippedKeyword(key)) continue;
+    out[key] = value;
+  }
+
+  // Recurse. `properties` KEYS are arbitrary names, not keywords: form.schema.json
+  // has properties literally called `properties` and `x-kai-order`, and stripping
+  // those would delete real fields rather than metadata.
+  for (const key of SUBSCHEMA_MAP_KEYS) {
+    const map = out[key];
+    if (!isRecord(map)) continue;
+    const next: Record<string, unknown> = {};
+    for (const [name, child] of Object.entries(map)) next[name] = project(child, opts);
+    out[key] = next;
+  }
+  for (const key of SUBSCHEMA_KEYS) {
+    if (!(key in out) || typeof out[key] === 'boolean') continue;
+    out[key] = project(out[key], opts);
+  }
+  if (isRecord(out.additionalProperties)) out.additionalProperties = project(out.additionalProperties, opts);
+  for (const key of SUBSCHEMA_LIST_KEYS) {
+    const list = out[key];
+    if (!Array.isArray(list)) continue;
+    out[key] = list.map((child) => project(child, opts));
+  }
+
+  const props = isRecord(out.properties) ? out.properties : undefined;
+  const looksLikeObject = out.type === 'object' || props !== undefined;
+
+  if (looksLikeObject && opts.closeObjects && !('additionalProperties' in out)) {
+    out.additionalProperties = false;
+  }
+
+  if (looksLikeObject && opts.requireEveryProperty && props) {
+    const originallyRequired = Array.isArray(out.required) ? out.required.map(String) : [];
+    const all = Object.keys(props);
+    for (const name of all) {
+      if (originallyRequired.includes(name)) continue;
+      props[name] = widenWithNull(props[name]);
+    }
+    out.required = all;
+  }
+
+  return out;
+}
+
+/**
+ * OpenAI's documented emulation of an optional field: keep it in `required` and let
+ * its type admit `null`.
+ *
+ * The `enum` half matters. `{ type: ['string','null'], enum: ['a','b'] }` admits
+ * nothing new, because the enum still excludes null, so the field would be required
+ * AND unsatisfiable-as-absent. `null` therefore joins the enum too.
+ *
+ * A subschema with nothing to widen (no `type`, no `anyOf`) is returned untouched.
+ * That is not a silent pass: `checkProviderSubset` reports it as an untyped
+ * subschema, which is the real problem and a truer message than "could not widen".
+ */
+function widenWithNull(sub: unknown): unknown {
+  if (!isRecord(sub)) return sub;
+  const out: Record<string, unknown> = { ...sub };
+
+  if ('type' in out) {
+    const declared = Array.isArray(out.type) ? out.type.map(String) : [String(out.type)];
+    if (!declared.includes('null')) out.type = [...declared, 'null'];
+  } else if (Array.isArray(out.anyOf)) {
+    if (!out.anyOf.some((b) => isRecord(b) && b.type === 'null')) out.anyOf = [...out.anyOf, { type: 'null' }];
+  } else {
+    return out;
+  }
+
+  if (Array.isArray(out.enum) && !out.enum.includes(null)) out.enum = [...out.enum, null];
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// cardTools
+// ---------------------------------------------------------------------------
+
+function normalizeSource(input: CardToolInput): {
+  schemas: Readonly<Record<string, CardSchema>>;
+  descriptions: Readonly<Record<string, string>>;
+} {
+  // A `CardToolSource` is recognised by carrying a `schemas` map. A bare
+  // `Record<type, CardSchema>` cannot collide with that unless someone names a card
+  // type "schemas" AND its schema document is itself a map of schema documents,
+  // which is not a shape the card contract can produce.
+  const maybe = input as Partial<CardToolSource>;
+  if (isRecord(maybe.schemas)) {
+    return { schemas: maybe.schemas, descriptions: maybe.descriptions ?? {} };
+  }
+  return { schemas: input as Readonly<Record<string, CardSchema>>, descriptions: {} };
+}
+
+function describe(cardType: string, schema: CardSchema, overrides: Readonly<Record<string, string>>): string {
+  const custom = overrides[cardType];
+  if (typeof custom === 'string' && custom.length > 0) return custom;
+  const builtIn = (CARD_TOOL_DESCRIPTIONS as Readonly<Record<string, string>>)[cardType];
+  if (typeof builtIn === 'string' && builtIn.length > 0) return builtIn;
+  // Last resort for a custom card type registered without a description. The schema's
+  // own prose is worse guidance than a purpose sentence, but it beats an empty string,
+  // and Phase 2's registry warns when a type arrives with neither.
+  const own = schema.description;
+  return typeof own === 'string' && own.length > 0 ? own : `Render a \`${cardType}\` card.`;
+}
+
+/**
+ * Project the card schemas into tool definitions for one provider.
+ *
+ * ```ts
+ * const tools = [...myTools, ...cardTools({ provider: 'openai' })];
+ * const tools = cardTools(cards, { provider: 'anthropic' });
+ * const tools = cardTools({ provider: 'jsonschema' }).map((t) =>
+ *   tool({ description: t.description, inputSchema: jsonSchema(t.schema) }));
+ * ```
+ *
+ * @throws {UnsupportedCardToolSchemaError} with `strict: true`, naming every card,
+ * path and keyword the provider cannot express. See the file header: today that is
+ * every built-in card on both providers.
+ */
+export function cardTools<P extends ToolProvider>(opts: CardToolOptions<P>): ToolDefFor<P>[];
+export function cardTools<P extends ToolProvider>(registry: CardToolInput, opts: CardToolOptions<P>): ToolDefFor<P>[];
+export function cardTools(a: CardToolInput | CardToolOptions, b?: CardToolOptions): ToolDef[] {
+  // Single-argument form: `cardTools({ provider: 'openai' })` defaults the registry
+  // to the built-ins, which is the shape the developer-facing docs lead with.
+  const optionsOnly = b === undefined;
+  const opts = (optionsOnly ? (a as CardToolOptions) : (b as CardToolOptions));
+  if (!isRecord(opts) || typeof opts.provider !== 'string') {
+    throw new TypeError('cardTools: an options object with a `provider` is required, e.g. cardTools({ provider: "openai" })');
+  }
+  const { schemas, descriptions } = normalizeSource(
+    optionsOnly ? (builtInSchemas() as CardToolInput) : (a as CardToolInput),
+  );
+  const strict = opts.strict === true;
+
+  if (opts.provider === 'jsonschema' && strict) {
+    throw new TypeError(
+      'cardTools: `strict: true` is provider-specific and cannot be checked for `provider: "jsonschema"`, ' +
+        'because the two documented strict subsets differ (see @kitn.ai/ui/schemas provider-subsets). ' +
+        'Pass provider "openai" or "anthropic" to project and check strictly, or drop `strict`.',
+    );
+  }
+
+  const subset: ProviderSubset | null = strict
+    ? opts.provider === 'openai'
+      ? OPENAI_STRICT
+      : ANTHROPIC_STRICT
+    : null;
+
+  const projectOptions: ProjectOptions = {
+    closeObjects: subset !== null,
+    requireEveryProperty: subset !== null && subset.requireAllPropertiesRequired,
+  };
+
+  const defs: ToolDef[] = [];
+  const failures: UnsupportedCardTool[] = [];
+
+  for (const [cardType, schema] of Object.entries(schemas)) {
+    const name = toolNameForCardType(cardType);
+    const description = describe(cardType, schema, descriptions);
+    const parameters = project(schema, projectOptions) as ToolParameters;
+
+    if (subset) {
+      const violations = checkProviderSubset(parameters, subset);
+      if (violations.length > 0) {
+        failures.push({ cardType, toolName: name, violations });
+        continue;
+      }
+    }
+
+    if (opts.provider === 'openai') {
+      defs.push({ type: 'function', function: { name, description, parameters, ...(strict ? { strict: true as const } : {}) } });
+    } else if (opts.provider === 'anthropic') {
+      defs.push({ name, description, input_schema: parameters, ...(strict ? { strict: true as const } : {}) });
+    } else {
+      defs.push({ name, description, schema: parameters });
+    }
+  }
+
+  if (subset && failures.length > 0) throw new UnsupportedCardToolSchemaError(subset, failures);
+  return defs;
+}
+
+/**
+ * The built-in map, read at CALL time.
+ *
+ * `./index` re-exports this module, and this module imports `cardSchemas` back out
+ * of it, which is a genuine ESM import cycle. It is safe because the value is only
+ * ever read inside a function body: by the time anyone calls `cardTools()`, both
+ * module bodies have finished evaluating and the live binding is populated. Reading
+ * it at TOP level here would be a temporal-dead-zone crash, so do not hoist it into
+ * a `const`.
+ */
+function builtInSchemas(): Readonly<Record<string, CardSchema>> {
+  return cardSchemas;
+}
+
+/** `cardTools(registry, { provider: 'openai' })`, spelled out. */
+export function toOpenAITools(registry?: CardToolInput, opts?: { strict?: boolean }): OpenAIToolDef[] {
+  return registry === undefined
+    ? cardTools({ provider: 'openai', strict: opts?.strict })
+    : cardTools(registry, { provider: 'openai', strict: opts?.strict });
+}
+
+/** `cardTools(registry, { provider: 'anthropic' })`, spelled out. */
+export function toAnthropicTools(registry?: CardToolInput, opts?: { strict?: boolean }): AnthropicToolDef[] {
+  return registry === undefined
+    ? cardTools({ provider: 'anthropic', strict: opts?.strict })
+    : cardTools(registry, { provider: 'anthropic', strict: opts?.strict });
+}
+
+/** `cardTools(registry, { provider: 'jsonschema' })`, spelled out. */
+export function toJsonSchemaTools(registry?: CardToolInput): JsonSchemaToolDef[] {
+  return registry === undefined
+    ? cardTools({ provider: 'jsonschema' })
+    : cardTools(registry, { provider: 'jsonschema' });
+}

package/src/solid.ts

@@ -0,0 +1,150 @@
+// `@kitn.ai/ui/solid` — the COMPLETE SolidJS surface.
+//
+// WHY THIS EXISTS
+// ---------------
+// Solid is this kit's authored layer, so every registered `kai-*` element must be
+// writable as a Solid component (`verify:solid-coverage` enforces 79/79 plus a
+// `<Name>Props` type for every public component). But the root entry "." is what
+// EVERY consumer resolves, including the React/Vue/Svelte/vanilla majority who
+// only ever touch the web components. Growing "." to full Solid coverage cost
+// them 591,359 -> 705,031 bytes (+113,672, +19.2%; +23,160 gzipped) for a surface
+// four of the five supported frameworks cannot even call.
+//
+// So the full Solid catalog lives here instead, and this file is compiled as its
+// OWN build target (vite.config.solid.ts -> dist/solid.js, plus the SSR twin
+// vite.config.solid.server.ts -> dist/solid.server.js, mirroring "."). Nothing
+// below is reachable from dist/index.js, which is the entire point: a React
+// consumer's bundle never sees it.
+//
+// WHY IT COMPOSES "." INSTEAD OF RESTATING IT
+// -------------------------------------------
+// `export * from './index'` makes "./solid is a superset of ." a COMPILER
+// invariant rather than a promise two hand-maintained lists have to keep. This
+// repo has been bitten repeatedly by copied lists that no compiler watches; a
+// restated 400-line barrel would be exactly that, and the failure mode is silent
+// (an export lands on "." only, and Solid consumers never learn it exists).
+//
+// This costs nothing at the package boundary. The composition is resolved at
+// SOURCE level and bundled away: dist/solid.js is a standalone artifact with no
+// runtime dependency on dist/index.js, so importing "./solid" does not drag in a
+// second entry, and importing "." does not drag in any of this.
+//
+// A Solid consumer therefore needs exactly one import:
+//   import { Thread, Dialog, Message, type ThreadProps } from '@kitn.ai/ui/solid';
+export * from './index';
+
+// ---------------------------------------------------------------------------
+// Layer 2 additions: UI primitives the coarse elements render.
+// ---------------------------------------------------------------------------
+export { HoverCardRoot, HoverCardTrigger, HoverCardContent } from './ui/hover-card';
+export type {
+  HoverCardRootProps, HoverCardTriggerProps, HoverCardContentProps,
+} from './ui/hover-card';
+export {
+  DropdownSeparator, DropdownLabel, DropdownCheckboxItem, DropdownRadioItem,
+  DropdownSub, DropdownSubTrigger, DropdownSubContent,
+} from './ui/dropdown';
+export type {
+  DropdownSeparatorProps, DropdownLabelProps, DropdownCheckboxItemProps, DropdownRadioItemProps,
+  DropdownSubProps, DropdownSubTriggerProps, DropdownSubContentProps,
+} from './ui/dropdown';
+export { clampBasis } from './ui/resizable';
+export { Input } from './ui/input';
+export type { InputProps } from './ui/input';
+export { Kbd } from './ui/kbd';
+export type { KbdProps, KbdPlatform } from './ui/kbd';
+export { Switch } from './ui/switch';
+export type { SwitchProps } from './ui/switch';
+export { Tabs } from './ui/tabs';
+export type { TabsProps, TabsVariant, KaiTabItem } from './ui/tabs';
+export { Segmented } from './ui/segmented';
+export type { SegmentedProps, SegmentedOption } from './ui/segmented';
+export { Status } from './ui/status';
+export type { StatusProps, StatusKind } from './ui/status';
+export { ProgressBar } from './ui/progress-bar';
+export type { ProgressBarProps, ProgressTone } from './ui/progress-bar';
+export { Notice } from './ui/notice';
+export type { NoticeProps, NoticeSeverity } from './ui/notice';
+export { EditableLabel } from './ui/editable-label';
+export type { EditableLabelProps } from './ui/editable-label';
+export { Dialog } from './ui/dialog';
+export type { DialogProps, DialogController } from './ui/dialog';
+export { Popover } from './ui/popover';
+export type { PopoverProps, PopoverController } from './ui/popover';
+export { Nav } from './ui/nav';
+export type { NavProps, KaiNavItem, NavItemStatus, NavStatusTone } from './ui/nav';
+export { CommandList } from './ui/command';
+export type { CommandListProps, CommandRow, CommandGroup } from './ui/command';
+export { AgentCard } from './ui/agent-card';
+export type { AgentCardProps, AgentStatus, AgentStatusTone } from './ui/agent-card';
+export { Pane } from './ui/pane';
+export type { PaneProps, PaneStatus, PaneStatusTone } from './ui/pane';
+export { PaneGroup } from './ui/pane-group';
+export type { PaneGroupProps, PaneTab, PaneTabStatus } from './ui/pane-group';
+// PaneGrid and the three overlay primitives have Storybook pages that tell a
+// consumer to `import { … } from '@kitn.ai/ui'` — and were exported from NEITHER
+// entry, so those snippets named symbols nobody could import. They belong on
+// ./solid (Solid-only building blocks, and the overlay trio is what you compose a
+// custom popover/tooltip out of).
+export { PaneGrid } from './ui/pane-grid';
+export type { PaneGridProps } from './ui/pane-grid';
+export { createPresence, usePosition, useDismiss } from './ui/overlay';
+export type { UsePositionOptions, UseDismissOptions, DismissReason } from './ui/overlay';
+export { PromptDock } from './ui/prompt-dock';
+export type { PromptDockProps, PromptDockFrame, PromptDockAppearance } from './ui/prompt-dock';
+export { SettingsGroup, SettingItem } from './ui/settings-group';
+export type { SettingsGroupProps, SettingItemProps } from './ui/settings-group';
+// `kai-icon` renders no kit component — it calls this. Solid consumers resolving
+// the same `icon` strings (named icon | URL | text fallback) need it too.
+export { renderIcon } from './ui/icon';
+
+// ---------------------------------------------------------------------------
+// Layer 3 additions: AI/feature components.
+// ---------------------------------------------------------------------------
+export { ChainOfThoughtAccordion } from './components/chain-of-thought';
+export type { ChainOfThoughtAccordionProps } from './components/chain-of-thought';
+export { VoiceOutput } from './components/voice-output';
+export type { VoiceOutputProps, VoiceOutputController } from './components/voice-output';
+export { CollapsedRail } from './components/conversation-list';
+export type { CollapsedRailProps } from './components/conversation-list';
+
+// ---------------------------------------------------------------------------
+// Layer 3b: the composed thread/shell components the coarse elements wrap.
+// These are what `<kai-thread>`, `<kai-chat>`, `<kai-screen>`, `<kai-coachmark>` and
+// `<kai-composer>` render, so a Solid consumer writes one component for one element
+// instead of re-deriving the scroll/feedback/staging behaviour by hand.
+// ---------------------------------------------------------------------------
+export { Thread } from './components/thread';
+export type { ThreadProps, ThreadController } from './components/thread';
+// ChatThread — the component behind `<kai-chat>`. VERIFIED standalone: rendered in
+// a plain Vite+Solid app (no custom element, no shadow root) it draws its header,
+// the full message list and its BUILT-IN composer; typing into that composer and
+// pressing Send fires `onSubmit` with the typed text and the thread updates, with
+// no console errors.
+//
+// It does emit 5 `<slot>` elements — header-start, header-end, input-top,
+// toolbar-start, toolbar-end. Those are OPTIONAL INJECT points with no assigned
+// nodes outside the facade, so they render nothing; they are only fillable from
+// `<kai-chat>`'s light DOM. The REPLACE/INJECT props (`sidebar`, `empty`,
+// `composer`, `headerFull`, `footer`, `composerActions`) are opt-in switches that
+// the FACADE sets when a host slots content — left at their default they emit no
+// slot at all and the built-in UI renders. So a Solid consumer can ignore all of
+// it; they just cannot project content into those five points without the element.
+export { ChatThread } from './components/chat-thread';
+export type { ChatThreadProps, ChatThreadController, ChatThreadContextUsage } from './components/chat-thread';
+export { Screen } from './components/screen';
+export type { ScreenProps, ScreenController } from './components/screen';
+export { Coachmark } from './components/coachmark';
+export type { CoachmarkProps, CoachmarkController } from './components/coachmark';
+export { Composer } from './components/composer';
+export type {
+  ComposerProps, ComposerController, ComposerChange, TriggerDef, TriggerItem, HighlightRule,
+} from './components/composer';
+// AudioVisualizer — the component behind `<kai-audio-visualizer>`. It arrived on
+// main after this entry was written, and the coverage guard caught it as the one
+// element with no writable SolidJS equivalent, which is exactly the job.
+export { AudioVisualizer } from './components/audio-visualizer';
+export type {
+  AudioVisualizerProps, VisualizerVariant, ShaderSpec, ShaderVariantProps,
+} from './components/audio-visualizer';
+export type { VisualizerSize } from './components/audio-visualizer/sizes';