@kitn.ai/ui 0.14.1

package/src/elements/remote.tsx

@@ -0,0 +1,221 @@
+// src/elements/remote.tsx
+// <kai-remote> — Shadow-DOM facade that mounts a sandboxed cross-origin iframe
+// card via mountRemoteCard(), re-emits every CardEvent as a bubbling+composed
+// kai-card CustomEvent, and validates the provider-origin before mounting.
+import { createEffect, createSignal, onCleanup, onMount } from 'solid-js';
+import { defineWebComponent } from './define';
+import { mountRemoteCard } from '../remote/host-embed';
+import type { RemoteCardHandle } from '../remote/host-embed';
+import type { CardEnvelope, CardContext, CardPolicy, CardEvent } from '../primitives/card-contract';
+import { emitCardEvent } from '../primitives/card-routing';
+
+interface Props extends Record<string, unknown> {
+  /** The remote card URL. Attribute: `src`. */
+  src?: string;
+  /** Exact provider origin (https: or http://localhost for dev). Attribute: `provider-origin`. */
+  providerOrigin?: string;
+  /** The card envelope to render. JS property only. */
+  envelope?: Record<string, unknown>;
+  /** Optional routing policy. JS property only. */
+  policy?: Record<string, unknown>;
+}
+
+/**
+ * Validate that `origin` is a single absolute origin that is either:
+ *   - an https: origin (e.g. "https://provider.example")
+ *   - http://localhost or http://127.0.0.1 (local dev only)
+ *
+ * Rejects "*", comma-lists, bare paths, and any other http: origin.
+ */
+function isValidProviderOrigin(origin: string | undefined): boolean {
+  if (!origin) return false;
+  // Reject wildcard and comma-lists immediately.
+  if (origin === '*' || origin.includes(',')) return false;
+  let parsed: URL;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    return false;
+  }
+  // Must be an exact origin: no pathname beyond '/', no search, no hash.
+  if (parsed.pathname !== '/' || parsed.search !== '' || parsed.hash !== '') return false;
+  if (parsed.protocol === 'https:') return true;
+  if (parsed.protocol === 'http:') {
+    return parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1';
+  }
+  return false;
+}
+
+/**
+ * Build a CardPolicy that re-emits each routed CardEvent as a bubbling+composed
+ * `kai-card` CustomEvent on `element`, AND delegates to the caller-supplied `policy`.
+ */
+function buildWrappedPolicy(element: HTMLElement, userPolicy: CardPolicy | undefined): CardPolicy {
+  function emit(ev: CardEvent): void {
+    emitCardEvent(element, ev);
+  }
+  return {
+    onSubmit(cardId, data) {
+      emit({ kind: 'submit', cardId, data });
+      userPolicy?.onSubmit?.(cardId, data);
+    },
+    onAction(cardId, action, payload) {
+      emit({ kind: 'action', cardId, action, payload });
+      userPolicy?.onAction?.(cardId, action, payload);
+    },
+    onSendPrompt(text, opts) {
+      // send-prompt doesn't carry cardId in the policy signature; we use a placeholder.
+      emit({ kind: 'send-prompt', cardId: '', text, mode: opts.mode, context: opts.context });
+      userPolicy?.onSendPrompt?.(text, opts);
+    },
+    onOpen(url, target) {
+      // open doesn't carry cardId in the policy signature.
+      emit({ kind: 'open', cardId: '', url, target });
+      userPolicy?.onOpen?.(url, target);
+    },
+    onState(cardId, patch) {
+      emit({ kind: 'state', cardId, patch });
+      userPolicy?.onState?.(cardId, patch);
+    },
+    onDismiss(cardId) {
+      emit({ kind: 'dismiss', cardId });
+      userPolicy?.onDismiss?.(cardId);
+    },
+    onError(cardId, message) {
+      emit({ kind: 'error', cardId, message });
+      userPolicy?.onError?.(cardId, message);
+    },
+    maxSendPromptMode: userPolicy?.maxSendPromptMode,
+  };
+}
+
+/**
+ * `<kai-remote>` — mounts a sandboxed cross-origin iframe card.
+ *
+ * Required props:
+ *   - `provider-origin` attribute: the exact HTTPS origin of the card provider
+ *     (or http://localhost for local dev).
+ *   - `src` attribute: the URL of the card page (must share the provider origin).
+ *   - `envelope` JS property: the CardEnvelope to render.
+ *
+ * Optional:
+ *   - `policy` JS property: a CardPolicy for routing card events.
+ *   - `theme` attribute (inherited from defineWebComponent): 'light' | 'dark' | 'auto'.
+ *
+ * Every routed CardEvent is also dispatched as a bubbling+composed `kai-card`
+ * CustomEvent off the host element.
+ */
+defineWebComponent<Props>(
+  'kai-remote',
+  {
+    src: undefined,
+    providerOrigin: undefined,
+    envelope: undefined,
+    policy: undefined,
+  },
+  (props, { element }) => {
+    // Lifted out of onMount so the theme effect (below) can re-push context to the
+    // live bridge after mount. `undefined` until the iframe is successfully mounted.
+    let handle: RemoteCardHandle | undefined;
+
+    // Resolve dark mode the SAME way native elements do (see createDarkMode in
+    // define.tsx): the `theme` prop is 'light' | 'dark' | 'auto' (default 'auto',
+    // which follows the OS `prefers-color-scheme`). Tracked reactively so a host /
+    // Storybook theme toggle flows through the effect below.
+    const [systemDark, setSystemDark] = createSignal(false);
+    if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+      const mq = window.matchMedia('(prefers-color-scheme: dark)');
+      setSystemDark(mq.matches);
+      const onChange = (e: MediaQueryListEvent) => setSystemDark(e.matches);
+      mq.addEventListener('change', onChange);
+      onCleanup(() => mq.removeEventListener('change', onChange));
+    }
+    const isDark = () => {
+      const theme = (props.theme as string | undefined) ?? 'auto';
+      return theme === 'dark' || (theme === 'auto' && systemDark());
+    };
+
+    onMount(() => {
+      const shadow = element.shadowRoot;
+      if (!shadow) return;
+
+      function renderError(message: string): void {
+        const alert = document.createElement('div');
+        alert.setAttribute('role', 'alert');
+        alert.textContent = message;
+        shadow!.appendChild(alert);
+      }
+
+      // Validate provider-origin before attempting any mount.
+      const providerOrigin = props.providerOrigin;
+      if (!isValidProviderOrigin(providerOrigin)) {
+        renderError(
+          `[kai-remote] Invalid provider-origin "${providerOrigin ?? ''}". ` +
+          `Must be an absolute https: origin, or http://localhost / http://127.0.0.1 for local dev.`,
+        );
+        return;
+      }
+
+      const src = props.src;
+      if (!src) {
+        renderError('[kai-remote] Missing required "src" attribute.');
+        return;
+      }
+
+      const envelope = props.envelope as CardEnvelope | undefined;
+      if (!envelope) {
+        renderError('[kai-remote] Missing required "envelope" property.');
+        return;
+      }
+
+      // Derive a minimal CardContext. Theme resolved the same way native elements
+      // do (isDark(), above); read untracked here so this initial mount doesn't
+      // re-run on theme change — the createEffect below pushes later changes.
+      const context: CardContext = {
+        theme: { mode: isDark() ? 'dark' : 'light' },
+        locale: (typeof navigator !== 'undefined' && navigator.language) || 'en',
+      };
+
+      const userPolicy = props.policy as CardPolicy | undefined;
+      const wrappedPolicy = buildWrappedPolicy(element, userPolicy);
+
+      // Create a container inside the shadow root for mountRemoteCard.
+      const container = document.createElement('div');
+      shadow.appendChild(container);
+
+      try {
+        handle = mountRemoteCard({
+          container,
+          providerOrigin: providerOrigin as string,
+          src,
+          envelope,
+          context,
+          policy: wrappedPolicy,
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        renderError(`[kai-remote] Mount failed: ${message}`);
+        container.remove();
+        return;
+      }
+
+      onCleanup(() => {
+        handle?.destroy();
+        handle = undefined;
+      });
+    });
+
+    // React to later host/Storybook theme toggles: re-push a fresh resolved theme
+    // to the live bridge so the framed card re-themes (consistent with native
+    // elements). No-op until the iframe has mounted (handle is set). The bridge
+    // does a dispose+remount on a genuine theme change — see provider-runtime.ts;
+    // token/locale refreshes stay silent.
+    createEffect(() => {
+      const mode = isDark() ? 'dark' : 'light';
+      handle?.updateContext({ theme: { mode } });
+    });
+
+    // This element renders purely into the shadow root via onMount — no JSX return needed.
+    return <></>;
+  },
+);

package/src/elements/resizable.d.ts

@@ -0,0 +1,27 @@
+// src/elements/resizable.d.ts
+// Hand-authored ambient types for <kai-resizable>'s maximize capability. The
+// generated element-types.d.ts emits prop/event interfaces only (not methods),
+// so the imperative host API + the cross-element protocol events live here.
+// NOT regenerated by `npm run build`.
+import type { KaiMaximizeIntentDetail, KaiMaximizeStateDetail } from './resizable';
+
+declare global {
+  interface KaiResizableElement extends HTMLElement {
+    /** Which item index is maximized (null = none). Setting it maximizes that
+     *  item (or restores when set to null) — the declarative source of truth. */
+    maximizedIndex: number | null;
+    /** Imperatively maximize the item at `index` (thin wrapper over maximizedIndex). */
+    maximize(index: number): void;
+    /** Imperatively restore from the maximized layout. */
+    restore(): void;
+  }
+  interface HTMLElementTagNameMap {
+    'kai-resizable': KaiResizableElement;
+  }
+  interface HTMLElementEventMap {
+    'kai-maximize-intent': CustomEvent<KaiMaximizeIntentDetail>;
+    'kai-maximize-state': CustomEvent<KaiMaximizeStateDetail>;
+  }
+}
+
+export {};

package/src/elements/resizable.stories.tsx

@@ -0,0 +1,426 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, type JSX } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import { Resizable, ResizablePanel } from '../ui/resizable';
+import type { ArtifactFile } from '../components/artifact';
+import { Artifact } from '../components/artifact';
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-resizable': JSX.HTMLAttributes<HTMLElement> & { orientation?: string };
+      'kai-resizable-item': JSX.HTMLAttributes<HTMLElement> & {
+        size?: string; min?: string; max?: string; locked?: boolean | string; hidden?: boolean | string;
+      };
+      // `kai-artifact` JSX type is augmented (with the full attr set) in
+      // artifact.stories.tsx — declaring it again here with a different shape
+      // would trip TS2717 (module-augmentation merges must match). Reuse that one.
+    }
+  }
+}
+
+// Fixture base URL (served by Storybook staticDirs from examples/artifact-fixtures).
+const BASE = new URL('artifact-fixtures', document.baseURI).href;
+
+const ARTIFACT_FILES: ArtifactFile[] = [
+  { path: 'index.html', url: `${BASE}/index.html`, type: 'html', language: 'html',
+    code: `<!DOCTYPE html><html lang="en"><head><title>Preview</title></head><body><h1>Starboard</h1></body></html>` },
+  { path: 'about.html', url: `${BASE}/about.html`, type: 'html', language: 'html',
+    code: `<!DOCTYPE html><html lang="en"><head><title>About</title></head><body><h1>About</h1></body></html>` },
+];
+
+/** A labelled placeholder pane so the layout is visible in stories. */
+function Pane(props: { label: string; tone?: 'muted' | 'plain' }) {
+  return (
+    <div
+      style={{
+        height: '100%',
+        display: 'flex',
+        'align-items': 'center',
+        'justify-content': 'center',
+        padding: '16px',
+        background: props.tone === 'plain' ? 'transparent' : 'var(--color-muted, #f4f4f5)',
+        color: 'var(--color-muted-foreground, #71717a)',
+        'font-size': '13px',
+      }}
+    >
+      {props.label}
+    </div>
+  );
+}
+
+/** A bordered, sized frame the group fills. */
+function Frame(props: { children: JSX.Element; tall?: boolean }) {
+  return (
+    <div
+      style={{
+        height: props.tall ? '384px' : '256px',
+        width: '100%',
+        'max-width': '768px',
+        border: '1px solid var(--color-border, #e4e4e7)',
+        'border-radius': '8px',
+        overflow: 'hidden',
+      }}
+    >
+      {props.children}
+    </div>
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-resizable orientation="horizontal" style="display:block;height:400px">
+  <kai-resizable-item size="25%" min="160px"> ...list... </kai-resizable-item>
+  <kai-resizable-item> ...chat... </kai-resizable-item>
+  <kai-resizable-item size="30%"> ...preview... </kai-resizable-item>
+</kai-resizable>
+
+<script type="module">
+  import '@kitn.ai/ui/elements'; // registers the custom elements
+  document.querySelector('kai-resizable')
+    .addEventListener('kai-change', (e) => console.log(e.detail.sizes));
+</script>`;
+
+const meta = {
+  title: 'Components/Resizable',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-resizable'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kai-resizable', [
+        '`<kai-resizable>` is the framework-agnostic **web component** for a composable, resizable multi-panel layout (up to **3** `<kai-resizable-item>` panels) with **auto-inserted draggable dividers** — isolated in **Shadow DOM**.',
+        '**When to use:** to compose an app shell out of slotted regions without hand-wiring panels and handles — e.g. `list | chat | preview`. In SolidJS, use the `Resizable` convenience (UI/Resizable) directly.',
+        "**How to use:** register once with `import '@kitn.ai/ui/elements'`, set `orientation` (`horizontal` row / `vertical` column), and put a `<kai-resizable-item>` per panel. Each item carries `size` (px or %, e.g. `\"280px\"` or `\"25%\"`), `min`/`max`, `locked` (fixed size + non-draggable neighbour), and `hidden` (drops the panel + its divider). Listen for the **`change`** event (`detail.sizes`, percent).",
+        '**Anatomy:** one or more **`<kai-resizable-item>`** light children (each a config-carrier: `size`, `min`, `max`, `locked`, `hidden` attributes; renders its slotted content) with auto-inserted **draggable divider handles** between each visible, unlocked pair. A panel is omitted from layout when `hidden`; its adjacent divider is dropped. Nesting `<kai-resizable>` inside an item allows more than 3 panels.',
+        '**Placement:** the layout spine for compose-your-own-chat shells — sidebar + conversation, conversation + inspector, or a three-up list/chat/preview.',
+        'See the **Code** tab for HTML usage.',
+      ]),
+    },
+  },
+  args: { orientation: 'horizontal' },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Interactive playground — flip orientation, then drag the dividers. */
+export const Playground: Story = {
+  render: (args: { orientation?: string }) => (
+    <Frame>
+      <kai-resizable orientation={args.orientation ?? 'horizontal'}>
+        <kai-resizable-item size="25%" min="120px"><Pane label="List" /></kai-resizable-item>
+        <kai-resizable-item><Pane label="Chat" tone="plain" /></kai-resizable-item>
+      </kai-resizable>
+    </Frame>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Two panels: a sized list beside a flexible chat. */
+export const ListChat: Story = {
+  name: 'Sidebar + chat',
+  render: () => (
+    <Frame>
+      <kai-resizable orientation="horizontal">
+        <kai-resizable-item size="28%" min="140px" max="50%"><Pane label="List" /></kai-resizable-item>
+        <kai-resizable-item><Pane label="Chat" tone="plain" /></kai-resizable-item>
+      </kai-resizable>
+    </Frame>
+  ),
+};
+
+/** Three panels, two draggable dividers. */
+export const ListChatPreview: Story = {
+  name: 'List + chat + preview',
+  render: () => (
+    <Frame>
+      <kai-resizable orientation="horizontal">
+        <kai-resizable-item size="22%" min="120px"><Pane label="List" /></kai-resizable-item>
+        <kai-resizable-item><Pane label="Chat" tone="plain" /></kai-resizable-item>
+        <kai-resizable-item size="30%" min="160px"><Pane label="Preview" /></kai-resizable-item>
+      </kai-resizable>
+    </Frame>
+  ),
+};
+
+/** A locked, fixed-px sidebar — its divider is a static (non-draggable) separator. */
+export const LockedSidebar: Story = {
+  name: 'Locked sidebar',
+  render: () => (
+    <Frame>
+      <kai-resizable orientation="horizontal">
+        <kai-resizable-item size="240px" locked><Pane label="Locked sidebar (240px)" /></kai-resizable-item>
+        <kai-resizable-item><Pane label="Chat" tone="plain" /></kai-resizable-item>
+      </kai-resizable>
+    </Frame>
+  ),
+};
+
+/** Stacked top/bottom split. */
+export const Vertical: Story = {
+  name: 'Vertical split',
+  render: () => (
+    <Frame tall>
+      <kai-resizable orientation="vertical">
+        <kai-resizable-item size="40%" min="80px"><Pane label="Top" /></kai-resizable-item>
+        <kai-resizable-item><Pane label="Bottom" tone="plain" /></kai-resizable-item>
+      </kai-resizable>
+    </Frame>
+  ),
+};
+
+/** Toggle the preview panel — its divider drops and the rest reflow. */
+export const HiddenToggle: Story = {
+  name: 'Show / hide a panel',
+  render: () => {
+    const [showPreview, setShowPreview] = createSignal(true);
+    let previewItem: HTMLElement | undefined;
+    const toggle = () => {
+      setShowPreview((v) => !v);
+      // Drive the boolean attribute directly so the group's MutationObserver
+      // re-lays out (Solid sets the `hidden` IDL property, which doesn't reflect
+      // to the attribute on a custom element).
+      if (previewItem) {
+        if (showPreview()) previewItem.removeAttribute('hidden');
+        else previewItem.setAttribute('hidden', '');
+      }
+    };
+    return (
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+        <button
+          type="button"
+          onClick={toggle}
+          style={{
+            'align-self': 'flex-start',
+            padding: '4px 12px',
+            'font-size': '13px',
+            border: '1px solid var(--color-border, #e4e4e7)',
+            'border-radius': '6px',
+            cursor: 'pointer',
+          }}
+        >
+          {showPreview() ? 'Hide preview' : 'Show preview'}
+        </button>
+        <Frame>
+          <kai-resizable orientation="horizontal">
+            <kai-resizable-item size="24%" min="120px"><Pane label="List" /></kai-resizable-item>
+            <kai-resizable-item><Pane label="Chat" tone="plain" /></kai-resizable-item>
+            <kai-resizable-item ref={(e) => (previewItem = e as HTMLElement)} size="30%"><Pane label="Preview" /></kai-resizable-item>
+          </kai-resizable>
+        </Frame>
+      </div>
+    );
+  },
+};
+
+const EXPAND_TO_FILL_SNIPPET = `<!-- The artifact's "Expand" button (opt-in: expandable) fires a bubbling
+     kai-maximize-intent event. The nearest enclosing <kai-resizable> catches it
+     automatically and hides siblings so the preview panel fills the container.
+     No wiring needed between the two elements — the protocol is zero-config. -->
+
+<kai-resizable orientation="horizontal" style="display:block;height:480px">
+  <kai-resizable-item size="20%" min="120px"> …list… </kai-resizable-item>
+  <kai-resizable-item> …chat… </kai-resizable-item>
+  <kai-resizable-item size="35%" min="200px">
+    <!-- expandable opt-in: adds the Expand/Collapse button -->
+    <kai-artifact
+      src="…/index.html"
+      expandable
+    ></kai-artifact>
+  </kai-resizable-item>
+</kai-resizable>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+
+  // Optional: observe the layout events.
+  document.querySelector('kai-resizable')
+    .addEventListener('kai-change', (e) => console.log('change', e.detail.sizes));
+  document.querySelector('kai-resizable')
+    .addEventListener('kai-maximize-change', (e) => console.log('maximizechange', e.detail));
+  document.querySelector('kai-artifact')
+    .addEventListener('kai-maximize-change', (e) => console.log('artifact maximizechange', e.detail));
+</script>
+
+<!-- Cross-element protocol (hand-authored; not generated):
+  • kai-maximize-intent  — CustomEvent, bubbles:true, composed:true
+      Fired by <kai-artifact> when the Expand/Collapse button is clicked.
+      detail: { requested: boolean }  (true = maximize, false = restore)
+  • kai-maximize-state   — CustomEvent, bubbles:false, composed:true
+      Dispatched by <kai-resizable> back DOWN onto the maximized <kai-resizable-item>
+      (on maximize) or the group host + the formerly-maximized item (on restore)
+      so the artifact can reconcile its button label.
+      detail: { maximized: boolean }
+  These protocol events are NOT listed in the generated web-components.md because
+  they are cross-element — the generator only documents per-element dispatch events. -->`;
+
+/**
+ * **Expand to fill** — the headline integration: the artifact's expand button
+ * fills the preview panel to the full container width. No wiring between the
+ * two elements is needed — clicking **Expand** fires a `kai-maximize-intent` event
+ * that bubbles up to the nearest enclosing `<kai-resizable>`, which hides siblings
+ * and lets the preview panel fill. **Collapse** (or **Escape**) restores the
+ * original layout.
+ *
+ * **Cross-element protocol (hand-authored docs):**
+ * - `kai-maximize-intent` — `bubbles:true, composed:true`; fired by `<kai-artifact>`
+ *   when Expand/Collapse is toggled. `detail: { requested: boolean }`.
+ * - `kai-maximize-state` — `bubbles:false, composed:true`; dispatched by
+ *   `<kai-resizable>` back down to the affected `<kai-resizable-item>` so the
+ *   artifact can reconcile its button. `detail: { maximized: boolean }`.
+ *
+ * These protocol events are NOT in the generated `web-components.md`
+ * (the generator only documents per-element `dispatch` events — resolved decision #1).
+ */
+export const ExpandToFill: Story = {
+  name: 'Expand to fill',
+  render: () => {
+    const [log, setLog] = createSignal<string[]>([]);
+    let artifactEl: HTMLElement & { files?: ArtifactFile[] };
+    let resizableEl: HTMLElement;
+    onMount(() => {
+      if (artifactEl) artifactEl.files = ARTIFACT_FILES;
+      if (resizableEl) {
+        resizableEl.addEventListener('kai-change', (e: Event) =>
+          setLog((l) => [`change → ${JSON.stringify((e as CustomEvent).detail.sizes)}`, ...l].slice(0, 6)),
+        );
+        resizableEl.addEventListener('kai-maximize-change', (e: Event) =>
+          setLog((l) => [`kai-maximize-change → ${JSON.stringify((e as CustomEvent).detail)}`, ...l].slice(0, 6)),
+        );
+      }
+      if (artifactEl) {
+        artifactEl.addEventListener('kai-maximize-change', (e: Event) =>
+          setLog((l) => [`artifact kai-maximize-change → ${JSON.stringify((e as CustomEvent).detail)}`, ...l].slice(0, 6)),
+        );
+      }
+    });
+    return (
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+        <div
+          style={{
+            height: '480px',
+            width: '100%',
+            'max-width': '900px',
+            border: '1px solid var(--color-border, #e4e4e7)',
+            'border-radius': '8px',
+            overflow: 'hidden',
+          }}
+        >
+          <kai-resizable
+            ref={(e) => (resizableEl = e as HTMLElement)}
+            orientation="horizontal"
+          >
+            <kai-resizable-item size="20%" min="120px">
+              <Pane label="List" />
+            </kai-resizable-item>
+            <kai-resizable-item min="140px">
+              <Pane label="Chat" tone="plain" />
+            </kai-resizable-item>
+            <kai-resizable-item size="35%" min="200px">
+              <kai-artifact
+                ref={(e) => (artifactEl = e as HTMLElement & { files?: ArtifactFile[] })}
+                src={`${BASE}/index.html`}
+                iframe-title="Starboard artifact preview"
+                expandable
+              />
+            </kai-resizable-item>
+          </kai-resizable>
+        </div>
+        <pre
+          style={{
+            'font-size': '12px',
+            'max-width': '900px',
+            padding: '10px 12px',
+            'border-radius': '8px',
+            background: 'var(--color-muted, #f4f4f5)',
+            color: 'var(--color-muted-foreground, #71717a)',
+            'min-height': '72px',
+            margin: '0',
+          }}
+        >
+          {log().length ? log().join('\n') : '(click the ⤢ Expand button in the preview toolbar…)'}
+        </pre>
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: EXPAND_TO_FILL_SNIPPET, language: 'html' } } },
+};
+
+const SOLID_PARITY_SNIPPET = `// SolidJS — Artifact inside Resizable with maximizedIndex/onMaximizeChange.
+// No web components needed; works in a pure-Solid app.
+import { createSignal } from 'solid-js';
+import { Artifact } from '@kitn.ai/ui/components';
+import { Resizable, ResizablePanel } from '@kitn.ai/ui/ui';
+
+function App() {
+  const [maximizedIndex, setMaximizedIndex] = createSignal<number | null>(null);
+  return (
+    <Resizable
+      maximizedIndex={maximizedIndex()}
+      onMaximizeChange={setMaximizedIndex}
+      style="height:480px"
+    >
+      <ResizablePanel defaultSize="20%" minSize="120px">…list…</ResizablePanel>
+      <ResizablePanel minSize="140px">…chat…</ResizablePanel>
+      <ResizablePanel defaultSize="35%" minSize="200px">
+        <Artifact
+          src="…"
+          expandable
+          maximized={maximizedIndex() === 2}
+          onMaximizeChange={(m) => setMaximizedIndex(m ? 2 : null)}
+        />
+      </ResizablePanel>
+    </Resizable>
+  );
+}`;
+
+/**
+ * **SolidJS parity** — the same `list | chat | artifact` layout using the Solid
+ * `Resizable` convenience and the `Artifact` component directly (no web components).
+ * `maximizedIndex` / `onMaximizeChange` on `Resizable` mirror the web-component
+ * protocol at the Solid level. Wire `Artifact`'s `onMaximizeChange` to set the
+ * index and pass `maximized` back down to drive the button.
+ */
+export const SolidParity: Story = {
+  name: 'SolidJS parity (Resizable + Artifact)',
+  render: () => {
+    const [maximizedIndex, setMaximizedIndex] = createSignal<number | null>(null);
+    return (
+      <div
+        style={{
+          height: '480px',
+          width: '100%',
+          'max-width': '900px',
+          border: '1px solid var(--color-border, #e4e4e7)',
+          'border-radius': '8px',
+          overflow: 'hidden',
+        }}
+      >
+        <Resizable
+          maximizedIndex={maximizedIndex()}
+          onMaximizeChange={setMaximizedIndex}
+        >
+          <ResizablePanel defaultSize="20%" minSize="120px">
+            <Pane label="List" />
+          </ResizablePanel>
+          <ResizablePanel minSize="140px">
+            <Pane label="Chat" tone="plain" />
+          </ResizablePanel>
+          <ResizablePanel defaultSize="35%" minSize="200px">
+            <Artifact
+              src={`${BASE}/index.html`}
+              iframeTitle="Starboard artifact preview"
+              expandable
+              maximized={maximizedIndex() === 2}
+              onMaximizeChange={(m) => setMaximizedIndex(m ? 2 : null)}
+            />
+          </ResizablePanel>
+        </Resizable>
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: SOLID_PARITY_SNIPPET, language: 'tsx' } } },
+};