@kitn.ai/ui 0.25.2 → 0.27.0

package/src/elements/chat-workspace.tsx

@@ -1,148 +1,125 @@
-import { Show, createSignal, onMount, onCleanup } from 'solid-js';
+import { createSignal, onMount, onCleanup, untrack } from 'solid-js';
 import { defineWebComponent } from './define';
-import { createControllableSignal } from '../primitives/controllable';
 import { readSlots, WORKSPACE_SLOTS } from './slots';
-import { ChatThread, type ChatThreadContextUsage, type ChatThreadController } from '../components/chat-thread';
-import { ConversationList, CollapsedRail } from '../components/conversation-list';
-import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '../ui/resizable';
-import { cardComponentsFromTags } from './message';
-import { createMessagesGuard } from './validate-messages';
-import type { AttachmentData } from '../components/attachments';
-import type { TriggerDef } from '../components/composer';
-import type { ChatMessage } from './chat-types';
-import type { ProseSize } from '../primitives/chat-config';
-import type { ModelOption, ConversationGroup, ConversationSummary } from '../types';
+import {
+  WorkspaceShell,
+  type WorkspaceShellController,
+  type WorkspaceAsideSide,
+  type WorkspaceAsideToggleDetail,
+  type WorkspaceAsideResizeDetail,
+} from '../components/workspace-shell';
 
 interface Props extends Record<string, unknown> {
-  /** The sidebar's section headers, rendered in array order. A group carries no
-   *  conversations of its own; it is matched against `conversations` by id, so
-   *  the two props are complementary rather than alternatives. Omit for an
-   *  ungrouped sidebar. Set as a JS property. */
-  groups?: ConversationGroup[];
-  /** Every conversation in the sidebar, flat. Each one is filed under the group
-   *  whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId`
-   *  matching no entry in `groups`, falls into a trailing ungrouped section
-   *  (headerless when `compact`), so nothing you pass in is ever dropped. There is
-   *  no recency bucketing. Set as a JS property. Omit for an empty sidebar, or
-   *  when `no-conversations` replaces the built-in list with your own
-   *  `sidebar-header` content. */
-  conversations?: ConversationSummary[];
-  /** Id of the open conversation, highlighted in the sidebar. */
-  activeId?: string;
-  /** The active conversation's message thread, newest last. Set as a JS property
-   *  (`el.messages = [...]`); a NEW array reference per streaming chunk
-   *  re-renders (mutating in place does not). Omit for an empty thread. */
-  messages?: ChatMessage[];
-  value?: string;
-  placeholder?: string;
-  loading?: boolean;
-  suggestions?: string[];
-  suggestionMode?: 'submit' | 'fill';
-  proseSize?: ProseSize;
-  codeTheme?: string;
-  codeHighlight?: boolean;
-  chatTitle?: string;
-  models?: ModelOption[];
-  currentModel?: string;
-  context?: ChatThreadContextUsage;
-  scrollButton?: boolean;
-  search?: boolean;
-  voice?: boolean;
-  /** Rich entity triggers (`/` skills, `@` agents/plugins) forwarded to the input. */
-  triggers?: TriggerDef[];
-  /** Default icon per entity kind (kind → image src) forwarded to the input. */
-  kindIcons?: Record<string, string>;
-  /** Sidebar default width as a percent of the workspace (default 26). */
-  sidebarWidth?: number;
-  /** Sidebar min width in px (default 240). */
-  sidebarMinWidth?: number;
-  /** Sidebar max width in px (default 420). */
-  sidebarMaxWidth?: number;
-  /** Controlled collapsed state. Set this as a JS property (`el.sidebarCollapsed
-   *  = true`) to drive the sidebar from your app, updating it in response to the
-   *  `kai-sidebar-toggle` event. Omit for uncontrolled (the element manages it). */
-  sidebarCollapsed?: boolean;
-  /** Initial collapsed state when uncontrolled (default false). Use the
-   *  `default-sidebar-collapsed` attribute to start collapsed in plain HTML. */
-  defaultSidebarCollapsed?: boolean;
-  /** Auto-collapse the rail when the workspace's own width drops below this many
-   *  px, and re-expand when it grows back above. Uncontrolled only (it never
-   *  fights an app-driven `sidebarCollapsed`); omit to disable. Fires
-   *  `kai-sidebar-toggle`. Attribute: `collapse-below`. */
+  /** Controlled collapsed state of the start aside. Set this as a JS property
+   *  (`el.startCollapsed = true`) to drive the aside from your app, updating it
+   *  in response to the `kai-aside-toggle` event. Omit for uncontrolled (the
+   *  element manages it). */
+  startCollapsed?: boolean;
+  /** Initial collapsed state of the start aside when uncontrolled (default
+   *  false). Use the `default-start-collapsed` attribute to start collapsed in
+   *  plain HTML. */
+  defaultStartCollapsed?: boolean;
+  /** Controlled collapsed state of the end aside. Set this as a JS property
+   *  (`el.endCollapsed = true`) to drive the aside from your app, updating it
+   *  in response to the `kai-aside-toggle` event. Omit for uncontrolled (the
+   *  element manages it). */
+  endCollapsed?: boolean;
+  /** Initial collapsed state of the end aside when uncontrolled (default
+   *  false). Use the `default-end-collapsed` attribute to start collapsed in
+   *  plain HTML. */
+  defaultEndCollapsed?: boolean;
+  /** 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.
+   *  Fires `kai-aside-toggle`. Attribute: `collapse-below`. */
   collapseBelow?: number;
-  /** Render Recents as dense single-line rows (a leading dot + title, no count). */
+  /** 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. Attribute: `drawer-below`. */
+  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;
-  /** Suppress the built-in ConversationList so the `sidebar-header` slot owns the
-   *  whole rail flex region (for apps that supply their own rail nav). Default
-   *  false. Attribute: `no-conversations`. */
-  noConversations?: boolean;
-  /** Optional card type -> custom-element tag overrides/additions for `card`
-   *  parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a
-   *  plain string map (not the `CardTagMap` alias) so the generated React
-   *  wrapper inlines it instead of emitting an unresolved named type. */
-  cardTypes?: Record<string, string>;
-  /** JSON Schemas for the card types this app renders, keyed by envelope type. The
-   *  companion of `cardTypes`, which says what DRAWS a card while this says what a
-   *  VALID one looks like. An OBJECT, so it is a JS property only: `el.cardSchemas
-   *  = { 'pricing-table': pricingSchema }`, never an attribute.
-   *  `createCardRegistry(...).validationSchemas` is exactly this shape.
-   *
-   *  Without it the kit validates its own seven built-ins and leaves your own card
-   *  type, the one your app actually cares about, as the only unchecked thing on
-   *  screen. A schema here WINS over a built-in of the same name.
-   *
-   *  Typed `Record<string, object>` rather than `Record<string, JsonSchema>`
-   *  deliberately: an imported `.json` schema widens `"type"` to `string`, and an
-   *  authored one carries `$schema`/`title`/`description`/`additionalProperties`,
-   *  so the tighter type would reject both of the normal ways to supply one. */
-  cardSchemas?: Record<string, object>;
 }
 
