@kitn.ai/ui 0.26.0 → 0.27.0

package/src/elements/feedback-bar.tsx

@@ -36,6 +36,11 @@ interface Events {
  * vote (`collect-detail`), then confirms with a thank-you — all in place. Emits
  * `kai-feedback` (`{ value }`), `kai-feedback-detail` (`{ value, category?, comment? }`),
  * and `kai-close`.
+ *
+ * Placement and lifecycle are the app's call: the component is designed as a
+ * THREAD-level bar (its events carry no message id), and when to show it —
+ * e.g. revealed after a settled turn, hidden again on submit — is product
+ * behavior the host decides.
  */
 defineWebComponent<Props, Events>('kai-feedback-bar', {
   barTitle: 'Was this helpful?',

package/src/elements/icon-names.json

@@ -1,20 +1,33 @@
 [
   "archive",
+  "arrow-down",
   "arrow-left",
+  "arrow-right",
   "arrow-up",
   "audio-lines",
+  "bell",
   "book-open",
   "bookmark",
   "box",
   "briefcase",
+  "check",
   "chevron-down",
   "chevron-left",
+  "chevron-right",
+  "chevron-up",
   "circle",
+  "circle-alert",
+  "circle-check",
+  "circle-x",
   "clock",
   "code",
   "copy",
+  "desktop",
+  "download",
   "ellipsis",
   "external-link",
+  "eye",
+  "eye-off",
   "file-text",
   "flag",
   "folder",
@@ -24,27 +37,43 @@
   "globe",
   "home",
   "image",
+  "info",
+  "laptop",
+  "link",
   "list-filter",
   "lock",
+  "maximize-2",
   "message-circle",
   "message-square",
   "mic",
+  "minimize-2",
+  "minus",
+  "mobile",
   "monitor",
   "moon",
   "more-horizontal",
   "panel-left",
+  "panel-right",
   "paperclip",
   "pencil",
+  "play",
   "plus",
+  "rotate-ccw",
   "rotate-cw",
   "search",
   "settings",
   "share",
   "sliders-horizontal",
+  "smartphone",
   "smile",
   "sparkles",
+  "square",
   "square-pen",
   "sun",
+  "tablet",
+  "trash",
+  "triangle-alert",
+  "upload",
   "workflow",
   "x"
 ]

package/src/elements/input.tsx

@@ -1,14 +1,26 @@
 import { createEffect, createSignal, onCleanup, onMount, untrack } from 'solid-js';
 import { defineWebComponent } from './define';
-import { Input, type InputProps } from '../ui/input';
+import { DEFAULT_FORMAT, Input, type InputProps } from '../ui/input';
+import {
+  compileMask,
+  formatForDisplay,
+  formatRaw,
+  normalizeToRaw,
+  type CaseMode,
+} from '../primitives/field-mask';
+import { canonicalize, fieldSemantics, type FieldSemanticType } from '../primitives/field-semantics';
+import type { CopyPolicy, InputMaskRejectReason } from '../primitives/input-mask';
 
 interface Props extends Record<string, unknown> {
   /** Native input type: `text` (default) · `email` · `url` · `search` · `tel` ·
    *  `password` · `number`. Single-line only. */
   type?: string;
-  /** Controlled value. Settable and reflected to the `value` attribute. `el.value
-   *  = 'hi'` drives it (no event); typing updates it and fires `kai-input`. Read
-   *  `el.value` for live state. */
+  /** Controlled value, and always the CANONICAL one when a mask is active: digits
+   *  for `tel` / `ssn` / `credit-card`, the formatted text for `custom`.
+   *  Settable and reflected to the `value` attribute. `el.value = '5551234567'`
+   *  drives it (no event) and is re-fitted to the mask on the way in, so the field
+   *  shows `555-123-4567`. Read `el.value` for live state; the formatted text rides
+   *  along on every `kai-input` / `kai-change` detail as `formattedValue`. */
   value?: string;
   /** Placeholder shown when empty. */
   placeholder?: string;
@@ -34,6 +46,35 @@ interface Props extends Record<string, unknown> {
   autocomplete?: string;
   /** Virtual-keyboard hint forwarded to the inner input (e.g. `numeric`, `email`). */
   inputmode?: string;
+
+  // --- Form-field formats (spec §7.2). Five SCALARS, which is exactly why they work as
+  // HTML attributes under the kai- contract. With `format` AND `semantic` both absent the
+  // element behaves as it always did: no mask, no extra attributes, nothing.
+
+  /** Mask pattern: `#` a digit, `@` a letter or digit, `*` an obscurable letter or
+   *  digit, and every other character a positional literal (`@@@-####` → `CHG-4821`).
+   *
+   *  The literal `default` is the opt-in sentinel: it resolves to the default format of
+   *  `semantic` (`tel` → `###-###-####`). A bare `semantic` never starts masking on its
+   *  own, so an opt-in token is what turns tier 2 on. */
+  format?: string;
+  /** Placeholder guide shown at unfilled positions, aligned position for position with
+   *  `format`: `mm/dd/yyyy` against `##/##/####`. Spaces are a valid guide character, so
+   *  a guide of blanks and separators is how a phone field shows its shape without
+   *  showing letters. Without a guide the field shows only up to the last typed
+   *  character. A guide is a visual aid, never an accessible name: keep the `hint` text
+   *  as well. */
+  guide?: string;
+  /** Semantic field type: `tel` · `ssn` · `credit-card` · `custom`. On its own it sets
+   *  `inputmode` / `autocomplete` / `spellcheck` / `autocorrect` / `autocapitalize` and
+   *  decides the canonical value; it never starts masking by itself. */
+  semantic?: FieldSemanticType;
+  /** Case folding applied to typed and pasted text: `preserve` (default) · `upper` ·
+   *  `lower`. Attribute: `case-mode`. */
+  caseMode?: CaseMode;
+  /** What a copy or cut of a masked field puts on the clipboard: `canonical` (default)
+   *  · `formatted` · `obscured` · `blocked`. Attribute: `copy-policy`. */
+  copyPolicy?: CopyPolicy;
   // NOTE: `autocapitalize` is forwarded too, but NOT as a declared prop — see the
   // attribute read in the facade body (it is a global reflected HTMLElement IDL
   // attribute and would break the element constructor as a component-register prop).
@@ -41,10 +82,22 @@ interface Props extends Record<string, unknown> {
 
 /** Events fired by `<kai-input>`. */
 interface Events {
-  /** The value changed per keystroke. */
-  'kai-input': { value: string };
-  /** The value was committed (blur). */
-  'kai-change': { value: string };
+  /** The value changed per keystroke. `value` is the canonical value (what a backend
+   *  wants); `formattedValue` is the text on screen. With no mask the two are equal. */
+  'kai-input': { value: string; formattedValue: string };
+  /** The value was committed (blur). Same detail shape as `kai-input`. */
+  'kai-change': { value: string; formattedValue: string };
+  /** A mask refused, or partly refused, some content. The reasons are `full` (no free
+   *  position left), `wrong-class` (a letter into a digit position), `over-capacity` (a
+   *  paste longer than the mask holds; what fits was kept), and `format-change-clipped`
+   *  (the `format` changed under a value that no longer fits). `data` is the content
+   *  that was refused.
+   *
+   *  The first three are USER-INPUT errors, and are the ones worth announcing in a
+   *  polite live region. `format-change-clipped` is not one: it follows the app changing
+   *  its own configuration, so it reports and nothing more. None of the four touches
+   *  validity, so `invalid` and `error` stay the consumer decision. */
+  'kai-input-rejected': { reason: InputMaskRejectReason; data: string };
 }
 
 /** Named slots whose occupancy gates an affix. An empty `<slot>` is always a
@@ -72,8 +125,52 @@ type SlotName = (typeof SLOT_NAMES)[number];
  * </script>
  * ```
  *
- * Methods: `focus()`, `select()`, `clear()`. Restyle via `::part(field)`,
+ * Methods: `focus()`, `select()`, `clear()`, `getRawValue()`, `getFormattedValue()`.
+ * Restyle via `::part(field)`,
  * `::part(input)`, `::part(label)`, `::part(hint)`.
+ *
+ * ## Masked and formatted fields
+ *
+ * `format` turns the field into a mask; `guide`, `semantic`, `case-mode` and
+ * `copy-policy` tune it. All five are scalars, so all five are plain attributes.
+ *
+ * ```html
+ * <kai-input label="Ticket" format="@@@-####" case-mode="upper"
+ *            hint="Three letters, a dash, four digits."></kai-input>
+ * <kai-input label="Phone" semantic="tel" format="default"
+ *            guide="   -   -    "></kai-input>
+ * ```
+ *
+ * `el.value` is the CANONICAL value — digits for `tel` / `ssn` / `credit-card`, the
+ * formatted text for `custom`. The text on screen rides along as
+ * `formattedValue` on the `kai-input` / `kai-change` details. Refusals report on
+ * `kai-input-rejected` and never touch validity.
+ *
+ * TWO THINGS THIS DELIBERATELY DOES NOT DO, both recorded rather than smuggled:
+ *
+ * 1. **Not form-associated.** There is no `ElementInternals` and no
+ *    `setFormValue()`, so a `<kai-input>` inside a `<form>` contributes nothing to
+ *    `FormData` and takes no part in native validation, with or without a mask.
+ *    That is a KNOWN GAP: form association lands later, with its own migration.
+ *    Read the value off the element.
+ * 2. **No `value-type` prop.** Canonical-form-per-semantic-type is the whole
+ *    contract; a per-field raw-or-formatted switch would make
+ *    the same field round-trip differently depending on who set it.
+ *
+ * ### The controlled-value rule, stated
+ *
+ * A write to `el.value` after mount is re-fitted through the masker, so it lands
+ * FORMATTED on screen and canonical on the property, and fires no event. What that
+ * covers is any write that reaches this element: `el.value = x`, the `value`
+ * attribute, and a React/Vue/Svelte wrapper prop, since every wrapper drives this
+ * element by writing the property. A value present at first render is masked by the
+ * same rule, and so is a change to `format` / `guide` / `semantic` / `case-mode`
+ * AFTER mount: the canonical value is re-derived, so `el.value` never serves a
+ * reading that disagrees with the configuration in force. An over-long write is
+ * clipped to what the mask holds and says so on `kai-input-rejected`.
+ *
+ * The one thing none of that reaches is a consumer that writes the inner `<input>`
+ * inside the shadow root directly, behind both this element and its mask.
  */
 defineWebComponent<Props, Events>('kai-input', {
   type: 'text',
@@ -90,15 +187,76 @@ defineWebComponent<Props, Events>('kai-input', {
   name: undefined,
   autocomplete: undefined,
   inputmode: undefined,
+  format: undefined,
+  guide: undefined,
+  semantic: undefined,
+  caseMode: undefined,
+  copyPolicy: undefined,
 }, (props, ctx) => {
   const { element, dispatch, flag, expose } = ctx;
 
-  // Lift the value into the facade and drive Input CONTROLLED so the host can read
-  // it (`el.value` / `:host([value])`) and set it after mount. Seed from the
-  // `value` property/attribute present on mount.
-  const [value, setValue] = createSignal(
+  /** Is a mask configured at all? An empty `format` means no, same as an absent one. */
+  const masked = (): boolean => {
+    const format = props.format as string | undefined;
+    return format !== undefined && format !== '';
+  };
+
+  /**
+   * Resolve a seed value through the SAME pure engine the masker runs on, so the two
+   * signals below start out agreeing with what the field will actually show.
+   *
+   * WHY THE FACADE DERIVES THIS INSTEAD OF ASKING THE MASKER. A seeded value is the one
+   * case the masker cannot report: it normalizes the text at attach time WITHOUT
+   * notifying, because attaching is not an edit the consumer made. Nor can the facade
+   * provoke it afterwards -- an edit whose raw value comes out unchanged commits nothing
+   * and notifies nobody (`applyEdit` returns early on `nextRaw === raw`), which is
+   * exactly what re-writing the seed is. So without this, a
+   * `<kai-input format="@@@-####" value="chg4821">` would SHOW `CHG-4821` while
+   * `el.value` still read `chg4821`.
+   *
+   * This is a derivation, not a second policy -- `field-mask`, `field-semantics` and the
+   * `DEFAULT_FORMAT` sentinel are all read from where `ui/input.tsx` reads them, so
+   * nothing about the resolution is restated here. A bad format or an unresolvable
+   * `default` falls through unmasked exactly as it does there (the widget is the one
+   * that warns; warning twice for one misconfiguration would be noise).
+   */
+  const throughMask = (text: string): { canonical: string; formatted: string } => {
+    const plain = { canonical: text, formatted: text };
+    if (text === '' || !masked()) return plain;
+    const semantic = (props.semantic as FieldSemanticType | undefined) ?? 'custom';
+    const format = props.format as string;
+    const resolved = format === DEFAULT_FORMAT ? fieldSemantics(semantic).defaultFormat : format;
+    if (resolved === undefined) return plain;
+    try {
+      const pattern = compileMask(resolved, props.guide as string | undefined);
+      const raw = normalizeToRaw(pattern, text, (props.caseMode as CaseMode | undefined) ?? 'preserve');
+      return {
+        canonical: canonicalize(pattern, formatRaw(pattern, raw), semantic),
+        formatted: formatForDisplay(pattern, raw),
+      };
+    } catch {
+      return plain;
+    }
+  };
+
+  // TWO signals, and the split is the whole controlled-value story.
+  //
+  // `value` is the CANONICAL value: what `el.value` reads, what reflects to the `[value]`
+  // attribute, what every event detail carries. `display` is the text the inner input
+  // shows, which under a mask is the FORMATTED text and is not the same string.
+  //
+  // Before the split there was one signal driving both, and it fought the masker: the
+  // masker writes `555-123-4567` into the input, the facade stores the canonical
+  // `5551234567`, and the controlled `value` prop then writes THAT back over the input on
+  // the next flush -- the field un-formats itself one keystroke behind the user. Feeding
+  // Input the display text means the value it writes is the text already there, which the
+  // HTML value setter treats as a no-op (caret included).
+
+  const seed = throughMask(
     (props.value as string | undefined) ?? element.getAttribute('value') ?? '',
   );
+  const [value, setValue] = createSignal(seed.canonical);
+  const [display, setDisplay] = createSignal(seed.formatted);
 
   // Coerce any value coming through the `value` setter (a JS assignment, or the
   // write-back from `attributeChangedCallback`) to a string — falling back to the
@@ -107,18 +265,115 @@ defineWebComponent<Props, Events>('kai-input', {
   const coerce = (v: unknown): string =>
     v == null ? (element.getAttribute('value') ?? '') : String(v);
 
-  // Set the value WITHOUT firing an event (programmatic / reflect write-back).
-  const setQuiet = (next: string) => { if (untrack(value) !== next) setValue(next); };
+  // Set both WITHOUT firing an event (the unmasked path: canonical IS the display text).
+  const setBothQuiet = (next: string) => {
+    if (untrack(value) !== next) setValue(next);
+    if (untrack(display) !== next) setDisplay(next);
+  };
+
+  const innerInput = () => element.shadowRoot?.querySelector<HTMLInputElement>('input') ?? null;
+
+  /** Set while the facade is driving the field itself, so the masker callback it
+   *  provokes updates state without firing `kai-input`. A programmatic write is not a
+   *  keystroke, and the host that performed it already knows what it wrote. */
+  let programmatic = false;
+
+  /**
+   * The single external-write path: `el.value = …`, the `value` attribute, and `clear()`
+   * all land here.
+   *
+   * WITH A MASK it goes THROUGH the masker rather than around it. The masker owns
+   * `input.value`, its own stored value, its undo stack and its caret; writing the input
+   * behind its back leaves it holding a stale string, and the next keystroke reconciles
+   * against that stale string rather than against what is on screen. So: put the text in
+   * the field, then fire the `input` event the masker already listens for, which is its
+   * documented reconcile path (spec §5.1) and ends in the same normalize-format-commit
+   * every edit takes. The masker calls back with the canonical value and the formatted
+   * text is then in the DOM, so both signals come from IT, not from the caller.
+   *
+   * A refusal (wrong characters, over capacity) reports on `kai-input-rejected` and leaves
+   * the field as it was, which is the same contract typing gets.
+   */
+  const writeValue = (next: string, force = false): void => {
+    // The reflect effect below writes `[value]`, which component-register writes back
+    // through this setter. Without this guard that write-back would re-enter the masker on
+    // every value change. `force` is for the one caller that must re-run an equal value.
+    if (!force && untrack(value) === next) return;
+
+    const input = innerInput();
+    if (input === null || !masked()) {
+      setBothQuiet(next);
+      return;
+    }
+
+    programmatic = true;
+    try {
+      input.value = next;
+      input.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+    } finally {
+      programmatic = false;
+    }
+  };
 
   // Override `value` so reads return LIVE state and host writes (`el.value = …`)
   // drive it WITHOUT firing events — distinct from the typing path.
   Object.defineProperty(element, 'value', {
     get: () => value(),
-    set: (v: unknown) => setQuiet(coerce(v)),
+    set: (v: unknown) => writeValue(coerce(v)),
     configurable: true,
     enumerable: true,
   });
 
+  // A CONFIGURATION CHANGE AFTER MOUNT re-derives the canonical value.
+  //
+  // The masker cannot report this one, in either of the two shapes it takes:
+  //
+  //   - `format` ARRIVING on a live field attaches a fresh masker, and attaching seeds
+  //     with `notify: false` on purpose. The display re-formats, `el.value` does not.
+  //   - `update()` notifies only when the FORMATTED text changed, so a reconfiguration
+  //     that moves the canonical value WITHOUT moving the display is silent by design:
+  //     flipping `semantic` from `custom` to `tel` under `###-###-####` turns
+  //     `555-123-4567` into `5551234567` on the wire and changes nothing on screen.
+  //
+  // Either way `el.value` would go on serving a stale canonical value indefinitely -- and
+  // an external write does NOT repair it, because an edit whose raw value comes out
+  // unchanged commits nothing and notifies nobody. Only a keystroke did. So the facade
+  // re-derives, from the text the masker has settled on.
+  //
+  // WHAT IT RE-FITS, and why not simply the text on screen. While a mask is on, the text
+  // on screen can carry GUIDE characters at the unfilled positions, and a guide character
+  // that happens to fit the position class would be absorbed as content on the way back
+  // in. The previous CANONICAL value has no guide in it and is the faithful record of what
+  // the user actually entered, so that is the input -- the same thing `update()` re-fits
+  // from. With no mask there is no canonical form to speak of, so the field text is it.
+  //
+  // WHY A MICROTASK. This effect is created before the JSX below, so on any flush it runs
+  // BEFORE the mask effect inside `Input`: reading or writing here would race the masker
+  // it is trying to agree with. One microtask puts the whole thing after the flush. Where
+  // the masker DID notify (a clipping format change), it has already set the right value
+  // by then and this recomputes the same answer.
+  {
+    let first = true;
+    createEffect(() => {
+      // Tracked deliberately, and these four only: the inputs `throughMask` reads.
+      void props.format;
+      void props.guide;
+      void props.semantic;
+      void props.caseMode;
+      if (first) {
+        // The seed above already did this, synchronously and with no DOM to wait for.
+        first = false;
+        return;
+      }
+      queueMicrotask(() => {
+        const source = masked() ? untrack(value) : (innerInput()?.value ?? untrack(display));
+        const next = throughMask(source);
+        if (untrack(value) !== next.canonical) setValue(next.canonical);
+        if (untrack(display) !== next.formatted) setDisplay(next.formatted);
+      });
+    });
+  }
+
   // Reflect internal value → the `[value]` host attribute (for `:host([value])`).
   // The guard against the live attribute keeps the write-back the reflect triggers
   // (attributeChangedCallback → setter) from looping.
@@ -163,15 +418,30 @@ defineWebComponent<Props, Events>('kai-input', {
   });
   const region = (name: SlotName) => (filled()[name] ? <slot name={name} /> : undefined);
 
-  const innerInput = () => element.shadowRoot?.querySelector<HTMLInputElement>('input') ?? null;
-
   expose({
     /** Focus the inner input (the host can't reach into the shadow root). */
     focus: (options?: FocusOptions) => innerInput()?.focus(options),
     /** Select the inner input's text. */
     select: () => innerInput()?.select(),
-    /** Empty the value and fire `kai-change` with `''`. */
-    clear: () => { setValue(''); dispatch('kai-change', { value: '' }); },
+    /** The canonical value: digits for `tel` / `ssn` / `credit-card`, the formatted text
+     *  for `custom`, and the field text when no mask is on. Identical to reading
+     *  `el.value`, under the name backends use for the submitted form of a masked
+     *  field. The mask engine has a third,
+     *  narrower notion of raw (the fill characters with no literals at all) and that one
+     *  is internal: it is not what any backend wants and it is not exposed here. */
+    getRawValue: (): string => untrack(value),
+    /** The text on screen, literals and guide included. The counterpart to
+     *  `formattedValue` on the `kai-input` / `kai-change` details, for a consumer that
+     *  needs it outside an event. */
+    getFormattedValue: (): string => innerInput()?.value ?? untrack(display),
+    /** Empty the value and fire `kai-change` with `''`. On a masked field this resets the
+     *  mask itself, not just the text on screen, so the next character starts over. */
+    clear: () => {
+      writeValue('', true);
+      // From the signals, not from the DOM: unmasked, the input has not been re-rendered
+      // yet at this point, so the DOM still holds the text that was just cleared.
+      dispatch('kai-change', { value: untrack(value), formattedValue: untrack(display) });
+    },
   });
 
   return (
@@ -179,7 +449,7 @@ defineWebComponent<Props, Events>('kai-input', {
       <style>{':host{display:block}'}</style>
       <Input
         type={(props.type as string) ?? 'text'}
-        value={value()}
+        value={display()}
         placeholder={props.placeholder as string | undefined}
         label={props.label as string | undefined}
         hint={props.hint as string | undefined}
@@ -193,10 +463,29 @@ defineWebComponent<Props, Events>('kai-input', {
         autocomplete={props.autocomplete as InputProps['autocomplete']}
         inputmode={props.inputmode as InputProps['inputmode']}
         autocapitalize={autocapitalize() as InputProps['autocapitalize']}
+        format={props.format as string | undefined}
+        guide={props.guide as string | undefined}
+        semantic={props.semantic as FieldSemanticType | undefined}
+        caseMode={props.caseMode as CaseMode | undefined}
+        copyPolicy={props.copyPolicy as CopyPolicy | undefined}
         leading={region('leading')}
         trailing={region('trailing')}
-        onValueInput={(v) => { setValue(v); dispatch('kai-input', { value: v }); }}
-        onValueChange={(v) => { setQuiet(v); dispatch('kai-change', { value: v }); }}
+        onValueInput={(v) => {
+          // `v` is already canonical (the widget reads it off the masker). The formatted
+          // text is whatever the masker just put in the DOM, so read it from there rather
+          // than re-deriving it -- there is only one thing that knows it.
+          setValue(v);
+          setDisplay(innerInput()?.value ?? v);
+          if (!programmatic) {
+            dispatch('kai-input', { value: v, formattedValue: untrack(display) });
+          }
+        }}
+        onValueChange={(v) => {
+          setValue(v);
+          if (!masked()) setDisplay(v);
+          dispatch('kai-change', { value: v, formattedValue: innerInput()?.value ?? v });
+        }}
+        onMaskReject={(detail) => dispatch('kai-input-rejected', detail)}
       />
     </>
   );

package/src/elements/message.tsx

@@ -285,6 +285,8 @@ defineWebComponent<Props, Events>('kai-message', {
       parts={msg().parts}
       cardTypes={cardComponentsFromTags(props.cardTypes, (props as { theme?: string }).theme)}
       cardSchemas={props.cardSchemas}
+      /* F-26: card parts emit off THIS element as the bubbling `kai-card` event. */
+      cardHostElement={element}
       isUser={isUser()}
       markdown={useMarkdown()}
       actions={mergedActions()}

package/src/elements/pane-grid.tsx

@@ -0,0 +1,111 @@
+import { createSignal, onMount, onCleanup, Index } from 'solid-js';
+import { defineWebComponent } from './define';
+import { PaneGrid } from '../ui/pane-grid';
+
+interface Props extends Record<string, unknown> {
+  /** Minimum width of every pane, in px, before columns drop / the grid scrolls.
+   *  Defaults to `280`. Attribute: `min-pane-width`. */
+  minPaneWidth?: number;
+  /** Minimum height of every pane, in px, before the grid scrolls vertically.
+   *  Defaults to `200`. Attribute: `min-pane-height`. */
+  minPaneHeight?: number;
+  /** Column cap when the container is wide (default `3`). Attribute: `max-columns`. */
+  maxColumns?: number;
+  /** Gap between panes, any CSS length. Defaults to the kit gap
+   *  (`var(--kai-pane-grid-gap, 0.5rem)`). Attribute: `gap`. */
+  gap?: string;
+  /** When set to a valid child index, render ONLY that pane full-bleed: a simple
+   *  maximize hook the consumer drives (pair it with `<kai-pane>`'s `kai-maximize`
+   *  event). Clear it (or point out of range) for the full tiled grid.
+   *  Attribute: `maximized-index`. */
+  maximizedIndex?: number | null;
+}
+
+/** Attribute values arrive as strings; blank/invalid → undefined (the default). */
+function num(value: unknown): number | undefined {
+  if (value == null || value === '') return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * `<kai-pane-grid>` — an N-pane responsive tiling grid with a min-size + scroll
+ * floor. Each direct light child is one tile: the grid fills up to `max-columns`
+ * columns when wide, DROPS columns as the container narrows so panes never squish
+ * below `min-pane-width`, then SCROLLS once even one column can't fit. Rows keep
+ * at least `min-pane-height` the same way. The natural children are `<kai-pane>` /
+ * `<kai-pane-group>`, but any elements tile.
+ *
+ * ```html
+ * <kai-pane-grid max-columns="2" min-pane-width="320" style="height: 480px">
+ *   <kai-pane headline="Atlas">…</kai-pane>
+ *   <kai-pane headline="Otto">…</kai-pane>
+ *   <kai-pane headline="Nova">…</kai-pane>
+ * </kai-pane-grid>
+ * ```
+ *
+ * Maximize: set `maximized-index` to a child index to show only that pane
+ * full-bleed; clear it to restore. The grid never decides this itself — drive it
+ * from your own control (e.g. `<kai-pane>`'s `kai-maximize` event). Scalar
+ * attributes only; no events.
+ *
+ * Under the shadow root each pane child is projected through its own named slot
+ * (assigned automatically — an author-set `slot` attribute on a direct child is
+ * respected and left alone), so the light children become the grid tiles directly.
+ */
+defineWebComponent<Props>('kai-pane-grid', {
+  minPaneWidth: undefined,
+  minPaneHeight: undefined,
+  maxColumns: undefined,
+  gap: undefined,
+  maximizedIndex: undefined,
+}, (props, { element }) => {
+  // One named slot per direct light child, in child order. The slot names are
+  // written onto the children (`pane-<i>`), the same per-child-slot pattern
+  // <kai-resizable> uses (`p0`/`p1`/…): PaneGrid tiles its JSX children, and a
+  // single default <slot> would make ALL panes one tile. A child that already
+  // carries an author-set slot attribute outside our namespace is left alone
+  // (and therefore not tiled) — authoring escape hatch, same as unslotted text.
+  const [slotNames, setSlotNames] = createSignal<string[]>([]);
+
+  onMount(() => {
+    const read = () => {
+      const names: string[] = [];
+      let i = 0;
+      for (const child of Array.from(element.children)) {
+        const existing = child.getAttribute('slot');
+        if (existing !== null && !/^pane-\d+$/.test(existing)) continue; // author-owned
+        const name = `pane-${i++}`;
+        if (existing !== name) child.setAttribute('slot', name);
+        names.push(name);
+      }
+      // Structural equality: our own setAttribute('slot') writes re-fire the
+      // observer; an unchanged name list means an unchanged layout, so skip the
+      // re-render (mirrors <kai-resizable>'s itemsChanged guard).
+      if (names.length !== slotNames().length || names.some((n, j) => n !== slotNames()[j])) {
+        setSlotNames(names);
+      }
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  return (
+    <>
+      {/* A tiling grid fills its container — default the host to a stretching
+          block, same as <kai-resizable>. Give the element (or a parent) a height. */}
+      <style>{':host{display:block;height:100%;min-height:0;min-width:0}'}</style>
+      <PaneGrid
+        minPaneWidth={num(props.minPaneWidth)}
+        minPaneHeight={num(props.minPaneHeight)}
+        maxColumns={num(props.maxColumns)}
+        gap={props.gap as string | undefined}
+        maximizedIndex={num(props.maximizedIndex) ?? null}
+      >
+        <Index each={slotNames()}>{(name) => <slot name={name()} />}</Index>
+      </PaneGrid>
+    </>
+  );
+});

package/src/elements/prompt-input.tsx

@@ -49,7 +49,11 @@ interface Props extends Record<string, unknown> {
   attach?: boolean;
   /** Attachments to seed the input with (so a consumer can pre-populate staged
    *  files without an upload). Set as a JS property; the element then manages its
-   *  own attachment state from there (add via the paperclip, remove per chip). */
+   *  own attachment state from there (add via the paperclip, remove per chip).
+   *  Each item's `url` must be a `data:` URI or an https URL, never
+   *  `URL.createObjectURL`: a `blob:` URL previews perfectly and is meaningless
+   *  outside this tab, so `toOpenAIMessages`/`toAnthropicMessages` refuse it.
+   *  (The built-in paperclip already stages files as `data:` URIs.) */
   attachments?: AttachmentData[];
   /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored menu
    *  that inserts an atomic pill. Convention: `/` → skills, `@` → agents (plugins
@@ -64,7 +68,9 @@ interface Props extends Record<string, unknown> {
 interface Events {
   /** The user submitted the prompt (Enter or send button). `value` is the
    *  flattened text (back-compat); `doc` is the structured document and
-   *  `entities` the inserted pills (skills/agents) for downstream expansion. */
+   *  `entities` the inserted pills (skills/agents) for downstream expansion.
+   *  `<kai-prompt-input>` is the batteries-included composer row (send button,
+   *  toolbar, attachment staging) built on `<kai-composer>`, the bare editor. */
   'kai-submit': { value: string; doc: ComposerDoc; entities: EntityRef[]; attachments: AttachmentData[] };
   /** The input changed (fires on every edit). Carries the flattened `value`
    *  plus the structured `doc` + `entities`. */