@kitn.ai/ui 0.14.1

package/src/primitives/card-schemas/card-envelope.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/card-envelope.schema.json",
+  "title": "CardEnvelope",
+  "description": "A card the agent/server asks the chat to render. `data` validates against the per-type schema.",
+  "type": "object",
+  "required": ["type", "id", "data"],
+  "properties": {
+    "type": { "type": "string", "minLength": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "data": {},
+    "title": { "type": "string" }
+  }
+}

package/src/primitives/card-schemas/card-event.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/card-event.schema.json",
+  "title": "CardEvent",
+  "description": "An event a card emits up to the host. `kind` discriminates the payload.",
+  "type": "object",
+  "required": ["kind"],
+  "properties": {
+    "kind": { "enum": ["ready", "submit", "action", "send-prompt", "open", "resize", "state", "dismiss", "error"] },
+    "cardId": { "type": "string" }
+  }
+}

package/src/primitives/card-schemas/choice.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/choice.schema.json",
+  "title": "ChoiceCardData",
+  "description": "Data payload for a `choice` card (CardEnvelope.data when type='choice'). A single-select 'pick one of N rich options' card; activating an option emits the `action` verb.",
+  "type": "object",
+  "required": ["options"],
+  "properties": {
+    "prompt": {
+      "type": "string",
+      "description": "Optional question/body text rendered above the options. Distinct from CardEnvelope.title (the card chrome heading)."
+    },
+    "submitLabel": {
+      "type": "string",
+      "description": "Label for the Submit button; default 'Submit'."
+    },
+    "options": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The selectable options, rendered in order. Exactly one can be chosen.",
+      "items": {
+        "type": "object",
+        "required": ["id", "label"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Emitted as CardEvent.action. Must be unique within `options`. (The reserved id '__other__' is used by the allowOther escape.)",
+            "x-kai-unique": true
+          },
+          "label": { "type": "string", "minLength": 1, "description": "Visible option label." },
+          "description": {
+            "type": "string",
+            "description": "Optional secondary line under the label."
+          },
+          "media": {
+            "type": "object",
+            "description": "Optional leading media: an image URL or a named icon.",
+            "properties": {
+              "image": { "type": "string", "description": "Image URL rendered as a leading thumbnail in the row." },
+              "imageAlt": { "type": "string", "description": "Accessible alt text for `image` (decorative if omitted)." },
+              "icon": { "type": "string", "description": "Named icon rendered as a leading glyph." }
+            }
+          },
+          "meta": {
+            "type": "string",
+            "description": "Trailing freeform text (e.g. a price or badge), right-aligned in the row."
+          },
+          "recommended": {
+            "type": "boolean",
+            "default": false,
+            "description": "Renders a small 'Recommended' pill near the label."
+          },
+          "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Option is shown but not selectable, and skipped in keyboard nav."
+          },
+          "payload": {
+            "description": "Optional opaque payload echoed back in CardEvent.payload (any JSON)."
+          }
+        }
+      }
+    },
+    "allowOther": {
+      "description": "Optional free-text escape ('none of these / specify'). `true` appends a final 'Other…' option; an object customizes its `label`/`placeholder`. Selecting it reveals a text input; the shared Submit button then emits `{ kind:'action', action:'__other__', payload:{ text } }`.",
+      "x-kai-control": "allow-other"
+    }
+  }
+}

package/src/primitives/card-schemas/confirm.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/confirm.schema.json",
+  "title": "ConfirmCardData",
+  "description": "Data payload for a `confirm` card (CardEnvelope.data when type='confirm').",
+  "type": "object",
+  "required": ["actions"],
+  "properties": {
+    "heading": {
+      "type": "string",
+      "description": "Optional in-body heading. Distinct from CardEnvelope.title (the card chrome title)."
+    },
+    "body": {
+      "type": "string",
+      "description": "Body text. Plain text in v1 (rendered safely; no HTML injection)."
+    },
+    "tone": {
+      "type": "string",
+      "enum": ["default", "warning", "danger"],
+      "default": "default",
+      "description": "Overall card tone; 'danger' adds a warning icon + accent for destructive approvals.",
+      "x-kai-control": "tone"
+    },
+    "actions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 4,
+      "description": "The choice set. Rendered as buttons in order; max 4 keeps it a decision, not a menu.",
+      "items": {
+        "type": "object",
+        "required": ["id", "label"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Emitted as CardEvent.action. Must be unique within `actions`.",
+            "x-kai-unique": true
+          },
+          "label": { "type": "string", "minLength": 1, "description": "Visible button label." },
+          "style": {
+            "type": "string",
+            "enum": ["primary", "default", "destructive"],
+            "default": "default",
+            "description": "Button emphasis. 'destructive' = red/danger; 'primary' = filled accent.",
+            "x-kai-control": "button-style"
+          },
+          "payload": {
+            "description": "Optional opaque payload echoed back in CardEvent.payload (any JSON)."
+          },
+          "default": {
+            "type": "boolean",
+            "default": false,
+            "description": "If true, this action is the keyboard default (Enter) and gets initial focus. At most one should be true; the card uses the first if several are.",
+            "x-kai-default-action": true
+          }
+        }
+      }
+    },
+    "dismissible": {
+      "type": "boolean",
+      "default": false,
+      "description": "Show a close affordance that emits the `dismiss` verb."
+    }
+  }
+}