+/** Events fired by `<kai-workspace>`. Layout only: every chat event now belongs
+ *  to the part that fires it, inside your own markup. */
 interface Events {
-  /** A conversation was selected in the sidebar. */
-  'kai-conversation-select': { id: string };
-  /** The "New chat" button was clicked. */
-  'kai-new-chat': Record<string, never>;
-  /** The sidebar was collapsed or expanded. */
-  'kai-sidebar-toggle': { collapsed: boolean };
-  /** User submitted a message. */
-  'kai-submit': { value: string; attachments: AttachmentData[] };
-  /** Fired on every input change. */
-  'kai-value-change': { value: string };
-  /** The header model switcher changed. */
-  'kai-model-change': { modelId: string };
-  /** An action button on a message was clicked. `state` is present only for the
-   *  toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when
-   *  re-tapped to clear. */
-  'kai-message-action': { messageId: string; action: string; state?: 'on' | 'off' };
-  /** The Search button was clicked. */
-  'kai-search': Record<string, never>;
-  /** The Mic / voice button was clicked. */
-  'kai-voice': Record<string, never>;
-  /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
-  'kai-suggestion-click': { value: string };
+  /** An aside collapsed or expanded (a method, the breakpoint, the drawer's Escape). */
+  'kai-aside-toggle': WorkspaceAsideToggleDetail;
+  /** The aside was resized (fires per drag step, keyboard nudge, or a handle double-click reset), width in px. */
+  'kai-aside-resize': WorkspaceAsideResizeDetail;
 }
 
