@kitn.ai/ui 0.14.1

package/src/elements/confirm-card.stories.tsx

@@ -0,0 +1,227 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, type JSX } from 'solid-js';
+import './confirm-card';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { ConfirmCardData } from '../components/confirm-card';
+import type { CardEvent } from '../primitives/card-contract';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-confirm': JSX.HTMLAttributes<HTMLElement> & {
+        heading?: string;
+        'card-id'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+type ConfirmEl = HTMLElement & { data?: ConfirmCardData; resolution?: Record<string, unknown> };
+
+function Frame(props: { children: JSX.Element }) {
+  return <div style={{ 'max-width': '460px' }}>{props.children}</div>;
+}
+
+/** Mounts a <kai-confirm>, sets `.data`, logs the emitted CardEvent under the render. */
+function ConfirmDemo(props: { def: ConfirmCardData; cardId: string; heading?: string }) {
+  const [log, setLog] = createSignal<CardEvent[]>([]);
+  let el: ConfirmEl | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.data = props.def;
+    el.addEventListener('kai-card', (e) => {
+      const detail = (e as CustomEvent<CardEvent>).detail;
+      setLog((prev) => [...prev, detail]);
+    });
+  });
+  return (
+    <Frame>
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '12px' }}>
+        <kai-confirm ref={(e) => (el = e as ConfirmEl)} card-id={props.cardId} heading={props.heading} />
+        <pre
+          style={{
+            margin: 0,
+            'max-height': '180px',
+            overflow: 'auto',
+            background: 'var(--color-muted, #f4f4f5)',
+            'border-radius': '8px',
+            padding: '8px',
+            'font-size': '12px',
+          }}
+        >
+          {log().length === 0 ? '// emitted CardEvents appear here' : JSON.stringify(log(), null, 2)}
+        </pre>
+      </div>
+    </Frame>
+  );
+}
+
+const APPROVE: ConfirmCardData = {
+  body: 'This will apply 3 pending migrations to production. This cannot be undone.',
+  tone: 'warning',
+  actions: [
+    { id: 'approve', label: 'Run migration', style: 'primary', default: true },
+    { id: 'reject', label: 'Cancel' },
+  ],
+};
+
+const DESTRUCTIVE: ConfirmCardData = {
+  body: 'Permanently delete 12 files from the workspace? This cannot be undone.',
+  tone: 'danger',
+  actions: [
+    { id: 'delete', label: 'Delete files', style: 'destructive', default: true },
+    { id: 'cancel', label: 'Keep them' },
+  ],
+};
+
+const CHOICES: ConfirmCardData = {
+  heading: 'Where should I deploy?',
+  body: 'Pick a target environment for this build.',
+  actions: [
+    { id: 'staging', label: 'Staging', default: true },
+    { id: 'preview', label: 'Preview' },
+    { id: 'prod', label: 'Production', style: 'primary' },
+  ],
+};
+
+const DISMISSIBLE: ConfirmCardData = {
+  body: 'Send the drafted email to the customer?',
+  dismissible: true,
+  actions: [
+    { id: 'send', label: 'Send', style: 'primary', default: true },
+    { id: 'edit', label: 'Edit first' },
+  ],
+};
+
+const HEADING_MAP: Record<string, string | undefined> = {
+  'card-approve': 'Run database migration?',
+  'card-delete': 'Delete files?',
+  'card-deploy': undefined,
+  'card-send': 'Send email?',
+};
+
+const HTML_SNIPPET = (def: ConfirmCardData, cardId: string) => {
+  const heading = HEADING_MAP[cardId];
+  return `<kai-confirm${heading ? ` heading="${heading}"` : ''}></kai-confirm>
+<script type="module">
+  import '@kitn.ai/ui/elements'; // registers the custom elements
+
+  const el = document.querySelector('kai-confirm');
+  // \`data\` is the CardEnvelope.data (set as a property).
+  el.data = ${JSON.stringify(def, null, 2)};
+
+  // Cards bubble ONE \`kai-card\` CustomEvent carrying a typed CardEvent.
+  el.addEventListener('kai-card', (e) => {
+    const ev = e.detail; // { kind:'action', cardId, action, payload? } | { kind:'dismiss', ... } | ...
+    if (ev.kind === 'action') console.log('chose', ev.action);
+  });
+</script>`;
+};
+
+const meta = {
+  title: 'Generative UI/Cards/kai-confirm',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-confirm'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kai-confirm', [
+        "`<kai-confirm>` is a **named-intent approval** card (set via the `data` **property**): a title + body + a small set of action buttons. Activating an action emits the Card contract's **`action`** verb up a bubbling **`kai-card`** CustomEvent of `{ kind: 'action', cardId, action, payload? }`, then **resolves** the card (other actions disabled, the chosen one marked) so the same approval can't double-fire.",
+        '**Action styles:** `primary` (filled accent), `default` (outline), `destructive` (red/danger). A `tone:\'danger\'` and any destructive action add a warning icon + danger accent — never color alone. At most one action can be `default:true` (the keyboard default; gets focus only when `autofocus` is set, which is **off** by default to avoid focus-stealing mid-stream).',
+        '**Events** (all frozen Card-contract verbs): `ready` on mount, `action` on choice, `dismiss` for the optional close affordance (`dismissible:true`), `error` for a malformed definition (renders the inline `kai-card` error). It **never invents events**. The same shapes flow over the remote iframe transport unchanged.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** The canonical two-action approval (Approve / Reject). */
+export const ApproveReject: Story = {
+  render: () => <ConfirmDemo def={APPROVE} cardId="card-approve" heading="Run database migration?" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(APPROVE, 'card-approve'), language: 'html' } } },
+};
+
+/** A destructive action (`tone:'danger'` + `style:'destructive'`) — danger styling, no color-only cue. */
+export const Destructive: Story = {
+  render: () => <ConfirmDemo def={DESTRUCTIVE} cardId="card-delete" heading="Delete files?" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(DESTRUCTIVE, 'card-delete'), language: 'html' } } },
+};
+
+/** A small choice set (3 actions, one `default:true`). */
+export const ChoiceSet: Story = {
+  render: () => <ConfirmDemo def={CHOICES} cardId="card-deploy" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(CHOICES, 'card-deploy'), language: 'html' } } },
+};
+
+/** A dismissible approval (a close affordance emits the `dismiss` verb). */
+export const Dismissible: Story = {
+  render: () => <ConfirmDemo def={DISMISSIBLE} cardId="card-send" heading="Send email?" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(DISMISSIBLE, 'card-send'), language: 'html' } } },
+};
+
+const RESOLVED_CONFIRM: ConfirmCardData = {
+  body: 'Apply 3 migrations?',
+  actions: [
+    { id: 'approve', label: 'Run migration', style: 'primary' },
+    { id: 'reject', label: 'Cancel' },
+  ],
+};
+
+/** The card after the user chose **Run migration** — chromed read-only, no buttons. */
+export const Resolved: Story = {
+  name: 'Resolved (read-only)',
+  render: () => {
+    let el: ConfirmEl | undefined;
+    onMount(() => {
+      if (!el) return;
+      el.data = RESOLVED_CONFIRM;
+      el.resolution = { kind: 'action', action: 'approve' };
+    });
+    return (
+      <Frame>
+        <kai-confirm ref={(e) => (el = e as ConfirmEl)} card-id="card-resolved-confirm" heading="Run database migration?" />
+      </Frame>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `<kai-confirm heading="Run database migration?"></kai-confirm>
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  const el = document.querySelector('kai-confirm');
+  el.data = ${JSON.stringify(RESOLVED_CONFIRM, null, 2)};
+  // Setting .resolution renders the chromed read-only view — no interactive controls.
+  el.resolution = { kind: 'action', action: 'approve' };
+</script>`,
+        language: 'html',
+      },
+    },
+  },
+};
+
+/** A malformed `data` (empty `actions`) → the inline error state + an `error` event. */
+export const ErrorState: Story = {
+  render: () => <ConfirmDemo def={{ actions: [] } as unknown as ConfirmCardData} cardId="card-bad" />,
+  parameters: {
+    docs: {
+      source: {
+        code: `<kai-confirm></kai-confirm>
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  const el = document.querySelector('kai-confirm');
+  // No actions → inline error state + an \`error\` event.
+  el.data = { actions: [] };
+  el.addEventListener('kai-card', (e) => {
+    if (e.detail.kind === 'error') console.warn('confirm error:', e.detail.message);
+  });
+</script>`,
+        language: 'html',
+      },
+    },
+  },
+};

