@kitn.ai/ui 0.14.1

package/src/remote/provider-runtime.ts

@@ -0,0 +1,259 @@
+// src/remote/provider-runtime.ts
+// The provider iframe-side bridge: handshake responder + CardHost impl + auto-height.
+// Security-critical, stateful, vanilla DOM ONLY — NO SolidJS imports (ships in the
+// SolidJS-free `@kitn.ai/ui/provider` bundle). See the iframe-transport design spec
+// (Provider iframe runtime surface + addendum H-A/H-D/H-E/H-J/H-H).
+
+import {
+  type CardEnvelope,
+  type CardContext,
+  type CardEvent,
+  type CardHost,
+} from '../primitives/card-contract';
+import { createPacker, isCardWireFrame, type WireMessage } from './wire';
+import { assertOrigin, redactFrame } from './origin';
+import { negotiateVersion } from './version';
+import { hasPollutionKey } from './validate';
+import { observeContentHeight } from '../primitives/use-resize-observer';
+import { validateAgainstSchema, type JsonSchema } from '../primitives/card-validate';
+
+/** A provider-side renderer for one card `type`. Renamed (was CardRenderer) per H-K
+ *  to avoid colliding with the exported Solid `<CardRenderer>` component. */
+export interface RemoteCardRenderer {
+  /** The card `type` this renderer handles. */
+  type: string;
+  /** Optional JSON Schema for this type's `data`; validated best-effort before mount. */
+  schema?: JsonSchema;
+  /** Mount into `root`, given the envelope + a CardHost. Return a disposer. */
+  mount(root: HTMLElement, envelope: CardEnvelope, host: CardHost): () => void;
+}
+
+export interface CreateCardBridgeOptions {
+  /** Element the card mounts into + whose height is observed. */
+  root: HTMLElement;
+  /** Renderers by card type. Unknown type → inline "unsupported card" + event{error}. */
+  renderers: RemoteCardRenderer[];
+  /** Versions this runtime supports (default ['1']). */
+  supportedVersions?: string[];
+}
+
+export interface CardBridge {
+  /** Begin: listen for `hello`, complete handshake, render on `render`. */
+  start(): void;
+  /** Stop observers + listeners + dispose current card. */
+  stop(): void;
+}
+
+const DEFAULT_VERSIONS = ['1'];
+
+/** A minimal complete-enough default so `CardHost.context()` never returns undefined
+ *  (the contract's return is non-optional) before the first `context` frame. */
+function defaultContext(): CardContext {
+  return { theme: { mode: 'light' }, locale: 'en' };
+}
+
+export function createCardBridge(options: CreateCardBridgeOptions): CardBridge {
+  const { root, renderers } = options;
+  const hostVersions = options.supportedVersions ?? DEFAULT_VERSIONS;
+  const rendererByType = new Map(renderers.map((r) => [r.type, r] as const));
+
+  // ── Locked-after-hello bridge identity (H-A/H-C). null until the first valid hello. ──
+  let lockedSource: unknown = null;
+  let lockedOrigin: string | null = null;
+  let nonce: string | null = null;
+  let negotiated: string | null = null;
+  let packer: ReturnType<typeof createPacker> | null = null;
+  let stopped = false; // tombstone: rejects all inbound once the version is unsupported / stopped
+
+  // ── Render state (H-E). One card at a time in v1. ──
+  let context: CardContext | null = null;
+  let currentId: string | null = null;
+  let currentEnvelope: CardEnvelope | null = null;
+  let dispose: (() => void) | null = null;
+  let stopObserver: (() => void) | null = null;
+  // The theme key applied at the current mount. A `context` push only forces a
+  // dispose+remount when the theme actually changes (renderers apply theme
+  // imperatively at mount); token/locale/a11y refreshes are read on-demand via
+  // host.context() and must NOT wipe in-progress card state.
+  let appliedThemeKey: string | null = null;
+  const themeKey = (c: CardContext | null) => JSON.stringify(c?.theme ?? null);
+
+  function warnDrop(data: unknown): void {
+    try { console.warn('[kai-remote]', redactFrame(data)); } catch { /* best-effort */ }
+  }
+
+  function postUp(message: WireMessage): void {
+    if (!packer || !lockedOrigin) return;
+    try { (parent as Window).postMessage(packer(message), lockedOrigin); } catch { /* best-effort */ }
+  }
+
+  const cardHost: CardHost = {
+    context: () => context ?? defaultContext(),
+    // HOST CONTRACT: the host MUST validate inbound event.cardId against the active card,
+    // because the provider cannot fence a replaced/stale renderer's host.emit calls.
+    emit: (event: CardEvent) => postUp({ dir: 'up', kind: 'event', event }),
+  };
+
+  function disposeCurrent(): void {
+    if (dispose) {
+      try { dispose(); } catch { /* renderer disposer threw — best-effort */ }
+    }
+    dispose = null;
+    currentId = null;
+    currentEnvelope = null;
+    appliedThemeKey = null;
+  }
+
+  function startObserver(): void {
+    // Tear down any existing observer so observeContentHeight's internal `last` baseline
+    // re-initializes to -1 and the newly-mounted card always emits its initial height.
+    stopObserver?.(); stopObserver = null;
+    stopObserver = observeContentHeight(root, (height) => {
+      if (!currentId) return;
+      cardHost.emit({ kind: 'resize', cardId: currentId, height });
+    });
+  }
+
+  function renderUnsupported(envelope: CardEnvelope, message: string): void {
+    disposeCurrent();
+    root.replaceChildren();
+    const el = document.createElement('div');
+    el.setAttribute('role', 'alert');
+    el.textContent = `Unsupported card: ${envelope.type}`;
+    root.appendChild(el);
+    currentId = envelope.id;
+    startObserver(); // placeholder has a height the host must know about
+    cardHost.emit({ kind: 'error', cardId: envelope.id, message });
+  }
+
+  function handleRender(envelope: CardEnvelope): void {
+    // Prototype-pollution guard (H-D): nested data is forwarded to app handlers.
+    if (hasPollutionKey(envelope.data)) {
+      renderUnsupported(envelope, 'rejected: payload contains a prohibited key');
+      return;
+    }
+    const renderer = rendererByType.get(envelope.type);
+    if (!renderer) {
+      renderUnsupported(envelope, `no renderer registered for type "${envelope.type}"`);
+      return;
+    }
+    // Best-effort schema validation (H-D). On failure: placeholder + event{error}.
+    if (renderer.schema) {
+      const result = validateAgainstSchema(renderer.schema, envelope.data);
+      if (!result.valid) {
+        renderUnsupported(envelope, `invalid card data: ${result.errors.join('; ')}`);
+        return;
+      }
+    }
+
+    // Re-render rules (H-E): same id OR different id → dispose current, clear, mount new
+    // (v1 has no in-place renderer update path).
+    disposeCurrent();
+    root.replaceChildren();
+    try {
+      dispose = renderer.mount(root, envelope, cardHost) ?? (() => {});
+      currentId = envelope.id;
+      currentEnvelope = envelope;
+      appliedThemeKey = themeKey(context);
+    } catch {
+      // NON-REFLECTIVE fault (H-H): never echo envelope/context content.
+      dispose = null;
+      currentId = envelope.id; // onError needs a cardId even on mount failure
+      postUp({ dir: 'up', kind: 'fault', code: 'render-failed', message: 'card failed to render' });
+      return;
+    }
+    startObserver();
+  }
+
+  function onMessage(event: MessageEvent): void {
+    if (stopped) return;
+    const data = event.data;
+
+    // ── Pre-lock: only the FIRST valid down `hello` from window.parent locks the bridge. ──
+    if (lockedSource === null) {
+      if (!isCardWireFrame(data, 'down')) return;
+      if (data.message.kind !== 'hello') return;
+      if (event.source !== window.parent) return; // host source must be the parent window
+      const supported = (data.message as { supportedVersions: string[] }).supportedVersions;
+      const picked = negotiateVersion(supported, hostVersions);
+      const echoedNonce = data.nonce;
+      const origin = event.origin;
+      if (picked === null) {
+        // No common version → fault with the host's first supported version + received nonce.
+        try {
+          (parent as Window).postMessage(
+            createPacker(hostVersions[0], echoedNonce)({ dir: 'up', kind: 'fault', code: 'version-unsupported', message: 'no compatible protocol version' }),
+            origin,
+          );
+        } catch { /* best-effort */ }
+        stopped = true; // refuse further frames
+        return;
+      }
+      // Lock identity.
+      lockedSource = event.source;
+      lockedOrigin = origin;
+      nonce = echoedNonce;
+      negotiated = picked;
+      packer = createPacker(negotiated, nonce);
+      postUp({ dir: 'up', kind: 'ready', acceptedVersion: negotiated, capabilities: { types: renderers.map((r) => r.type) } });
+      return;
+    }
+
+    // ── Post-lock: ALL gates must pass (H-A source + origin + H-D direction + nonce + version). ──
+    if (event.source !== lockedSource) { warnDrop(data); return; }
+    if (!assertOrigin(event.origin, lockedOrigin!)) { warnDrop(data); return; }
+    if (!isCardWireFrame(data, 'down')) { warnDrop(data); return; }
+    if (data.nonce !== nonce) { warnDrop(data); return; }
+    if (data.version !== negotiated) { warnDrop(data); return; }
+
+    try {
+      const message = data.message;
+      switch (message.kind) {
+        case 'hello':
+          // Re-hello after lock is ignored (bridge identity is fixed for its generation).
+          return;
+        case 'context': {
+          const next = (message as { context: CardContext }).context;
+          context = next;
+          // Live context push. Renderers read host.context() on-demand, so silent
+          // token/locale/a11y refreshes need NO remount — storing the new context is
+          // enough. Only a THEME change requires a dispose+remount, since renderers
+          // apply theme imperatively at mount (v1 has no in-place update hook).
+          if (currentEnvelope && themeKey(next) !== appliedThemeKey) {
+            handleRender(currentEnvelope); // handleRender resets appliedThemeKey
+          }
+          return;
+        }
+        case 'render':
+          handleRender((message as { envelope: CardEnvelope }).envelope);
+          return;
+        case 'teardown':
+          teardown();
+          return;
+        default:
+          warnDrop(data);
+          return;
+      }
+    } catch (e) {
+      // No throw may escape the message handler — the listener must survive.
+      warnDrop(data);
+    }
+  }
+
+  function teardown(): void {
+    disposeCurrent();
+    if (stopObserver) { stopObserver(); stopObserver = null; }
+    root.replaceChildren();
+  }
+
+  return {
+    start() {
+      window.addEventListener('message', onMessage);
+    },
+    stop() {
+      stopped = true;
+      window.removeEventListener('message', onMessage);
+      teardown();
+    },
+  };
+}