package/src/primitives/card-schemas/embed.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/embed.schema.json",
+  "title": "EmbedCardData",
+  "description": "Lazy media-embed payload (YouTube / Vimeo / generic player URL).",
+  "type": "object",
+  "x-kai-card-type": "embed",
+  "x-kai-contract-version": "1",
+  "required": ["provider"],
+  "additionalProperties": false,
+  "properties": {
+    "provider": {
+      "type": "string",
+      "enum": ["youtube", "vimeo", "generic"],
+      "description": "Media provider. 'generic' frames `url` directly (must be an https embeddable player URL whose origin is app-allowlisted).",
+      "x-kai-control": "select"
+    },
+    "id": {
+      "type": "string",
+      "description": "Provider video id (required for youtube/vimeo when `url` is absent). e.g. 'dQw4w9WgXcQ'.",
+      "maxLength": 64,
+      "pattern": "^[A-Za-z0-9_-]+$"
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Full media/watch URL. For youtube/vimeo it is parsed to an id; for 'generic' it is the embeddable player src (https only).",
+      "x-kai-format": "url"
+    },
+    "title": {
+      "type": "string",
+      "description": "Accessible title for the player iframe + the poster label. Strongly recommended for a11y.",
+      "maxLength": 300
+    },
+    "poster": {
+      "type": "string",
+      "format": "uri",
+      "description": "Thumbnail shown before play. When omitted, youtube/vimeo derive a default thumbnail; 'generic' shows a neutral play placeholder.",
+      "x-kai-format": "url"
+    },
+    "start": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional start offset in seconds.",
+      "x-kai-unit": "seconds"
+    },
+    "aspectRatio": {
+      "type": "string",
+      "enum": ["16:9", "4:3", "1:1", "9:16"],
+      "default": "16:9",
+      "description": "Player box aspect ratio (CSS aspect-ratio).",
+      "x-kai-control": "select"
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "provider": { "const": "generic" } } },
+      "then": { "required": ["url"] }
+    },
+    {
+      "if": { "properties": { "provider": { "enum": ["youtube", "vimeo"] } } },
+      "then": { "anyOf": [{ "required": ["id"] }, { "required": ["url"] }] }
+    }
+  ]
+}

package/src/primitives/card-schemas/form.result.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/form.result.schema.json",
+  "title": "kai-form submit payload",
+  "description": "The CardEvent {kind:'submit'} `data` for a form card: an object that validates against the form-definition schema that was sent down in CardEnvelope.data. Standard JSON Schema validation (type/enum/required/min-max/length/pattern) holds. Optional empty strings are omitted.",
+  "type": "object"
+}

package/src/primitives/card-schemas/form.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/form.schema.json",
+  "title": "kai-form data (a form definition)",
+  "description": "The CardEnvelope.data for a card of type 'form': a JSON Schema (type:'object') describing the fields kai-form renders, plus optional x-kai-* UI hints. The same schema validates the submission.",
+  "type": "object",
+  "required": ["type", "properties"],
+  "properties": {
+    "type": { "const": "object" },
+    "title": { "type": "string" },
+    "description": { "type": "string" },
+    "required": { "type": "array", "items": { "type": "string" } },
+    "properties": {
+      "type": "object"
+    },
+    "x-kai-order": { "type": "array", "items": { "type": "string" } },
+    "x-kai-inlineMax": { "type": "integer", "minimum": 1 },
+    "x-kai-submitLabel": { "type": "string" },
+    "x-kai-dismissible": { "type": "boolean" },
+    "x-kai-actions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label"],
+        "properties": {
+          "id": { "type": "string" },
+          "label": { "type": "string" },
+          "variant": { "enum": ["default", "ghost", "outline"] }
+        }
+      }
+    }
+  }
+}