package/src/elements/confirm-card.tsx

@@ -0,0 +1,51 @@
+import { defineWebComponent } from './define';
+import { ConfirmCard, type ConfirmCardData } from '../components/confirm-card';
+import type { CardResolution } from '../primitives/card-contract';
+
+interface Props extends Record<string, unknown> {
+  /** The confirm definition (the CardEnvelope.data). Set as a JS PROPERTY:
+   *  `el.data = { body, tone, actions:[…] }`. Import `ConfirmCardData` from
+   *  `@kitn.ai/ui` for the full shape. */
+  data?: Record<string, unknown>;
+  /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
+  cardId?: string;
+  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
+  heading?: string;
+  /** Focus the default action on mount (off by default — no focus-stealing).
+   *  Attribute: `autofocus`. */
+  autofocus?: boolean;
+  /** Set when the user resolved this card; renders the read-only view. Property:
+   *  `el.resolution = { kind:'action', action:'…' }`. */
+  resolution?: Record<string, unknown>;
+}
+
+/**
+ * `<kai-confirm>` — a named-intent **approval** card (set via the `data` property):
+ * a title + body + a small set of action buttons. Activating an action emits the
+ * Card contract's **`action`** verb up a bubbling **`kai-card`** CustomEvent
+ * (`{ kind:'action', cardId, action, payload }`) and resolves the card so the same
+ * approval can't double-fire. Also emits `ready` on mount, `dismiss` for the
+ * optional close affordance, and `error` for a malformed definition (inline error).
+ * Routes through a `CardProvider` when present, else the bubbling `kai-card` event.
+ * Isolated in Shadow DOM; theme-aware via the shared kit tokens.
+ */
+defineWebComponent<Props>(
+  'kai-confirm',
+  {
+    data: undefined,
+    cardId: undefined,
+    heading: undefined,
+    autofocus: false,
+    resolution: undefined,
+  },
+  (props, { element, flag }) => (
+    <ConfirmCard
+      data={props.data as ConfirmCardData | undefined}
+      cardId={props.cardId ?? (element.id || 'kai-confirm')}
+      heading={props.heading}
+      autofocus={flag('autofocus')}
+      resolution={props.resolution as CardResolution | undefined}
+      hostElement={element}
+    />
+  ),
+);