package/src/remote/provider.ts

@@ -0,0 +1,2 @@
+export { createCardBridge } from './provider-runtime';
+export type { RemoteCardRenderer, CardBridge } from './provider-runtime';

package/src/remote/validate.ts

@@ -0,0 +1,22 @@
+import type { CardEventKind } from '../primitives/card-contract';
+
+const POLLUTION = new Set(['__proto__', 'constructor', 'prototype']);
+/** Recursive guard (H-D): nested data/patch/context are forwarded to app handlers. */
+export function hasPollutionKey(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(hasPollutionKey);
+  if (value && typeof value === 'object') {
+    for (const k of Object.keys(value)) {
+      if (POLLUTION.has(k)) return true;
+      if (hasPollutionKey((value as Record<string, unknown>)[k])) return true;
+    }
+  }
+  return false;
+}
+
+// Verbs MUST match CardEventKind in card-contract.ts (verify against source).
+const KINDS: ReadonlySet<string> = new Set<CardEventKind>([
+  'ready', 'submit', 'action', 'send-prompt', 'open', 'resize', 'state', 'dismiss', 'error',
+] as CardEventKind[]);
+export function isKnownEventKind(k: unknown): k is CardEventKind {
+  return typeof k === 'string' && KINDS.has(k);
+}

package/src/remote/version.ts