package/src/primitives/card-schemas/link.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/link.schema.json",
+  "title": "LinkPreviewData",
+  "description": "Rich link / Open-Graph preview payload. The card renders from this; it never fetches.",
+  "type": "object",
+  "x-kai-card-type": "link",
+  "x-kai-contract-version": "1",
+  "required": ["url"],
+  "additionalProperties": false,
+  "properties": {
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Canonical destination. Opened via the contract `open` verb (target 'tab').",
+      "x-kai-format": "url"
+    },
+    "title": {
+      "type": "string",
+      "description": "OG title (og:title). Falls back to the domain when absent.",
+      "maxLength": 300
+    },
+    "description": {
+      "type": "string",
+      "description": "OG description (og:description). Clamped to 3 lines in the UI.",
+      "maxLength": 1000
+    },
+    "image": {
+      "type": "string",
+      "format": "uri",
+      "description": "Preview image (og:image). Optional; the card degrades gracefully when missing or it fails to load.",
+      "x-kai-format": "url"
+    },
+    "imageAlt": {
+      "type": "string",
+      "description": "Alt text for the preview image. Defaults to the title (or empty = decorative) when omitted.",
+      "maxLength": 300
+    },
+    "favicon": {
+      "type": "string",
+      "format": "uri",
+      "description": "Site favicon shown next to the domain.",
+      "x-kai-format": "url"
+    },
+    "domain": {
+      "type": "string",
+      "description": "Display domain (e.g. 'example.com'). Derived from `url` when omitted.",
+      "maxLength": 253
+    },
+    "siteName": {
+      "type": "string",
+      "description": "OG site name (og:site_name). Shown in place of the domain when present.",
+      "maxLength": 200
+    }
+  }
+}

package/src/primitives/card-schemas/tasks.result.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/tasks.result.schema.json",
+  "title": "TasksCardResult",
+  "description": "Payload of CardEvent { kind: 'submit' } from a tasks card.",
+  "type": "object",
+  "required": ["selected"],
+  "properties": {
+    "selected": {
+      "type": "array",
+      "description": "Ids of the checked tasks, in the order they appear in `tasks`. Subset of the input task ids.",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    }
+  }
+}

package/src/primitives/card-schemas/tasks.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kitn.ai/schemas/card/tasks.schema.json",
+  "title": "TasksCardData",
+  "description": "Data payload for a `tasks` card (CardEnvelope.data when type='tasks').",
+  "type": "object",
+  "required": ["tasks"],
+  "properties": {
+    "mode": {
+      "type": "string",
+      "enum": ["select"],
+      "default": "select",
+      "description": "v1 supports only 'select' (toggle + confirm). 'progress' (live AG-UI status) is a future enum value; restricting it now keeps the wire forward-compatible.",
+      "x-kai-mode": true
+    },
+    "heading": {
+      "type": "string",
+      "description": "Optional in-body heading; distinct from CardEnvelope.title."
+    },
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The selectable rows, rendered in order.",
+      "items": {
+        "type": "object",
+        "required": ["id", "label"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable id; the selected ids are returned in the result. Unique within `tasks`.",
+            "x-kai-unique": true
+          },
+          "label": { "type": "string", "minLength": 1, "description": "Row label." },
+          "description": { "type": "string", "description": "Optional secondary line under the label." },
+          "checked": {
+            "type": "boolean",
+            "default": false,
+            "description": "Initial checked state of the row."
+          },
+          "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Row is shown but not toggleable (and excluded from select-all)."
+          }
+        }
+      }
+    },
+    "selectAll": {
+      "type": "boolean",
+      "default": false,
+      "description": "Render a master select-all checkbox above the list.",
+      "x-kai-control": "select-all"
+    },
+    "confirmLabel": {
+      "type": "string",
+      "default": "Confirm",
+      "description": "Label for the confirm button."
+    },
+    "allowEmpty": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true, confirm is enabled with zero selected (emits { selected: [] }). If false, confirm is disabled until >=1 selected."
+    },
+    "min": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional minimum number that must be selected to confirm.",
+      "x-kai-select-min": true
+    },
+    "max": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional maximum selectable; further toggles are blocked once reached.",
+      "x-kai-select-max": true
+    }
+  }
+}