package/src/elements/context-meter.stories.tsx

@@ -0,0 +1,151 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+
+interface ContextUsage {
+  usedTokens: number;
+  maxTokens: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  cacheTokens?: number;
+  estimatedCost?: number;
+}
+
+// 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-context': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const usage: ContextUsage = {
+  usedTokens: 48200,
+  maxTokens: 200000,
+  inputTokens: 31000,
+  outputTokens: 17200,
+  reasoningTokens: 4200,
+  cacheTokens: 8000,
+  estimatedCost: 0.42,
+};
+
+interface MeterElementProps {
+  context: ContextUsage;
+  warnThreshold?: number;
+  dangerThreshold?: number;
+  onThresholdChange?: (level: string) => void;
+}
+
+/** Render `<kai-context>` with the `context` set as a JS property. */
+function MeterElement(props: MeterElementProps) {
+  let el: (HTMLElement & { context?: ContextUsage; warnThreshold?: number; dangerThreshold?: number }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.context = props.context;
+    if (props.warnThreshold !== undefined) el.warnThreshold = props.warnThreshold;
+    if (props.dangerThreshold !== undefined) el.dangerThreshold = props.dangerThreshold;
+    if (props.onThresholdChange) {
+      el.addEventListener('kai-threshold-change', (e) => {
+        props.onThresholdChange!((e as CustomEvent<{ level: string }>).detail.level);
+      });
+    }
+  });
+  return (
+    <kai-context ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-context id="ctx"></kai-context>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  document.getElementById('ctx').context = {
+    usedTokens: 48200, maxTokens: 200000,
+    inputTokens: 31000, outputTokens: 17200,
+    reasoningTokens: 4200, cacheTokens: 8000,
+    estimatedCost: 0.42,
+  };
+</script>`;
+
+const CUSTOM_THRESHOLDS_SNIPPET = `<!-- Custom thresholds: warn at 50%, danger at 75% -->
+<kai-context id="ctx"></kai-context>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+
+  const el = document.getElementById('ctx');
+  el.context = {
+    usedTokens: 110000,  // 55% of 200 000 -> warn (> 50%)
+    maxTokens: 200000,
+    inputTokens: 70000,
+    outputTokens: 40000,
+    estimatedCost: 0.65,
+  };
+
+  // Lower the thresholds so the indicator warns earlier.
+  el.warnThreshold = 0.5;    // default 0.7
+  el.dangerThreshold = 0.75; // default 0.9
+
+  // Listen for severity changes.
+  el.addEventListener('kai-threshold-change', (e) => {
+    console.log('severity changed to', e.detail.level); // 'ok' | 'warn' | 'danger'
+  });
+</script>`;
+
+const meta = {
+  title: 'Components/Context',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-context'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-context', [
+          '`<kai-context>` is the framework-agnostic **web component** for a token/context-window usage meter — a compact gauge with a hover-card breakdown (input / output / reasoning / cache + estimated cost) — isolated in **Shadow DOM**.',
+          '**When to use:** showing how much of the context window a conversation is using, typically in a chat header. In SolidJS, compose the `Context` primitives.',
+          '**Placement:** inline in the chat header or toolbar, beside the model switcher or other header controls; it is a compact `inline-block` element and does not need a dedicated row.',
+          "**How to use:** register once with `import '@kitn.ai/ui/elements'`, then set the `context` **property** with the usage object. Hover the meter to reveal the breakdown.",
+          '**Color thresholds** are configurable via `warnThreshold` (default `0.7`) and `dangerThreshold` (default `0.9`) number properties. When the computed severity level changes, the element fires a **`kai-threshold-change`** event with `detail.level` set to `\'ok\'`, `\'warn\'`, or `\'danger\'`.',
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A meter at ~24% usage; hover to reveal the full breakdown. */
+export const Default: Story = {
+  render: () => <MeterElement context={usage} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/**
+ * Custom thresholds — `warnThreshold=0.5` and `dangerThreshold=0.75` so the
+ * meter turns yellow at 50% and red at 75%. At ~55% (110 000 / 200 000) the
+ * meter renders yellow. Open the browser console to see `kai-threshold-change`
+ * events as the property changes.
+ */
+export const CustomThresholds: Story = {
+  render: () => (
+    <MeterElement
+      context={{
+        usedTokens: 110000,
+        maxTokens: 200000,
+        inputTokens: 70000,
+        outputTokens: 40000,
+        estimatedCost: 0.65,
+      }}
+      warnThreshold={0.5}
+      dangerThreshold={0.75}
+      onThresholdChange={(level) => console.log('kai-threshold-change', { level })}
+    />
+  ),
+  parameters: { docs: { source: { code: CUSTOM_THRESHOLDS_SNIPPET, language: 'html' } } },
+};

package/src/elements/context-meter.tsx

@@ -0,0 +1,121 @@
+import { Show, createEffect, createMemo, on } from 'solid-js';
+import { defineWebComponent } from './define';
+import {
+  Context,
+  ContextTrigger,
+  ContextContent,
+  ContextContentHeader,
+  ContextContentBody,
+  ContextContentFooter,
+  ContextInputUsage,
+  ContextOutputUsage,
+  ContextReasoningUsage,
+  ContextCacheUsage,
+  computeSeverity,
+  DEFAULT_WARN_THRESHOLD,
+  DEFAULT_DANGER_THRESHOLD,
+  type ContextSeverity,
+} from '../components/context';
+
+interface ContextUsage {
+  /** Tokens consumed so far in the context window (drives the meter fill). */
+  usedTokens: number;
+  /** The model's total context-window size in tokens. */
+  maxTokens: number;
+  /** Tokens attributed to the prompt/input, shown in the breakdown. */
+  inputTokens?: number;
+  /** Tokens attributed to the generated output, shown in the breakdown. */
+  outputTokens?: number;
+  /** Tokens attributed to reasoning/thinking, shown when present. */
+  reasoningTokens?: number;
+  /** Tokens served from prompt cache, shown when present. */
+  cacheTokens?: number;
+  /** Estimated cost in dollars for this usage, shown in the footer. */
+  estimatedCost?: number;
+}
+
+interface Props extends Record<string, unknown> {
+  /** Token-usage data. Set as a JS property. */
+  context?: ContextUsage;
+  /**
+   * Fraction (0–1) above which the meter turns yellow.
+   * Defaults to `0.7` (70%).
+   */
+  warnThreshold?: number;
+  /**
+   * Fraction (0–1) above which the meter turns red.
+   * Defaults to `0.9` (90%).
+   */
+  dangerThreshold?: number;
+}
+
+/** Events fired by `<kai-context>`. */
+interface Events {
+  /**
+   * Fires when the computed severity level changes (ok → warn → danger or back).
+   * `detail.level` is `'ok'`, `'warn'`, or `'danger'`.
+   */
+  'kai-threshold-change': { level: ContextSeverity };
+}
+
+/**
+ * `<kai-context>` — a token/context-window usage meter with a hover-card
+ * breakdown (input/output/reasoning/cache + estimated cost). Data via the
+ * `context` property.
+ *
+ * **Color thresholds** are configurable via `warnThreshold` (default `0.7`)
+ * and `dangerThreshold` (default `0.9`). When the computed severity level
+ * changes, a `kai-threshold-change` event fires with `detail.level` set to
+ * `'ok'`, `'warn'`, or `'danger'`.
+ */
+defineWebComponent<Props, Events>('kai-context', {
+  context: undefined,
+  warnThreshold: undefined,
+  dangerThreshold: undefined,
+}, (props, { dispatch }) => {
+  const warn = () => (props.warnThreshold as number | undefined) ?? DEFAULT_WARN_THRESHOLD;
+  const danger = () => (props.dangerThreshold as number | undefined) ?? DEFAULT_DANGER_THRESHOLD;
+
+  const severity = createMemo<ContextSeverity>(() => {
+    const ctx = props.context;
+    if (!ctx) return 'ok';
+    return computeSeverity(ctx.usedTokens / ctx.maxTokens, warn(), danger());
+  });
+
+  // Fire kai-threshold-change only when the level actually changes.
+  createEffect(on(severity, (level, prev) => {
+    if (prev !== undefined && level !== prev) {
+      dispatch('kai-threshold-change', { level });
+    }
+  }));
+
+  return (
+    <Show when={props.context}>
+      <Context
+        usedTokens={props.context!.usedTokens}
+        maxTokens={props.context!.maxTokens}
+        inputTokens={props.context!.inputTokens}
+        outputTokens={props.context!.outputTokens}
+        reasoningTokens={props.context!.reasoningTokens}
+        cacheTokens={props.context!.cacheTokens}
+        estimatedCost={props.context!.estimatedCost}
+        warnThreshold={warn()}
+        dangerThreshold={danger()}
+      >
+        <ContextTrigger />
+        <ContextContent>
+          <ContextContentHeader />
+          <ContextContentBody>
+            <div class="space-y-1.5">
+              <ContextInputUsage />
+              <ContextOutputUsage />
+              <Show when={props.context!.reasoningTokens}><ContextReasoningUsage /></Show>
+              <Show when={props.context!.cacheTokens}><ContextCacheUsage /></Show>
+            </div>
+          </ContextContentBody>
+          <ContextContentFooter />
+        </ContextContent>
+      </Context>
+    </Show>
+  );
+});

package/src/elements/conversation-list.declarative.test.tsx

@@ -0,0 +1,137 @@
+/**
+ * Unit tests for the declarative `<kai-conversation>` light-DOM API of
+ * `<kai-conversations>`.
+ *
+ * Strategy: `defineWebComponent` registers a real Shadow-DOM custom element
+ * and is not suitable for jsdom unit tests. Instead:
+ *   1. Test the exported `parseKaiConversationElement` helper in isolation.
+ *   2. Test that the merged list of prop + slotted items renders items correctly
+ *      via a minimal ConvList harness, mirroring the pattern in
+ *      `source-list.test.tsx`.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { render, cleanup, fireEvent } from '@solidjs/testing-library';
+import { For } from 'solid-js';
+import { parseKaiConversationElement } from './conversation-list';
+import type { ConversationSummary } from '../types';
+
+afterEach(cleanup);
+
+// ---------------------------------------------------------------------------
+// parseKaiConversationElement — pure helper
+// ---------------------------------------------------------------------------
+
+describe('parseKaiConversationElement', () => {
+  function makeEl(attrs: Record<string, string | null>, textContent = ''): Element {
+    const el = document.createElement('kai-conversation');
+    for (const [k, v] of Object.entries(attrs)) {
+      if (v !== null) el.setAttribute(k, v);
+    }
+    el.textContent = textContent;
+    return el;
+  }
+
+  it('maps id attribute to ConversationSummary.id', () => {
+    const el = makeEl({ id: 'c-1' }, 'Q2 plan');
+    expect(parseKaiConversationElement(el).id).toBe('c-1');
+  });
+
+  it('uses trimmed textContent as title', () => {
+    const el = makeEl({ id: 'c-1' }, '  Q2 plan  ');
+    expect(parseKaiConversationElement(el).title).toBe('Q2 plan');
+  });
+
+  it('reads group-id attribute as groupId when present', () => {
+    const el = makeEl({ id: 'c-1', 'group-id': 'g-work' }, 'Q2 plan');
+    expect(parseKaiConversationElement(el).groupId).toBe('g-work');
+  });
+
+  it('sets groupId to undefined when group-id attribute is absent', () => {
+    const el = makeEl({ id: 'c-1' }, 'Q2 plan');
+    expect(parseKaiConversationElement(el).groupId).toBeUndefined();
+  });
+
+  it('falls back to empty string for missing id attribute', () => {
+    const el = makeEl({}, 'Untitled');
+    expect(parseKaiConversationElement(el).id).toBe('');
+  });
+
+  it('provides safe defaults for scope, messageCount, lastMessageAt, updatedAt', () => {
+    const el = makeEl({ id: 'c-1' }, 'Q2 plan');
+    const item = parseKaiConversationElement(el);
+    expect(item.scope).toEqual({ type: 'collection' });
+    expect(item.messageCount).toBe(0);
+    expect(typeof item.lastMessageAt).toBe('string');
+    expect(typeof item.updatedAt).toBe('string');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Merge: prop conversations + slotted conversations combine correctly
+// ---------------------------------------------------------------------------
+
+describe('conversation merge order', () => {
+  /** Minimal render harness that outputs a button per conversation. */
+  function ConvList(props: { items: ConversationSummary[]; onSelect: (id: string) => void }) {
+    return (
+      <div>
+        <For each={props.items}>
+          {(c) => (
+            <button type="button" onClick={() => props.onSelect(c.id)}>
+              {c.title}
+            </button>
+          )}
+        </For>
+      </div>
+    );
+  }
+
+  it('renders one item per conversation', () => {
+    const items: ConversationSummary[] = [
+      { id: 'c-1', title: 'First', scope: { type: 'collection' }, messageCount: 0, lastMessageAt: '', updatedAt: '' },
+      { id: 'c-2', title: 'Second', scope: { type: 'collection' }, messageCount: 0, lastMessageAt: '', updatedAt: '' },
+    ];
+    const { getByText } = render(() => <ConvList items={items} onSelect={() => {}} />);
+    expect(getByText('First')).toBeInTheDocument();
+    expect(getByText('Second')).toBeInTheDocument();
+  });
+
+  it('fires onSelect with the conversation id when an item is clicked', () => {
+    const onSelect = vi.fn();
+    const items: ConversationSummary[] = [
+      { id: 'c-42', title: 'API plan', scope: { type: 'collection' }, messageCount: 0, lastMessageAt: '', updatedAt: '' },
+    ];
+    const { getByText } = render(() => <ConvList items={items} onSelect={onSelect} />);
+    fireEvent.click(getByText('API plan'));
+    expect(onSelect).toHaveBeenCalledWith('c-42');
+  });
+
+  it('renders prop items before declarative (slotted) items', () => {
+    const propItems: ConversationSummary[] = [
+      { id: 'p-1', title: 'Prop conv', scope: { type: 'collection' }, messageCount: 0, lastMessageAt: '', updatedAt: '' },
+    ];
+    const slottedItems: ConversationSummary[] = [
+      { id: 's-1', title: 'Slotted conv', scope: { type: 'collection' }, messageCount: 0, lastMessageAt: '', updatedAt: '' },
+    ];
+    const merged = [...propItems, ...slottedItems];
+
+    const { getAllByRole } = render(() => <ConvList items={merged} onSelect={() => {}} />);
+    const buttons = getAllByRole('button');
+    expect(buttons).toHaveLength(2);
+    expect(buttons[0]).toHaveTextContent('Prop conv');
+    expect(buttons[1]).toHaveTextContent('Slotted conv');
+  });
+
+  it('parseKaiConversationElement produces items that render and fire correct id', () => {
+    const onSelect = vi.fn();
+    const el = document.createElement('kai-conversation');
+    el.setAttribute('id', 'c-99');
+    el.textContent = 'My conversation';
+
+    const parsed = parseKaiConversationElement(el);
+    const { getByText } = render(() => <ConvList items={[parsed]} onSelect={onSelect} />);
+    fireEvent.click(getByText('My conversation'));
+    expect(onSelect).toHaveBeenCalledWith('c-99');
+  });
+});