+/**
+ * `<kai-workspace>` — the chat-agnostic layout shell: five slots (`header` ·
+ * `start` · `main` · `end` · `footer`), resize handles between the columns,
+ * per-aside 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 `<kai-conversations>`, and the workspace app slots `<kai-conversations>`
+ * and `<kai-chat>` into it.
+ *
+ * ```html
+ * <kai-workspace collapse-below="720" drawer-below="640">
+ *   <kai-conversations slot="start"></kai-conversations>
+ *   <kai-chat></kai-chat>
+ * </kai-workspace>
+ * ```
+ *
+ * Aside geometry is CSS custom properties, not props (the `kai-dock` rule):
+ * `--kai-workspace-start-width` (280px) · `--kai-workspace-start-min-width`
+ * (200px) · `--kai-workspace-start-max-width` (480px) · `--kai-workspace-end-width`
+ * (320px) · `--kai-workspace-end-min-width` (200px) · `--kai-workspace-end-max-width`
+ * (480px). Read once at upgrade. Parts: `header` · `start` · `main` · `end` ·
+ * `footer` (the asides also match `::part(aside)`).
+ *
+ * **BREAKING (0.24):** this element was a chat
+ * preset; it is now a layout shell, and everything chat-shaped is gone from its
+ * surface. Where each removed prop went:
+ *
+ * - `conversations` / `activeId` / `groups` / `noConversations`: set them on your
+ *   own `<kai-conversations slot="start">`.
+ * - `messages` / `loading` / `proseSize` / `codeTheme` / `codeHighlight` /
+ *   `chatTitle` / `scrollButton` / `cardTypes` / `cardSchemas`: set them on your
+ *   own `<kai-chat>` in the main region.
+ * - `value` / `placeholder` / `suggestions` / `suggestionMode` / `voice` /
+ *   `triggers` / `kindIcons` and the renamed `webSearch` (was `search`): the
+ *   composer surface on `<kai-chat>` or `<kai-prompt-input>`.
+ * - `models` / `currentModel` / `context`: header chrome you slot (a model
+ *   picker is a part in a slot, not three orchestrator props).
+ * - `sidebarWidth` / `sidebarMinWidth` / `sidebarMaxWidth`: the
+ *   `--kai-workspace-start-*` custom properties above.
+ * - `sidebarCollapsed` / `defaultSidebarCollapsed`: `startCollapsed` /
+ *   `defaultStartCollapsed` (per-aside; the end aside has its own pair).
+ * - `collapseBelow`: kept, now collapsing both asides.
+ * - `compact`: kept as a reflected density hint; the rail's row density is
+ *   `<kai-conversations>`' own `compact`.
+ * - Chat events (`kai-submit`, `kai-conversation-select`, `kai-message-action`,
+ *   `kai-model-change`, `kai-search`, `kai-voice`, `kai-value-change`,
+ *   `kai-suggestion-click`): listen on the part that fires them.
+ *   `kai-sidebar-toggle` is now `kai-aside-toggle` with a `side`.
+ * - Methods: `toggleSidebar()` / `collapseSidebar()` / `expandSidebar()` are now
+ *   `toggleAside(side)` / `collapseAside(side)` / `expandAside(side)`; the
+ *   thread methods (`focus`/`clear`/`send`/`scrollToBottom`) live on your
+ *   `<kai-chat>`.
+ *
+ * The migration path for a full app is the `workspace` block scaffold (the kai
+ * MCP `scaffold` tool), which emits this composition wired.
+ */
 defineWebComponent<Props, Events>('kai-workspace', {
-  groups: [], conversations: [], activeId: undefined, messages: [],
-  value: undefined, placeholder: 'Send a message...', loading: false,
-  suggestions: undefined, suggestionMode: 'submit', proseSize: 'sm',
-  codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,
-  models: undefined, currentModel: undefined, context: undefined, scrollButton: true,
-  search: false, voice: false, triggers: undefined, kindIcons: undefined,
-  sidebarWidth: 26, sidebarMinWidth: 240, sidebarMaxWidth: 420,
-  sidebarCollapsed: undefined, defaultSidebarCollapsed: undefined, collapseBelow: undefined, compact: undefined,
-  noConversations: undefined, cardTypes: undefined, cardSchemas: undefined,
-}, (props, { dispatch, flag, expose, element }) => {
-  // `messages` is an untyped boundary: a consumer can hand it anything at
-  // runtime (a pre-0.20.0 `{ id, role, content }` array, in particular). Skip
-  // the invalid entries rather than let `groupMessageParts` throw deep inside a
-  // render pass, which would blank the whole workspace instead of one message.
-  const validMessages = createMessagesGuard('kai-workspace');
-
-  // Which injection slots the consumer has filled. A bare <slot> is always a
-  // truthy JSX node, so we render each region wrapper ONLY when readSlots reports
-  // projected light-DOM content (re-read on childList mutation).
+  startCollapsed: undefined,
+  defaultStartCollapsed: undefined,
+  endCollapsed: undefined,
+  defaultEndCollapsed: undefined,
+  collapseBelow: undefined,
+  drawerBelow: undefined,
+  compact: undefined,
+}, (props, { dispatch, flag, expose, element, reflectFlag }) => {
+  // Which slots the consumer has filled. A bare <slot> is always a truthy JSX
+  // node, so each optional region renders ONLY when readSlots reports projected
+  // light-DOM content (re-read on childList mutation). Main always renders.
   const [slots, setSlots] = createSignal<Record<string, boolean>>({});
   onMount(() => {
     const read = () => setSlots(readSlots(element, WORKSPACE_SLOTS));
@@ -152,165 +129,60 @@ defineWebComponent<Props, Events>('kai-workspace', {
     onCleanup(() => observer.disconnect());
   });
 
-  // Controlled/uncontrolled collapse: `sidebarCollapsed` (when set) wins;
-  // otherwise the element manages its own state, seeded from
-  // `defaultSidebarCollapsed`. `setCollapsedTo` always writes the internal value (a
-  // no-op visually while controlled) and emits `kai-sidebar-toggle` so a controlling
-  // app can update its own state.
-  const [collapsed, setCollapsed] = createControllableSignal(
-    () => props.sidebarCollapsed as boolean | undefined,
-    flag('defaultSidebarCollapsed'),
-  );
-  const setCollapsedTo = (next: boolean) => { setCollapsed(next); dispatch('kai-sidebar-toggle', { collapsed: next }); };
-  const toggle = () => setCollapsedTo(!collapsed());
+  // Reflect the read-back flags (the G-05 rule: a bare attribute parses to
+  // `undefined`, so without this the property would contradict the attribute).
+  reflectFlag('compact');
+  reflectFlag('defaultStartCollapsed');
+  reflectFlag('defaultEndCollapsed');
 
-  // Responsive auto-collapse. When `collapseBelow` is set, a ResizeObserver on the
-  // workspace root collapses the rail once the workspace's own width drops below
-  // it and re-expands above it. Uncontrolled only — bail while `sidebarCollapsed`
-  // is set so we never fight an app-driven collapse. `autoCollapsed` tracks whether
-  // WE collapsed it, so a user's manual expand isn't auto-undone on the next tick.
-  let rootEl!: HTMLDivElement;
-  let autoCollapsed = false;
-  onMount(() => {
-    if (typeof ResizeObserver === 'undefined') return;
-    const ro = new ResizeObserver((entries) => {
-      const below = props.collapseBelow as number | undefined;
-      if (below == null || props.sidebarCollapsed !== undefined) return;
-      const width = entries[0]?.contentRect.width ?? rootEl.clientWidth;
-      const isBelow = width < below;
-      if (isBelow && !collapsed()) {
-        autoCollapsed = true;
-        setCollapsedTo(true);
-      } else if (!isBelow && collapsed() && autoCollapsed) {
-        autoCollapsed = false;
-        setCollapsedTo(false);
-      }
-    });
-    ro.observe(rootEl);
-    onCleanup(() => ro.disconnect());
-  });
+  // Aside geometry from the element's CSS custom properties, read once at
+  // upgrade (inline style first so jsdom, which does not resolve custom
+  // properties through getComputedStyle, still honors a direct set).
+  const readVar = (name: string, fallback: number): number => {
+    const inline = element.style.getPropertyValue(name).trim();
+    const computed = inline || getComputedStyle(element).getPropertyValue(name).trim();
+    const n = parseFloat(computed);
+    return Number.isFinite(n) ? n : fallback;
+  };
+  const geometry = untrack(() => ({
+    startWidth: readVar('--kai-workspace-start-width', 280),
+    startMinWidth: readVar('--kai-workspace-start-min-width', 200),
+    startMaxWidth: readVar('--kai-workspace-start-max-width', 480),
+    endWidth: readVar('--kai-workspace-end-width', 320),
+    endMinWidth: readVar('--kai-workspace-end-min-width', 200),
+    endMaxWidth: readVar('--kai-workspace-end-max-width', 480),
+  }));
 
-  // Imperative method API. The sidebar methods drive the same collapse path as the
-  // in-UI toggle (named *Sidebar to avoid the `sidebarCollapsed` prop accessor).
-  // The thread methods delegate to the embedded ChatThread's controller, captured
-  // once below — the thread node is shared across both <Show> branches, so a single
-  // controllerRef is stable across collapse/expand.
-  let controller: ChatThreadController | undefined;
+  let controller: WorkspaceShellController | undefined;
   expose({
-    /** Collapse/expand the conversation sidebar and fire `kai-sidebar-toggle`. */
-    toggleSidebar: () => toggle(),
-    /** Force the conversation sidebar collapsed (fires `kai-sidebar-toggle`). */
-    collapseSidebar: () => setCollapsedTo(true),
-    /** Force the conversation sidebar expanded (fires `kai-sidebar-toggle`). */
-    expandSidebar: () => setCollapsedTo(false),
-    /** Focus the thread's composer. */
-    focus: (options?: FocusOptions) => controller?.focus(options),
-    /** Clear the thread draft + staged attachments. */
-    clear: () => controller?.clear(),
-    /** Submit the current thread draft programmatically (fires `kai-submit`). */
-    send: () => controller?.send(),
-    /** Scroll the thread to the newest message. */
-    scrollToBottom: (behavior?: ScrollBehavior) => controller?.scrollToBottom(behavior),
+    /** Collapse/expand one aside (fires `kai-aside-toggle`). */
+    toggleAside: (side: WorkspaceAsideSide) => controller?.toggleAside(side),
+    /** Force one aside collapsed (fires `kai-aside-toggle`). */
+    collapseAside: (side: WorkspaceAsideSide) => controller?.collapseAside(side),
+    /** Force one aside expanded (fires `kai-aside-toggle`). */
+    expandAside: (side: WorkspaceAsideSide) => controller?.expandAside(side),
   });
 
-  // Create the thread ONCE and reference the same node in both <Show> branches.
-  // It's owned by this component root (not by a Show branch), so toggling the
-  // sidebar moves the node between branches without disposing it — the thread's
-  // own state (e.g. an uncontrolled draft) survives the collapse/expand.
-  const threadEl = (
-    <ChatThread
-      messages={validMessages(props.messages)} value={props.value as string | undefined} placeholder={props.placeholder as string}
-      loading={flag('loading')} suggestions={props.suggestions as string[] | undefined}
-      suggestionMode={props.suggestionMode as 'submit' | 'fill'} proseSize={props.proseSize as ProseSize}
-      codeTheme={props.codeTheme as string} codeHighlight={flag('codeHighlight')}
-      chatTitle={props.chatTitle as string | undefined} models={props.models as ModelOption[] | undefined}
-      currentModel={props.currentModel as string | undefined} context={props.context as ChatThreadContextUsage | undefined}
-      scrollButton={props.scrollButton !== false} search={flag('search')} voice={flag('voice')}
-      triggers={props.triggers as TriggerDef[] | undefined}
-      kindIcons={props.kindIcons as Record<string, string> | undefined}
-      cardTypes={cardComponentsFromTags(props.cardTypes as Record<string, string> | undefined, (props as { theme?: string }).theme)}
-      cardSchemas={props.cardSchemas as Record<string, object> | undefined}
-      onValueChange={(value) => dispatch('kai-value-change', { value })}
-      onSubmit={(detail) => dispatch('kai-submit', detail)}
-      onSuggestionClick={(value) => dispatch('kai-suggestion-click', { value })}
-      onModelChange={(modelId) => dispatch('kai-model-change', { modelId })}
-      onMessageAction={(detail) => dispatch('kai-message-action', detail)}
-      onSearch={() => dispatch('kai-search', {})}
-      onVoice={() => dispatch('kai-voice', {})}
-      controllerRef={(c) => (controller = c)}
-    />
-  );
-
-  // The main region: an optional top-placed `main-header` band above the thread.
-  // Shared across both collapse branches (the thread node is the same instance).
-  const mainRegion = (
-    <div class="flex h-full flex-col overflow-hidden">
-      <Show when={slots()['main-header']}>
-        <div class="shrink-0 border-b border-border"><slot name="main-header" /></div>
-      </Show>
-      <div class="min-h-0 flex-1">
-        <Show when={slots()['main']} fallback={threadEl}>
-          <slot name="main" />
-        </Show>
-      </div>
-    </div>
-  );
-
   return (
-    <div ref={rootEl} class="h-full w-full overflow-hidden bg-background">
-      <Show
-        when={!collapsed()}
-        fallback={
-          <div class="flex h-full">
-            {/* Collapsed: the reopen control lives in its OWN thin rail column
-                (matching the sidebar's bg-surface) rather than floating over the
-                content. The previous `absolute` overlay sat on top of a
-                `main-header`'s leading title — see the t3code/codex/chatgpt apps,
-                all of which fill that slot — so it both overlapped the header and
-                competed with any in-header toggle. A dedicated column never
-                overlaps and reads as a collapsed sidebar. */}
-            <div class="flex w-11 shrink-0 flex-col items-center border-r border-border bg-surface pt-2.5">
-              <CollapsedRail onExpand={toggle} class="bg-transparent shadow-none backdrop-blur-none" />
-            </div>
-            <div class="min-w-0 flex-1">{mainRegion}</div>
-          </div>
-        }
-      >
-        <ResizablePanelGroup orientation="horizontal">
-          <ResizablePanel defaultSize={props.sidebarWidth as number} data-min-size={String(props.sidebarMinWidth)} data-max-size={String(props.sidebarMaxWidth)}>
-            {/* The rail: an optional injected header above the list and footer
-                below it (upgrade card / Design trigger / user menu). Carries a
-                subtle, theme-aware default background (bg-surface), exposed as
-                ::part(sidebar) so a consumer can override it. The inner list is
-                made transparent so the part background reads uniformly. */}
-            <div part="sidebar" class="flex h-full flex-col overflow-hidden bg-surface">
-              <Show when={slots()['sidebar-header']}>
-                {/* When `no-conversations` suppresses the built-in list, the
-                    projected header owns the whole rail flex region; otherwise it
-                    sits as a fixed band above the list. */}
-                <div class={flag('noConversations') ? 'min-h-0 flex-1' : 'shrink-0'}><slot name="sidebar-header" /></div>
-              </Show>
-              <Show when={!flag('noConversations')}>
-                <div class="min-h-0 flex-1">
-                  <ConversationList
-                    class="bg-transparent"
-                    groups={props.groups ?? []} conversations={props.conversations ?? []} activeId={props.activeId as string | undefined}
-                    compact={flag('compact')}
-                    onSelect={(id) => dispatch('kai-conversation-select', { id })}
-                    onNewChat={() => dispatch('kai-new-chat', {})}
-                    onToggleSidebar={toggle}
-                  />
-                </div>
-              </Show>
-              <Show when={slots()['sidebar-footer']}>
-                <div class="shrink-0"><slot name="sidebar-footer" /></div>
-              </Show>
-            </div>
-          </ResizablePanel>
-          <ResizableHandle />
-          <ResizablePanel>{mainRegion}</ResizablePanel>
-        </ResizablePanelGroup>
-      </Show>
-    </div>
+    <WorkspaceShell
+      header={slots()['header'] ? <slot name="header" /> : undefined}
+      start={slots()['start'] ? <slot name="start" /> : undefined}
+      end={slots()['end'] ? <slot name="end" /> : undefined}
+      footer={slots()['footer'] ? <slot name="footer" /> : undefined}
+      startCollapsed={props.startCollapsed as boolean | undefined}
+      defaultStartCollapsed={flag('defaultStartCollapsed')}
+      endCollapsed={props.endCollapsed as boolean | undefined}
+      defaultEndCollapsed={flag('defaultEndCollapsed')}
+      collapseBelow={props.collapseBelow as number | undefined}
+      drawerBelow={props.drawerBelow as number | undefined}
+      compact={flag('compact')}
+      {...geometry}
+      onAsideToggle={(detail) => dispatch('kai-aside-toggle', detail)}
+      onAsideResize={(detail) => dispatch('kai-aside-resize', detail)}
+      controllerRef={(c) => (controller = c)}
+    >
+      <slot name="main" />
+      <slot />
+    </WorkspaceShell>
   );
 });

package/src/elements/chat.tsx

@@ -1,4 +1,4 @@
-import { createEffect, createSignal, onCleanup, onMount } from 'solid-js';
+import { createSignal, onCleanup, onMount } from 'solid-js';
 import { defineWebComponent } from './define';
 import { CHAT_SLOTS, readSlots } from './slots';
 import { ChatThread, type ChatThreadProps, type ChatThreadContextUsage, type ChatThreadController } from '../components/chat-thread';
@@ -14,8 +14,20 @@ import type { ModelOption } from '../types';
 
 type Props = Omit<ChatThreadProps,
   'class' | 'onValueChange' | 'onSubmit' | 'onAttachmentsChange' | 'onSuggestionClick' | 'onModelChange'
-  | 'onMessageAction' | 'onSearch' | 'onVoice' | 'controllerRef' | 'cardTypes' | 'cardSchemas' | 'messages'
-  | 'accept' | 'onAttachmentsRejected'> & Record<string, unknown> & {
+  | 'onMessageAction' | 'onWebSearch' | 'onVoice' | 'controllerRef' | 'cardTypes' | 'cardSchemas' | 'cardHostElement' | 'messages'
+  | 'accept' | 'onAttachmentsRejected'
+  // `headerEndContent`/`emptyContent` are JSX.Element escape hatches for a caller
+  // composing `ChatThread` directly as a Solid component (see their doc comments in
+  // chat-thread.tsx — the construct-engine's emitted App is the motivating case).
+  // `<kai-chat>` is the OPPOSITE shape: a custom element crossing the shadow-DOM
+  // boundary, where a `JSX.Element` value cannot exist for a consumer to construct
+  // (React/Vue/plain HTML have no such type) and the facade already has its own
+  // working mechanism for both regions — `slot="header-end"` and `slot="empty"`.
+  // Omitted here rather than left to flow through `Omit`'s default pass-through:
+  // without this, `gen-element-api.mjs` picked them up and put a JSX.Element type
+  // (which it stringifies as Solid's internal array-like union — meaningless to a
+  // web-component consumer) into `<kai-chat>`'s public prop surface and docs.
+  | 'headerEndContent' | 'emptyContent'> & Record<string, unknown> & {
     /** Which attachment media types the user may stage, in HTML `accept` syntax:
      *  `<kai-chat accept="image/*,application/pdf">`. A plain string, so unlike
      *  `messages` it DOES work as an attribute. Omitted means no filter.
@@ -86,8 +98,8 @@ interface Events {
   'kai-message-action': { messageId: string; action: string; state?: 'on' | 'off' };
   /** The header model switcher changed. */
   'kai-model-change': { modelId: string };
-  /** The Search button was clicked. */
-  'kai-search': Record<string, never>;
+  /** The web-search (Globe) toolbar button was clicked. */
+  'kai-web-search': Record<string, never>;
   /** The Mic / voice button was clicked. */
   'kai-voice': Record<string, never>;
 }
@@ -97,9 +109,10 @@ defineWebComponent<Props, Events>('kai-chat', {
   suggestions: undefined, suggestionMode: 'submit', persistSuggestions: false, proseSize: 'sm',
   codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,
   models: undefined, currentModel: undefined, context: undefined, scrollButton: true,
-  search: false, voice: false, triggers: undefined, kindIcons: undefined,
+  attach: true, webSearch: false, voice: false, triggers: undefined, kindIcons: undefined,
   actionsReveal: 'always', cardTypes: undefined, cardSchemas: undefined, accept: undefined,
-}, (props, { dispatch, flag, element, expose }) => {
+  reasoning: undefined, reasoningOpen: undefined,
+}, (props, { dispatch, flag, reflectFlag, element, expose }) => {
   // `messages` is an untyped boundary: a consumer can hand it anything at
   // runtime (a pre-0.20.0 `{ id, role, content }` array, in particular). Skip
   // the invalid entries rather than let `groupMessageParts` throw deep inside a
@@ -120,7 +133,10 @@ defineWebComponent<Props, Events>('kai-chat', {
 
   // Reflect streaming state to a host attribute so slotted composer/notice CSS
   // can react without reading internals (e.g. :host([loading]) ::slotted(...)).
-  createEffect(() => { element.toggleAttribute('loading', flag('loading')); });
+  // reflectFlag, not a hand-rolled toggleAttribute effect: the reflection is what
+  // makes the property read back `undefined`, so the two belong in one call. See
+  // WebComponentContext.reflectFlag.
+  reflectFlag('loading');
 
   // Imperative method API — forward the chat-thread controller onto the host
   // (focus the composer, clear it, send programmatically, scroll the thread).
@@ -161,12 +177,17 @@ defineWebComponent<Props, Events>('kai-chat', {
     codeTheme={props.codeTheme as string} codeHighlight={flag('codeHighlight')}
     chatTitle={props.chatTitle as string | undefined} models={props.models as ModelOption[] | undefined}
     currentModel={props.currentModel as string | undefined} context={props.context as ChatThreadContextUsage | undefined}
-    scrollButton={props.scrollButton !== false} search={flag('search')} voice={flag('voice')}
+    scrollButton={props.scrollButton !== false} attach={flag('attach')} webSearch={flag('webSearch')} voice={flag('voice')}
+    reasoning={props.reasoning as 'full' | 'compact' | 'off' | undefined}
+    reasoningOpen={flag('reasoningOpen')}
     triggers={props.triggers as TriggerDef[] | undefined}
     kindIcons={props.kindIcons as Record<string, string> | undefined}
     actionsReveal={props.actionsReveal as 'always' | 'hover'}
     cardTypes={cardComponentsFromTags(props.cardTypes as Record<string, string> | undefined, (props as { theme?: string }).theme)}
     cardSchemas={props.cardSchemas as Record<string, object> | undefined}
+    /* F-26: card parts emit off THIS element as the bubbling `kai-card` event,
+       so `listenForCardEvents(el)` / addEventListener('kai-card') work. */
+    cardHostElement={element}
     onValueChange={(value) => dispatch('kai-value-change', { value })}
     onSubmit={(detail) => dispatch('kai-submit', detail)}
     accept={props.accept as string | undefined}
@@ -175,7 +196,7 @@ defineWebComponent<Props, Events>('kai-chat', {
     onSuggestionClick={(value) => dispatch('kai-suggestion-click', { value })}
     onModelChange={(modelId) => dispatch('kai-model-change', { modelId })}
     onMessageAction={(detail) => dispatch('kai-message-action', detail)}
-    onSearch={() => dispatch('kai-search', {})}
+    onWebSearch={() => dispatch('kai-web-search', {})}
     onVoice={() => dispatch('kai-voice', {})}
     controllerRef={(c) => (controller = c)}
     headerStart={slot('header-start')}