package/src/primitives/card-validate.ts

@@ -0,0 +1,95 @@
+// src/primitives/card-validate.ts
+// The single shared lean JSON-Schema validator the contract mandates. Covers the
+// subset cards use; `x-*` keywords (incl. x-kai-*) are ignored. No ajv. Used at
+// every boundary (incoming card data, outgoing payloads) by cards + both transports.
+
+export interface JsonSchema {
+  type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+  const?: unknown;
+  enum?: unknown[];
+  required?: string[];
+  properties?: Record<string, JsonSchema>;
+  items?: JsonSchema;
+  minimum?: number; maximum?: number;
+  exclusiveMinimum?: number; exclusiveMaximum?: number;
+  minLength?: number; maxLength?: number;
+  pattern?: string;
+  minItems?: number; maxItems?: number;
+  uniqueItems?: boolean;
+  // x-* keywords (e.g. x-kai-widget) are allowed and ignored.
+  [key: `x-${string}`]: unknown;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+function typeOf(v: unknown): string {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v;
+}
+
+function matchesType(v: unknown, t: NonNullable<JsonSchema['type']>): boolean {
+  switch (t) {
+    case 'integer': return typeof v === 'number' && Number.isInteger(v);
+    case 'number': return typeof v === 'number' && Number.isFinite(v);
+    case 'array': return Array.isArray(v);
+    case 'null': return v === null;
+    case 'object': return typeOf(v) === 'object';
+    default: return typeof v === t;
+  }
+}
+
+function walk(schema: JsonSchema, value: unknown, path: string, errors: string[]): void {
+  const at = path || '(root)';
+  if (schema.type && !matchesType(value, schema.type)) {
+    errors.push(`${at}: expected ${schema.type}, got ${typeOf(value)}`);
+    return; // type wrong → downstream checks are meaningless
+  }
+  if ('const' in schema && JSON.stringify(value) !== JSON.stringify(schema.const)) {
+    errors.push(`${at}: must equal const ${JSON.stringify(schema.const)}`);
+  }
+  if (schema.enum && !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))) {
+    errors.push(`${at}: must be one of ${JSON.stringify(schema.enum)}`);
+  }
+  if (typeof value === 'number') {
+    if (schema.minimum !== undefined && value < schema.minimum) errors.push(`${at}: < minimum ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) errors.push(`${at}: > maximum ${schema.maximum}`);
+    if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) errors.push(`${at}: <= exclusiveMinimum`);
+    if (schema.exclusiveMaximum !== undefined && value >= schema.exclusiveMaximum) errors.push(`${at}: >= exclusiveMaximum`);
+  }
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && value.length < schema.minLength) errors.push(`${at}: shorter than minLength ${schema.minLength}`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) errors.push(`${at}: longer than maxLength ${schema.maxLength}`);
+    if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) errors.push(`${at}: does not match pattern`);
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) errors.push(`${at}: fewer than minItems ${schema.minItems}`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) errors.push(`${at}: more than maxItems ${schema.maxItems}`);
+    if (schema.uniqueItems) {
+      const seen = new Set(value.map((v) => JSON.stringify(v)));
+      if (seen.size !== value.length) errors.push(`${at}: items not unique`);
+    }
+    if (schema.items) value.forEach((v, i) => walk(schema.items!, v, `${at}[${i}]`, errors));
+  }
+  if (typeOf(value) === 'object') {
+    const obj = value as Record<string, unknown>;
+    for (const key of schema.required ?? []) {
+      if (!(key in obj) || obj[key] === undefined) errors.push(`${at}.${key}: required`);
+    }
+    if (schema.properties) {
+      for (const [key, sub] of Object.entries(schema.properties)) {
+        if (key in obj && obj[key] !== undefined) walk(sub, obj[key], `${at}.${key}`, errors);
+      }
+    }
+  }
+}
+
+/** Validate `value` against the lean JSON-Schema subset. */
+export function validateAgainstSchema(schema: JsonSchema, value: unknown): ValidationResult {
+  const errors: string[] = [];
+  walk(schema, value, '', errors);
+  return { valid: errors.length === 0, errors };
+}

package/src/primitives/chat-config.tsx

@@ -0,0 +1,76 @@
+import { createContext, useContext, type Accessor, type JSX } from 'solid-js';
+
+export type ProseSize = 'xs' | 'sm' | 'base' | 'lg';
+
+export interface ChatConfigValue {
+  /** Prose/text size for messages, markdown, and UI elements */
+  proseSize: Accessor<ProseSize>;
+  /** Shiki theme for code blocks */
+  codeTheme: Accessor<string>;
+  /** Node the kit's overlays portal into; undefined → document.body */
+  portalMount: Accessor<HTMLElement | undefined>;
+  /** Whether code blocks are syntax-highlighted; false → plain text, no Shiki loaded */
+  codeHighlight: Accessor<boolean>;
+}
+
+const defaultConfig: ChatConfigValue = {
+  proseSize: () => 'sm' as ProseSize,
+  codeTheme: () => 'github-dark-dimmed',
+  portalMount: () => undefined,
+  codeHighlight: () => true,
+};
+
+const ChatConfigContext = createContext<ChatConfigValue>(defaultConfig);
+
+export interface ChatConfigProps {
+  proseSize?: ProseSize;
+  codeTheme?: string;
+  portalMount?: HTMLElement;
+  codeHighlight?: boolean;
+  children: JSX.Element;
+}
+
+/**
+ * Provides chat-wide appearance settings to all child components.
+ * Set once at the top level — MessageContent, Markdown, CodeBlock,
+ * ConversationList, and PromptInput all read from this.
+ */
+export function ChatConfig(props: ChatConfigProps) {
+  const value: ChatConfigValue = {
+    proseSize: () => props.proseSize ?? 'sm',
+    codeTheme: () => props.codeTheme ?? 'github-dark-dimmed',
+    portalMount: () => props.portalMount,
+    codeHighlight: () => props.codeHighlight ?? true,
+  };
+
+  return (
+    <ChatConfigContext.Provider value={value}>
+      {props.children}
+    </ChatConfigContext.Provider>
+  );
+}
+
+/** Read the current chat config. Returns defaults if no provider is present. */
+export function useChatConfig(): ChatConfigValue {
+  return useContext(ChatConfigContext)!;
+}
+
+/** Maps prose size to Tailwind prose class */
+export function proseClass(size: ProseSize): string {
+  switch (size) {
+    case 'xs': return 'prose-sm text-xs';
+    case 'sm': return 'prose-sm';
+    case 'base': return '';
+    case 'lg': return 'prose-lg';
+  }
+}
+
+/** Maps prose size to a text class for non-prose elements (sidebar, input) */
+export function textClass(size: ProseSize): string {
+  switch (size) {
+    case 'xs': return 'text-xs';
+    case 'sm': return 'text-sm';
+    case 'base': return 'text-base';
+    case 'lg': return 'text-lg';
+  }
+}

package/src/primitives/controllable.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { createRoot, createSignal } from 'solid-js';
+import { createControllableSignal } from './controllable';
+
+describe('createControllableSignal', () => {
+  it('uses the initial value when uncontrolled (controlled accessor is undefined)', () => {
+    createRoot((dispose) => {
+      const [value] = createControllableSignal(() => undefined, true);
+      expect(value()).toBe(true);
+      dispose();
+    });
+  });
+
+  it('updates via the setter when uncontrolled', () => {
+    createRoot((dispose) => {
+      const [value, setValue] = createControllableSignal(() => undefined, false);
+      setValue(true);
+      expect(value()).toBe(true);
+      dispose();
+    });
+  });
+
+  it('reflects the controlled value and ignores the internal setter while controlled', () => {
+    createRoot((dispose) => {
+      const [controlled, setControlled] = createSignal<boolean | undefined>(false);
+      const [value, setValue] = createControllableSignal(controlled, false);
+      expect(value()).toBe(false);
+      setValue(true); // masked while controlled
+      expect(value()).toBe(false);
+      setControlled(true); // the controlling value wins
+      expect(value()).toBe(true);
+      dispose();
+    });
+  });
+
+  it('falls back to the internal value when control is released (becomes undefined)', () => {
+    createRoot((dispose) => {
+      const [controlled, setControlled] = createSignal<boolean | undefined>(true);
+      const [value, setValue] = createControllableSignal(controlled, false);
+      expect(value()).toBe(true);
+      setValue(true); // sets internal (masked now)
+      setControlled(undefined); // uncontrolled → internal shows
+      expect(value()).toBe(true);
+      dispose();
+    });
+  });
+});