@kitn.ai/ui 0.25.2 → 0.27.0

package/src/components/tasks-card.tsx

@@ -14,6 +14,7 @@ import {
 } from 'solid-js';
 import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
+import { Checkbox } from '../ui/checkbox';
 import { ProgressBar } from '../ui/progress-bar';
 import { Card } from './card';
 import { DismissedStub } from './dismissed-stub';
@@ -21,7 +22,7 @@ import type { CardEnvelope, CardEvent, CardHost, CardResolution } from '../primi
 import { useCardResolution } from './use-card-resolution';
 import { emitCardEvent } from '../primitives/card-routing';
 import { useCardHost } from '../primitives/card-host';
-import { Check, Circle, CircleCheck, X } from 'lucide-solid';
+import { Check, Circle, CircleCheck } from 'lucide-solid';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types (tasks.schema.json) — AUTHORED IN ../primitives/card-data-types.ts.
@@ -415,14 +416,23 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
             progress() || res.isResolved() || readOnly() ? undefined : (
               <div class="flex w-full flex-wrap items-center justify-between gap-2">
                 <Show when={local.data?.dismissible === true}>
+                  {/* The contract `dismiss` verb — a footer ACTION (it emits
+                      `{kind:'dismiss'}` and collapses the card to a re-openable
+                      stub), not the chrome close in `Card`'s own `dismissible`
+                      prop, which the contract cards deliberately never set.
+                      Labelled rather than a bare ghost ✕: every other control in
+                      this row says what it does, and an unlabelled 28px glyph
+                      300px from the primary button reads as stray chrome. Same
+                      shape in all four cards — `form` already looked like this.
+                      `aria-label` is kept (redundant with the text) so the
+                      element tests that select on it keep working. */}
                   <Button
                     type="button"
                     variant="ghost"
-                    size="icon-sm"
                     aria-label="Dismiss"
                     onClick={onDismiss}
                   >
-                    <X size={16} aria-hidden="true" />
+                    Dismiss
                   </Button>
                 </Show>
                 <span id={countId} aria-live="polite" class="text-xs text-muted-foreground">
@@ -485,7 +495,7 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
                 if (confirmEnabled()) onConfirm();
               }}
             >
-              <div class="divide-y divide-border overflow-hidden rounded-lg border border-input">
+              <div class="divide-y divide-border overflow-hidden rounded-lg border border-border">
                 <Show when={showMaster()}>
                   {(() => {
                     const indeterminate = () => masterState() === 'indeterminate';
@@ -501,17 +511,20 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
                               : 'text-foreground hover:bg-muted/50',
                         )}
                       >
-                        <input
-                          type="checkbox"
-                          class="kai-checkbox"
+                        {/* SQUARE `Checkbox` (the `.kai-checkbox` look), and the checklist below draws a
+                            ROUND lucide Circle/CircleCheck instead. Deliberate, not drift: this
+                            is `select` mode — a pick-list whose rows are a pending selection that
+                            only commits when the confirm button fires, which is what a checkbox
+                            means everywhere else. `progress` mode has no confirm and toggling a
+                            row IS the action, so it uses the done/not-done affordance of a todo
+                            list. See the D-2 row in
+                            docs/superpowers/plans/2026-08-25-form-control-primitives.md; owner has
+                            not ruled, so do not converge these on your own. */}
+                        <Checkbox
                           checked={masterState() === 'checked'}
                           disabled={groupDisabled() || readOnly()}
+                          indeterminate={indeterminate()}
                           aria-checked={indeterminate() ? 'mixed' : masterState() === 'checked'}
-                          ref={(el) => {
-                            createEffect(() => {
-                              el.indeterminate = indeterminate();
-                            });
-                          }}
                           onChange={(e) => toggleAll(e.currentTarget.checked)}
                         />
                         <span>Select all</span>
@@ -541,9 +554,8 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
                         )}
                         data-task-id={task.id}
                       >