@@ -0,0 +1,12 @@
+/** Contract versions are decimal integer strings ('1','2',…). */
+export function isValidVersion(s: string): boolean {
+  return /^[0-9]+$/.test(s);
+}
+
+/** Highest version both sides support; null if disjoint or any candidate is malformed. */
+export function negotiateVersion(hostVersions: string[], mine: string[]): string | null {
+  const set = new Set(mine.filter(isValidVersion));
+  const common = hostVersions.filter((v) => isValidVersion(v) && set.has(v));
+  if (common.length === 0) return null;
+  return common.sort((a, b) => Number(b) - Number(a))[0];
+}

package/src/remote/wire.ts

@@ -0,0 +1,48 @@
+import { type CardEnvelope, type CardContext, type CardEvent } from '../primitives/card-contract';
+
+export const CARD_WIRE_PROTOCOL = 'kitn-card' as const;
+
+export interface WireFrame<M extends WireMessage = WireMessage> {
+  protocol: typeof CARD_WIRE_PROTOCOL;
+  /** The NEGOTIATED contract version (set by the per-bridge packer). */
+  version: string;
+  /** Per-bridge instance nonce (host-minted, echoed on every up-frame). */
+  nonce: string;
+  message: M;
+}
+
+export type DownMessage =
+  | { dir: 'down'; kind: 'hello'; supportedVersions: string[] }
+  | { dir: 'down'; kind: 'render'; envelope: CardEnvelope }
+  | { dir: 'down'; kind: 'context'; context: CardContext }
+  | { dir: 'down'; kind: 'teardown' };
+
+export type UpMessage =
+  | { dir: 'up'; kind: 'ready'; acceptedVersion: string; capabilities?: { types?: string[] } }
+  | { dir: 'up'; kind: 'event'; event: CardEvent }
+  | { dir: 'up'; kind: 'focus-edge'; edge: 'start' | 'end' }
+  | { dir: 'up'; kind: 'fault'; code: WireFaultCode; message: string };
+
+export type WireFaultCode = 'version-unsupported' | 'bad-frame' | 'render-failed' | 'origin-rejected';
+export type WireMessage = DownMessage | UpMessage;
+
+export function createPacker(version: string, nonce: string) {
+  return function pack<M extends WireMessage>(message: M): WireFrame<M> {
+    return { protocol: CARD_WIRE_PROTOCOL, version, nonce, message };
+  };
+}
+
+/** Structural + direction guard. Host calls with 'up', runtime with 'down'.
+ *  STRUCTURAL only — nonce/version equality + schema validation happen after. */
+export function isCardWireFrame(data: unknown, expectedDir: 'up' | 'down'): data is WireFrame {
+  if (typeof data !== 'object' || data === null) return false;
+  const d = data as Record<string, unknown>;
+  const m = d.message as Record<string, unknown> | undefined;
+  return (
+    d.protocol === CARD_WIRE_PROTOCOL &&
+    typeof d.version === 'string' &&
+    typeof d.nonce === 'string' &&
+    typeof m === 'object' && m !== null &&
+    m.dir === expectedDir
+  );
+}