-                        <input
-                          type="checkbox"
-                          class="kai-checkbox mt-0.5"
+                        <Checkbox
+                          class="mt-0.5"
                           checked={checked()}
                           disabled={blocked() || readOnly()}
                           aria-disabled={blocked() ? 'true' : undefined}
@@ -603,7 +615,10 @@ function ProgressChecklist(props: {
     <div class={cn('flex flex-col gap-3', props.groupClass)}>
       <Show when={props.heading}>
         <div class="flex items-center justify-between gap-3">
-          <span id={props.headingId} class="text-sm font-medium text-foreground">
+          <span
+            id={props.headingId}
+            class="text-title font-semibold tracking-tight text-foreground"
+          >
             {props.heading}
           </span>
           <span
@@ -646,8 +661,23 @@ function ProgressChecklist(props: {
                     // row doesn't leave a noisy persistent outline — and it makes a
                     // Tab-focused completed row's open description perceivable. Dropped
                     // entirely when readonly (the row isn't focusable then).
+                    //
+                    // TWO tab stops exist per row and the ring has to cover both.
+                    // `focus-visible:` matches only when the LABEL itself is focused,
+                    // which is completed rows only (the `tabindex` below). Every row's
+                    // other — and for an incomplete row, only — tab stop is the sr-only
+                    // checkbox inside, so without `has-[:focus-visible]:` tabbing to an
+                    // unchecked row put focus on an off-screen input with no indicator
+                    // anywhere on screen. Both halves stay on the focus-VISIBLE axis on
+                    // purpose: `focus-within:` would also fire for a mouse click (which
+                    // forwards focus from the label to the checkbox), which is exactly
+                    // the persistent-outline noise the paragraph above rejects. The
+                    // description reveal below uses `group-focus-within:` because a
+                    // hover-or-focus reveal wants the looser condition.
                     !props.readonly &&
                       'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring',
+                    !props.readonly &&
+                      'has-[:focus-visible]:outline-none has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-inset has-[:focus-visible]:ring-ring',
                     props.readonly
                       ? 'cursor-default'
                       : blocked()
@@ -680,6 +710,18 @@ function ProgressChecklist(props: {
                     )}
                     aria-hidden="true"
                   >
+                    {/* ROUND, where `select` mode uses the square `Checkbox`. Deliberate:
+                        this mode has no confirm button, so ticking a row IS the action and the
+                        row is done-or-not rather than selected-or-not — the todo-list
+                        affordance, which is how this mode has been described since it landed
+                        (see the `mode` argType in tasks-card.stories.tsx and the JSDoc on
+                        src/elements/tasks.tsx). D-2 in
+                        docs/superpowers/plans/2026-08-25-form-control-primitives.md tracks
+                        whether to keep the split; unruled, so leave both. NOTE the cost: the
+                        icon replaces the visible native control, which is why the real input
+                        above is `sr-only` and why the row's focus ring has to be driven by
+                        `has-[:focus-visible]:`. Converging on `Checkbox` would take that
+                        hazard away with it. */}
                     <Show
                       when={checked()}
                       fallback={<Circle size={18} />}

package/src/components/thread.tsx

@@ -34,6 +34,11 @@ export interface ThreadProps {
    *  the kit checks its own seven built-ins and leaves your own card type
    *  unvalidated. A schema here WINS over a built-in of the same name. */
   cardSchemas?: CardSchemaMap;
+  /** The custom-element host node to emit card events off when no `CardProvider`
+   *  is present, forwarded through `MessageBody` to `CardRenderer`. The
+   *  element facades pass their own host element so card events leave as the
+   *  bubbling `kai-card` CustomEvent. */
+  cardHostElement?: HTMLElement;
   /** Show a typing indicator on the pending assistant turn — use while awaiting
    *  the assistant's reply. */
   loading?: boolean;
@@ -146,6 +151,7 @@ export function Thread(props: ThreadProps) {
                         parts={m().parts}
                         cardTypes={props.cardTypes}
                         cardSchemas={props.cardSchemas}
+                        cardHostElement={props.cardHostElement}
                         isUser={m().role === 'user'}
                         markdown={m().role === 'assistant'}
                         actions={m().actions}
@@ -209,7 +215,10 @@ export function Thread(props: ThreadProps) {
           </ChatContainerContent>
           <Show when={showScrollButton()}>
             <div class="absolute bottom-4 left-1/2 flex w-full max-w-3xl -translate-x-1/2 justify-center px-5">
-              <ScrollButton class="shadow-sm" />
+              {/* The button now owns its elevation (kai-elevation); a `shadow-sm`
+                  here would set box-shadow a second time and the winner would
+                  be stylesheet order, not this call site. */}
+              <ScrollButton />
             </div>
           </Show>
         </ChatContainer>

package/src/components/toast.tsx

@@ -320,11 +320,17 @@ function anchorStyle(position: ToastPosition, r: TargetRect): Record<string, str
   }
 }
 
+/** The overlay layer both region roots sit on. One token, one default:
+ *  your app chrome must stay below the toast layer; set `--kai-toast-z`
+ *  (default 100) on the host to move the layer. */
+const TOAST_Z = 'var(--kai-toast-z, 100)';
+
 /**
  * Renders a stack of toasts at a viewport edge. Caps the visible count at `max`
  * (newest on top); overflow waits in a queue and is promoted as visible toasts
  * leave. `aria-live=polite` / `role=region` so screen readers announce new
- * toasts without stealing focus.
+ * toasts without stealing focus. Your app chrome must stay below the toast
+ * layer; set `--kai-toast-z` (default 100) on the host to move the layer.
  */
 export function ToastRegion(props: ToastRegionProps) {
   const max = () => props.max ?? 3;
@@ -425,12 +431,12 @@ export function ToastRegion(props: ToastRegionProps) {
           aria-live="polite"
           data-stack="expanded"
           class={cn(
-            'pointer-events-none fixed z-[100] flex flex-col gap-2',
+            'pointer-events-none fixed flex flex-col gap-2',
             anchor()
               ? ANCHOR_FLEX[position()]
               : cn('max-w-[min(30rem,calc(100vw-2rem))]', POSITION_CLASSES[position()]),
           )}
-          style={anchor() ? anchorStyle(position(), anchor()!) : undefined}
+          style={{ 'z-index': TOAST_Z, ...(anchor() ? anchorStyle(position(), anchor()!) : undefined) }}
         >
           <For each={visible()}>
             {(item) => (
@@ -456,8 +462,8 @@ export function ToastRegion(props: ToastRegionProps) {
         onPointerLeave={() => setHovered(false)}
         onFocusIn={() => setFocused(true)}
         onFocusOut={() => setFocused(false)}
-        class={cn('pointer-events-none fixed z-[100]', !anchor() && POSITION_CLASSES[position()])}
-        style={anchor() ? anchorStyle(position(), anchor()!) : undefined}
+        class={cn('pointer-events-none fixed', !anchor() && POSITION_CLASSES[position()])}
+        style={{ 'z-index': TOAST_Z, ...(anchor() ? anchorStyle(position(), anchor()!) : undefined) }}
       >
         {/* Relative stage with an explicit height so it's ONE continuous hover
             surface (pointer-events-auto) — no flicker when the cursor crosses gaps

package/src/components/tool-types.ts

@@ -25,6 +25,15 @@ export interface ToolPart {
   type: string;
   /** Semantic classification for rendering. Derive with classifyTool(type). */
   kind?: ToolKind;
+  /** The call's lifecycle. A provider stream (real or `createMockResponder`)
+   *  only ever ANNOUNCES a call: arguments stream in (`input-streaming`), then
+   *  the part parks at `input-available` — and stays there. The kit parses and
+   *  renders the call; EXECUTING it and answering is the host's side of the
+   *  seam: after the read settles, run the tool and patch the part forward with
+   *  `stream.upsertTool(id, { state: 'output-available', output })` (or
+   *  `upsertToolPart`), or `output-error` + `errorText` on failure. The one
+   *  exception is a call the provider ran itself (`raw` carries the result and
+   *  the wire sets `output` directly) — never re-execute those. */
   state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
   /** Last VALID parsed snapshot, fingerprint-deduped. The primary channel: this is
    *  what the kit renders. */

package/src/components/voice-input.tsx

@@ -38,6 +38,10 @@ export interface VoiceInputProps {
   /** Receive the imperative controller once mounted. The `<kai-voice-input>`
    *  facade forwards these as element methods (start/stop). */
   controllerRef?: (controller: VoiceInputController) => void;
+  /** A recognition session failed or produced nothing. `error` is the platform
+   *  error code, the thrown exception's name, or `no-result` when the session
+   *  ended with no error and no text. The facade maps this to kai-voice-error. */
+  onError?: (detail: { source: 'recognition'; error: string; message: string }) => void;
 }
 
 export function VoiceInput(props: VoiceInputProps) {
@@ -59,15 +63,43 @@ export function VoiceInput(props: VoiceInputProps) {
 
   // Native path: SpeechRecognition resolves with the final transcript when it
   // ends (click again or controller.stop()). Final text → onTranscription.
+  // Every other outcome reaches onError, so a session can never end in silence
+  // (W4 symptom 1: runtime errors set a signal nothing read, and an empty
+  // result fired no event at all).
   async function beginRecognition() {
+    let errored = false;
     try {
       const text = await speech.start({
         lang: props.lang,
         onInterim: props.interim ? (t) => props.onInterim?.(t) : undefined,
+        onError: (error, message) => {
+          errored = true;
+          props.onError?.({ source: 'recognition', error, message });
+        },
       });
-      if (text.trim()) local.onTranscription(text.trim());
-    } catch {
-      /* surfaced via speech.error; the mic returns to idle */
+      if (text.trim()) {
+        local.onTranscription(text.trim());
+      } else if (!errored) {
+        // No error, no text: the session ended cleanly having heard nothing.
+        // Reported through the SAME error event (as `no-result`) rather than an
+        // empty kai-transcription, so kai-transcription keeps its contract
+        // (final text exists) and one listener covers every failed session; the
+        // code distinguishes "user said nothing" from "recognition broke".
+        props.onError?.({
+          source: 'recognition',
+          error: 'no-result',
+          message: 'Speech recognition ended without capturing any text',
+        });
+      }
+    } catch (err) {
+      // start() itself threw (unsupported, or the platform refused to start).
+      if (!errored) {
+        props.onError?.({
+          source: 'recognition',
+          error: err instanceof Error ? err.name : 'unknown',
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
     }
   }
 

package/src/components/voice-output.tsx

@@ -26,8 +26,15 @@ export interface VoiceOutputProps {
   /** TTS model seam: given text, return an audio Blob to play. When set, the
    *  native speechSynthesis path is bypassed. Mirrors VoiceInput's `onTranscribe`. */
   onSynthesize?: (text: string) => Promise<Blob>;
-  /** Fires whenever playback starts or stops. */
+  /** Fires whenever playback starts or stops. `speaking: true` means audio has
+   *  actually started (utterance.onstart on the native path; audio.play()
+   *  resolving on the model path), not that speak() was called. */
   onSpeakingChange?: (speaking: boolean) => void;
+  /** Synthesis failed: a native utterance error, a rejecting `onSynthesize`, or
+   *  audio playback failing to start. `error` is the platform error code or the
+   *  exception's name. Deliberate cancellation (stop(), a new speak()) is not a
+   *  failure and does not fire. The facade maps this to kai-voice-error. */
+  onError?: (detail: { source: 'synthesis'; error: string; message: string }) => void;
   /** Fires once the model path resolves audio (model path only). */
   onSynthesized?: (blob: Blob) => void;
   disabled?: boolean;
@@ -68,13 +75,30 @@ export function VoiceOutput(props: VoiceOutputProps) {
   }
 
   // Native path: speechSynthesis.speak(new SpeechSynthesisUtterance(text)).
+  // isSpeaking waits for utterance.onstart, so onSpeakingChange(true) means the
+  // audio actually began. It used to flip optimistically before speak(), which
+  // made "speaking" mean "speak() was called" and raced consumers watching for
+  // playback to start (W4 symptom 3).
   function speakNative() {
     if (!hasSpeechSynthesis() || !local.text) return;
     window.speechSynthesis.cancel();
     utterance = new SpeechSynthesisUtterance(local.text);
+    utterance.onstart = () => setIsSpeaking(true);
     utterance.onend = () => setIsSpeaking(false);
-    utterance.onerror = () => setIsSpeaking(false);
-    setIsSpeaking(true);
+    utterance.onerror = (event) => {
+      setIsSpeaking(false);
+      const code = event?.error ?? 'unknown';
+      // `canceled`/`interrupted` are what the platform reports when the app
+      // itself cancels (stop(), or a new speak() pre-empting): deliberate, not
+      // a failure. Everything else surfaces (W4 traced a `not-allowed` here
+      // that vanished without a word).
+      if (code === 'canceled' || code === 'interrupted') return;
+      props.onError?.({
+        source: 'synthesis',
+        error: code,
+        message: `Speech synthesis error: ${code}`,
+      });
+    };
     window.speechSynthesis.speak(utterance);
   }
 
@@ -90,11 +114,27 @@ export function VoiceOutput(props: VoiceOutputProps) {
       audio ??= new Audio();
       audio.src = objectUrl;
       audio.onended = () => setIsSpeaking(false);
-      audio.onerror = () => setIsSpeaking(false);
-      setIsSpeaking(true);
+      audio.onerror = () => {
+        setIsSpeaking(false);
+        props.onError?.({
+          source: 'synthesis',
+          error: 'playback-failed',
+          message: 'The synthesized audio failed to play',
+        });
+      };
       await audio.play();
-    } catch {
+      // play() resolving is this path's "audio actually started" (the model
+      // path's counterpart of utterance.onstart), so isSpeaking flips only now.
+      setIsSpeaking(true);
+    } catch (err) {
+      // onSynthesize rejected, or play() did (e.g. NotAllowedError under an
+      // autoplay policy). Either way the reply is silent: say so.
       setIsSpeaking(false);
+      props.onError?.({
+        source: 'synthesis',
+        error: err instanceof Error ? err.name : 'unknown',
+        message: err instanceof Error ? err.message : String(err),
+      });
     } finally {
       setIsLoading(false);
     }

package/src/components/workspace-shell.tsx

@@ -0,0 +1,285 @@
+import { Show, createSignal, createMemo, onMount, onCleanup, type JSX } from 'solid-js';
+import { createControllableSignal } from '../primitives/controllable';
+import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '../ui/resizable';
+import { cn } from '../utils/cn';
+
+/** The two aside columns of the shell, named logically (`start` follows the
+ *  writing direction; on an RTL page it is the right column). */
+export type WorkspaceAsideSide = 'start' | 'end';
+
+/** Detail of an aside collapse/expand, however it happened (a method, the
+ *  breakpoint, the drawer's Escape). */
+export interface WorkspaceAsideToggleDetail {
+  side: WorkspaceAsideSide;
+  collapsed: boolean;
+}
+
+/** Detail of an aside resize (fires per drag step, keyboard nudge, or a handle double-click reset), width in px. */
+export interface WorkspaceAsideResizeDetail {
+  side: WorkspaceAsideSide;
+  width: number;
+}
+
+/** Imperative surface exposed through `controllerRef` (the facade forwards it
+ *  as element methods). */
+export interface WorkspaceShellController {
+  /** Collapse/expand one aside (reports through onAsideToggle). */
+  toggleAside(side: WorkspaceAsideSide): void;
+  /** Force one aside collapsed (reports through onAsideToggle). */
+  collapseAside(side: WorkspaceAsideSide): void;
+  /** Force one aside expanded (reports through onAsideToggle). */
+  expandAside(side: WorkspaceAsideSide): void;
+}
+
+export interface WorkspaceShellProps {
+  /** Header band content. The region renders only when this is provided. */
+  header?: JSX.Element;
+  /** Start aside content (the inline-start column: a rail, a nav, a file tree).
+   *  The region renders only when this is provided. */
+  start?: JSX.Element;
+  /** End aside content (the inline-end column: inspector, notes, preview).
+   *  The region renders only when this is provided. */
+  end?: JSX.Element;
+  /** Footer band content. The region renders only when this is provided. */
+  footer?: JSX.Element;
+  /** Main region content. Always rendered. */
+  children?: JSX.Element;
+
+  /** Controlled collapsed state of the start aside. Omit for uncontrolled. */
+  startCollapsed?: boolean;
+  /** Initial collapsed state of the start aside when uncontrolled (default false). */
+  defaultStartCollapsed?: boolean;
+  /** Controlled collapsed state of the end aside. Omit for uncontrolled. */
+  endCollapsed?: boolean;
+  /** Initial collapsed state of the end aside when uncontrolled (default false). */
+  defaultEndCollapsed?: boolean;
+
+  /** Start aside default width in px (default 280). */
+  startWidth?: number;
+  /** Start aside minimum width in px during resize (default 200). */
+  startMinWidth?: number;
+  /** Start aside maximum width in px during resize (default 480). */
+  startMaxWidth?: number;
+  /** End aside default width in px (default 320). */
+  endWidth?: number;
+  /** End aside minimum width in px during resize (default 200). */
+  endMinWidth?: number;
+  /** End aside maximum width in px during resize (default 480). */
+  endMaxWidth?: number;
+
+  /** Auto-collapse both asides when the shell's own width drops below this many
+   *  px, and re-expand when it grows back above. Applies to uncontrolled asides
+   *  only (it never fights an app-driven collapsed prop); omit to disable. */
+  collapseBelow?: number;
+  /** Below this shell width in px, an expanded aside renders as an overlay
+   *  drawer over the main region instead of a column beside it. Escape inside
+   *  the drawer closes it and returns focus to the element focused before it
+   *  opened. Omit to disable. */
+  drawerBelow?: number;
+  /** Density hint. Reflected as a `data-compact` hook on the root (and as the
+   *  `compact` attribute on the element) for your CSS and slotted content; the
+   *  shell itself keeps no other opinion about density. */
+  compact?: boolean;
+
+  /** An aside collapsed or expanded (any path: method, breakpoint, drawer Escape). */
+  onAsideToggle?: (detail: WorkspaceAsideToggleDetail) => void;
+  /** The aside was resized (fires per drag step, keyboard nudge, or a handle double-click reset), width in px. */
+  onAsideResize?: (detail: WorkspaceAsideResizeDetail) => void;
+
+  /** Receives the imperative controller once on mount. */
+  controllerRef?: (controller: WorkspaceShellController) => void;
+  class?: string;
+}
+
+/**
+ * The chat-agnostic workspace layout shell: five regions (header · start aside ·
+ * main · end aside · footer) with resize handles between the columns, per-aside
+ * controlled/uncontrolled collapse, collapse-below-breakpoint, and a mobile
+ * drawer mode for the asides. It knows nothing about chat: a file tree in
+ * `start` is as valid as a conversation rail.
+ */
+export function WorkspaceShell(props: WorkspaceShellProps) {
+  let rootEl!: HTMLDivElement;
+
+  // --- host width (drives collapseBelow + drawerBelow) ---
+  const [hostWidth, setHostWidth] = createSignal<number | undefined>(undefined);
+
+  // --- per-aside collapse: controlled wins, otherwise internal state ---
+  const [startCollapsed, setStartCollapsed] = createControllableSignal(
+    () => props.startCollapsed,
+    props.defaultStartCollapsed ?? false,
+  );
+  const [endCollapsed, setEndCollapsed] = createControllableSignal(
+    () => props.endCollapsed,
+    props.defaultEndCollapsed ?? false,
+  );
+  const collapsed = (side: WorkspaceAsideSide) => (side === 'start' ? startCollapsed() : endCollapsed());
+  const isControlled = (side: WorkspaceAsideSide) =>
+    (side === 'start' ? props.startCollapsed : props.endCollapsed) !== undefined;
+
+  const setCollapsedTo = (side: WorkspaceAsideSide, next: boolean) => {
+    if (side === 'start') setStartCollapsed(next); else setEndCollapsed(next);
+    if (next) restoreDrawerFocus(side);
+    props.onAsideToggle?.({ side, collapsed: next });
+  };
+
+  // --- drawer mode + focus return ---
+  const drawerMode = createMemo(() => {
+    const below = props.drawerBelow;
+    const width = hostWidth();
+    return below != null && width != null && width < below;
+  });
+  // The element focused when a drawer opened, restored on close. Per side, so a
+  // start drawer closing never steals focus a later end drawer captured.
+  const drawerOpeners: Partial<Record<WorkspaceAsideSide, HTMLElement>> = {};
+  const captureDrawerFocus = (side: WorkspaceAsideSide) => {
+    if (!drawerMode()) return;
+    const active = document.activeElement;
+    if (active instanceof HTMLElement) drawerOpeners[side] = active;
+  };
+  const restoreDrawerFocus = (side: WorkspaceAsideSide) => {
+    const opener = drawerOpeners[side];
+    delete drawerOpeners[side];
+    if (drawerMode() && opener && opener.isConnected) opener.focus();
+  };
+
+  const expand = (side: WorkspaceAsideSide) => {
+    captureDrawerFocus(side);
+    setCollapsedTo(side, false);
+  };
+  const controller: WorkspaceShellController = {
+    toggleAside: (side) => (collapsed(side) ? expand(side) : setCollapsedTo(side, true)),
+    collapseAside: (side) => setCollapsedTo(side, true),
+    expandAside: (side) => expand(side),
+  };
+  props.controllerRef?.(controller);
+
+  // --- collapse-below-breakpoint (uncontrolled asides only) ---
+  // `autoCollapsed` tracks whether WE collapsed a side, so crossing back above
+  // the breakpoint never expands an aside the user collapsed themselves.
+  const autoCollapsed: Record<WorkspaceAsideSide, boolean> = { start: false, end: false };
+  const applyBreakpoint = (width: number) => {
+    const below = props.collapseBelow;
+    if (below == null) return;
+    const isBelow = width < below;
+    for (const side of ['start', 'end'] as const) {
+      // A side with no content has nothing to collapse; reporting a toggle for
+      // a region that does not exist would be noise, not loudness.
+      if (!asideContent(side)) continue;
+      if (isControlled(side)) continue;
+      if (isBelow && !collapsed(side)) {
+        autoCollapsed[side] = true;
+        setCollapsedTo(side, true);
+      } else if (!isBelow && collapsed(side) && autoCollapsed[side]) {
+        autoCollapsed[side] = false;
+        setCollapsedTo(side, false);
+      }
+    }
+  };
+
+  onMount(() => {
+    if (typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver((entries) => {
+      const width = entries[0]?.contentRect.width ?? rootEl.clientWidth;
+      setHostWidth(width);
+      applyBreakpoint(width);
+    });
+    ro.observe(rootEl);
+    onCleanup(() => ro.disconnect());
+  });
+
+  // --- widths ---
+  const widths = (side: WorkspaceAsideSide) =>
+    side === 'start'
+      ? {
+          size: props.startWidth ?? 280,
+          min: props.startMinWidth ?? 200,
+          max: props.startMaxWidth ?? 480,
+        }
+      : {
+          size: props.endWidth ?? 320,
+          min: props.endMinWidth ?? 200,
+          max: props.endMaxWidth ?? 480,
+        };
+
+  // --- drawer Escape: scoped to the drawer (never a document listener, never
+  // swallowed — the kai-dock rule at page scale) ---
+  const onDrawerKeyDown = (side: WorkspaceAsideSide) => (event: KeyboardEvent) => {
+    if (event.key !== 'Escape') return;
+    setCollapsedTo(side, true);
+  };
+
+  const asideRefs: Partial<Record<WorkspaceAsideSide, HTMLElement>> = {};
+  const emitResize = (side: WorkspaceAsideSide) => {
+    const el = asideRefs[side];
+    if (!el) return;
+    props.onAsideResize?.({ side, width: el.getBoundingClientRect().width });
+  };
+
+  const asideContent = (side: WorkspaceAsideSide) => (side === 'start' ? props.start : props.end);
+
+  /** An aside as a resizable column (desktop mode). */
+  const asideColumn = (side: WorkspaceAsideSide) => {
+    const w = widths(side);
+    return (
+      <ResizablePanel
+        defaultSize={`${w.size}px`}
+        minSize={`${w.min}px`}
+        maxSize={`${w.max}px`}
+        part={side === 'start' ? 'aside start' : 'aside end'}
+        ref={(el: HTMLElement) => (asideRefs[side] = el)}
+        class="bg-surface"
+      >
+        {asideContent(side)}
+      </ResizablePanel>
+    );
+  };
+
+  /** An aside as an overlay drawer (mobile mode). */
+  const asideDrawer = (side: WorkspaceAsideSide) => (
+    <div
+      part={side === 'start' ? 'aside start' : 'aside end'}
+      data-drawer=""
+      class={cn(
+        'absolute inset-y-0 z-20 max-w-[85%] overflow-auto border-border bg-surface shadow-lg',
+        side === 'start' ? 'start-0 border-e' : 'end-0 border-s',
+      )}
+      style={{ width: `${widths(side).size}px` }}
+      onKeyDown={onDrawerKeyDown(side)}
+    >
+      {asideContent(side)}
+    </div>
+  );
+
+  const showAside = (side: WorkspaceAsideSide) => !!asideContent(side) && !collapsed(side);
+
+  return (
+    <div
+      ref={rootEl}
+      class={cn('flex h-full w-full flex-col overflow-hidden bg-background', props.class)}
+      data-compact={props.compact ? '' : undefined}
+    >
+      <Show when={props.header}>
+        <div part="header" class="shrink-0 border-b border-border">{props.header}</div>
+      </Show>
+      <div class="relative min-h-0 flex-1">
+        <ResizablePanelGroup orientation="horizontal">
+          <Show when={showAside('start') && !drawerMode()}>
+            {asideColumn('start')}
+            <ResizableHandle onPanelResize={() => emitResize('start')} />
+          </Show>
+          <ResizablePanel part="main">{props.children}</ResizablePanel>
+          <Show when={showAside('end') && !drawerMode()}>
+            <ResizableHandle onPanelResize={() => emitResize('end')} />
+            {asideColumn('end')}
+          </Show>
+        </ResizablePanelGroup>
+        <Show when={showAside('start') && drawerMode()}>{asideDrawer('start')}</Show>
+        <Show when={showAside('end') && drawerMode()}>{asideDrawer('end')}</Show>
+      </div>
+      <Show when={props.footer}>
+        <div part="footer" class="shrink-0 border-t border-border">{props.footer}</div>
+      </Show>
+    </div>
+  );
+}