package/src/stories/chat-panel-layout.stories.tsx

@@ -0,0 +1,145 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal } from 'solid-js';
+import { Message, MessageAvatar, MessageContent, MessageActions } from '../components/message';
+import { ChatContainer } from '../components/chat-container';
+import { ChatConfig } from '../primitives/chat-config';
+import { PromptInput, PromptInputTextarea, PromptInputActions } from '../components/prompt-input';
+import { Button } from '../ui/button';
+import { ScrollButton } from '../components/scroll-button';
+import { Copy, ArrowUp } from 'lucide-solid';
+
+const meta: Meta = {
+  title: 'Patterns/Chat Panel Layout',
+  parameters: { layout: 'centered' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+const assistantMsg1 = `The document is a transcript of a YouTube video by Cole Medin, where he discusses building a self-evolving memory system for coding agents using Large Language Models (LLMs), inspired by Andre Karpathy's ideas on LLM knowledge bases.`;
+
+const assistantMsg2 = `Short answer: **it has to be a separate browser window** (or tab/iframe), not just a normal component in your application.
+
+Here's why:
+
+- The OAuth flow requires redirecting to the provider's login page
+- The callback URL needs to be a real URL the browser can navigate to
+- Security policies prevent embedding auth pages in iframes`;
+
+const userMsg1 = 'What is this video about?';
+const userMsg2 = 'And from what I understand, does that need to be another browser window pop-up that happens, or can I just have a component that does that in my application?';
+
+function CopyButton(props: { text: string }) {
+  return (
+    <button aria-label="Copy message" onClick={() => navigator.clipboard.writeText(props.text)}>
+      <Copy size={14} />
+    </button>
+  );
+}
+
+/**
+ * Reference layout — uses variant props, no custom class overrides.
+ */
+export const ChatGPTStyle: Story = {
+  render: () => {
+    const [input, setInput] = createSignal('');
+    return (
+      <ChatConfig proseSize="base">
+        <div
+          style={{ width: '420px', height: '700px' }}
+          class="flex flex-col overflow-hidden rounded-lg bg-card"
+        >
+          {/* Header */}
+          <div class="px-3 py-2.5 bg-muted/30 text-sm font-semibold text-foreground flex-shrink-0 flex items-center justify-between">
+            <span>Chat Panel</span>
+            <span class="text-xs text-muted-foreground">GPT-4o Mini</span>
+          </div>
+
+          {/* Messages */}
+          <ChatContainer class="flex-1 min-w-0 px-4 py-3 space-y-4">
+              {/* Assistant message 1 — with avatar */}
+              <Message>
+                <MessageAvatar src="" alt="AI" fallback="AI" />
+                <div class="flex w-full flex-col min-w-0">
+                  <MessageContent markdown class="bg-transparent p-0 pt-1.5">
+                    {assistantMsg1}
+                  </MessageContent>
+                  <MessageActions>
+                    <CopyButton text={assistantMsg1} />
+                  </MessageActions>
+                </div>
+              </Message>
+
+              {/* User message 1 */}
+              <Message class="group flex-col items-end">
+                <MessageContent class="bg-muted text-primary max-w-[85%] rounded-xl px-4 py-2 mr-1">
+                  {userMsg1}
+                </MessageContent>
+                <MessageActions class="opacity-0 group-hover:opacity-100 transition-opacity duration-150">
+                  <CopyButton text={userMsg1} />
+                </MessageActions>
+              </Message>
+
+              {/* Assistant message 2 — with avatar, markdown */}
+              <Message>
+                <MessageAvatar src="" alt="AI" fallback="AI" />
+                <div class="flex w-full flex-col min-w-0">
+                  <MessageContent markdown class="bg-transparent p-0 pt-1.5">
+                    {assistantMsg2}
+                  </MessageContent>
+                  <MessageActions>
+                    <CopyButton text={assistantMsg2} />
+                  </MessageActions>
+                </div>
+              </Message>
+
+              {/* User message 2 — longer */}
+              <Message class="group flex-col items-end">
+                <MessageContent class="bg-muted text-primary max-w-[85%] rounded-xl px-4 py-2 mr-1">
+                  {userMsg2}
+                </MessageContent>
+                <MessageActions class="opacity-0 group-hover:opacity-100 transition-opacity duration-150">
+                  <CopyButton text={userMsg2} />
+                </MessageActions>
+              </Message>
+
+              {/* Assistant message 3 — with avatar, short */}
+              <Message>
+                <MessageAvatar src="" alt="AI" fallback="AI" />
+                <div class="flex w-full flex-col min-w-0">
+                  <MessageContent markdown class="bg-transparent p-0 pt-1.5">
+                    Got it — let me know if you have more questions!
+                  </MessageContent>
+                  <MessageActions>
+                    <CopyButton text="Got it — let me know if you have more questions!" />
+                  </MessageActions>
+                </div>
+              </Message>
+            <ScrollButton />
+          </ChatContainer>
+
+          {/* Input */}
+          <div class="px-3 pb-3 pt-1 flex-shrink-0">
+            <PromptInput
+              value={input()}
+              onValueChange={setInput}
+              onSubmit={() => setInput('')}
+            >
+              <PromptInputTextarea placeholder="Ask about this page..." class="min-h-[44px] pt-3 pl-4" />
+              <PromptInputActions class="mt-2 flex w-full items-center justify-end gap-2 px-3 pb-3">
+                <Button
+                  size="icon-sm"
+                  class="rounded-full"
+                  aria-label="Send message"
+                  disabled={!input().trim()}
+                >
+                  <ArrowUp class="size-4" />
+                </Button>
+              </PromptInputActions>
+            </PromptInput>
+          </div>
+        </div>
+      </ChatConfig>
+    );
+  },
+};