anentrypoint-design 0.0.195 → 0.0.197

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anentrypoint-design",
-  "version": "0.0.195",
+  "version": "0.0.197",
   "description": "247420 design system SDK — webjsx + modified ripple-ui, single-file ESM bundle for reproducible use of the AnEntrypoint design.",
   "type": "module",
   "main": "./dist/247420.js",

package/src/components/agent-chat.js

@@ -13,14 +13,44 @@
 import * as webjsx from '../../vendor/webjsx/index.js';
 import { ChatComposer, ChatMessage, makeThreadAutoScroll } from './chat.js';
 import { Select } from './content.js';
-import { Btn } from './shell.js';
+import { Btn, Icon } from './shell.js';
 
 const h = webjsx.createElement;
 
 // Auto-scroll behaviour is the shared chat helper; bind it to this thread's
 // live message count. (`makeThreadAutoScroll` takes a getter so the observer
 // always compares against current state, not a value captured at mount.)
-const threadRef = (msgCount) => makeThreadAutoScroll(() => msgCount);
+const baseAutoScroll = (msgCount) => makeThreadAutoScroll(() => msgCount);
+
+// Compose the auto-scroll ref with a scroll listener that reveals the
+// jump-to-latest button when the user has scrolled away from the bottom. This
+// is the scroll-anchoring fix: auto-scroll only pins when the user is already at
+// the bottom (the IntersectionObserver gate), so reading back-history is no
+// longer fought; the button is the explicit way back to the live edge.
+const NEAR_BOTTOM_PX = 80;
+const threadRef = (msgCount) => {
+  const auto = baseAutoScroll(msgCount);
+  return (el) => {
+    if (!el) return;
+    const disposeAuto = auto(el);
+    const jumpBtn = () => el.parentElement && el.parentElement.querySelector('.agentchat-jump');
+    const update = () => {
+      const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight < NEAR_BOTTOM_PX;
+      const btn = jumpBtn();
+      if (btn) btn.classList.toggle('show', !atBottom);
+    };
+    el.addEventListener('scroll', update, { passive: true });
+    requestAnimationFrame(update);
+    return () => { el.removeEventListener('scroll', update); if (typeof disposeAuto === 'function') disposeAuto(); };
+  };
+};
+
+// Scroll a thread to its live edge — used by the jump-to-latest button.
+function scrollThreadToBottom(btn) {
+  const wrap = btn.closest('.agentchat-thread-wrap');
+  const thread = wrap && wrap.querySelector('.agentchat-thread');
+  if (thread) thread.scrollTop = thread.scrollHeight;
+}
 
 // The agent picker: agent-then-model, not a flat model list. Unavailable agents
 // are disabled (unless installable via npx). Ordering is the host's concern.
@@ -93,6 +123,7 @@ export function AgentChat(props = {}) {
     onCwdEdit, onCwdSave, onCwdCancel, onCwdClear, onCwdDraft,
     canSend = true,
     suggestions = [], onSuggestionClick,
+    onCopyMessage, onRetryMessage, onEditMessage,
   } = props;
 
   const name = agentName || (agents.find((a) => a.id === selectedAgent)?.name) || selectedAgent || 'agent';
@@ -129,7 +160,11 @@ export function AgentChat(props = {}) {
         // accumulated source and swaps the entire bubble innerHTML on every frame
         // (O(n^2) over the turn, with a visible reflow). Downgrade md -> text
         // mid-stream; the settled turn below renders real markdown once.
-        if (isStreaming && part.kind === 'md') parts.push({ kind: 'text', text: part.text });
+        // Carry a `mdShell` flag so the streaming-text bubble uses the same
+        // container shape (.chat-md padding/spacing) the settled markdown will
+        // use — only the inner content swaps on settle, so the bubble box does
+        // not reflow/jump when the turn finishes and renders real markdown.
+        if (isStreaming && part.kind === 'md') parts.push({ kind: 'text', text: part.text, mdShell: true });
         else parts.push(part);
       }
     }
@@ -138,6 +173,19 @@ export function AgentChat(props = {}) {
     // carry prose, so a parts-driven turn isn't double-rendered.
     const partsHaveProse = parts.some(p => p.kind === 'md' || p.kind === 'text');
     if (m.content && !partsHaveProse) parts.unshift({ kind: isAssistant ? 'md' : 'text', text: m.content });
+    // The streaming caret rides the live assistant turn once it has body (the
+    // empty-shell turn already shows the inline typing dots).
+    const streaming = isStreaming && msgHasBody(m);
+    // Per-message actions: the host supplies onCopyMessage / onRetryMessage; we
+    // build the action row only for SETTLED messages (no actions mid-stream).
+    let actions;
+    if (!isStreaming && msgHasBody(m)) {
+      const built = [];
+      if (onCopyMessage) built.push({ label: 'copy', icon: 'page', title: 'copy message', onClick: () => onCopyMessage(m) });
+      if (isAssistant && onRetryMessage && i === lastIdx) built.push({ label: 'retry', icon: 'refresh', title: 'retry this turn', onClick: () => onRetryMessage(m) });
+      if (!isAssistant && onEditMessage) built.push({ label: 'edit', icon: 'pencil', title: 'edit and resend', onClick: () => onEditMessage(m) });
+      if (built.length) actions = built;
+    }
     return ChatMessage({
       key: m.id || String(i),
       who: isAssistant ? 'them' : 'you',
@@ -145,6 +193,8 @@ export function AgentChat(props = {}) {
       name: isAssistant ? name : 'you',
       time: m.time || '',
       typing: emptyStreaming,
+      streaming,
+      actions,
       parts: emptyStreaming ? undefined : (parts.length ? parts : [{ kind: 'text', text: '' }]),
     });
   });
@@ -192,14 +242,21 @@ export function AgentChat(props = {}) {
         // reconnecting-while-streaming state reads one word everywhere instead of
         // the head saying "streaming…" while the controls say "reconnecting…".
         busy ? (status || 'streaming…') : (messages.length ? messages.length + (messages.length === 1 ? ' message' : ' messages') : ''))),
-    h('div', { class: 'agentchat-thread', ref: threadRef(messages.length), role: 'log', 'aria-label': 'conversation' },
-      emptyState,
-      ...rows.filter(Boolean),
-      showWorkingTail
-        ? h('div', { key: '_working', class: 'agentchat-working', role: 'status', 'aria-live': 'polite' },
-            h('span', { class: 'chat-thinking-dots', 'aria-hidden': 'true' }, h('span'), h('span'), h('span')),
-            h('span', { class: 'agentchat-working-text' }, 'working…'))
-        : null),
+    h('div', { class: 'agentchat-thread-wrap' },
+      h('div', { class: 'agentchat-thread', ref: threadRef(messages.length), role: 'log', 'aria-label': 'conversation' },
+        emptyState,
+        ...rows.filter(Boolean),
+        showWorkingTail
+          ? h('div', { key: '_working', class: 'agentchat-working', role: 'status', 'aria-live': 'polite' },
+              h('span', { class: 'chat-thinking-dots', 'aria-hidden': 'true' }, h('span'), h('span'), h('span')),
+              h('span', { class: 'agentchat-working-text' }, 'working…'))
+          : null),
+      // Jump-to-latest: hidden until the scroll listener adds .show (user scrolled
+      // up). Clicking returns to the live edge. Pure-DOM, like the kit's other
+      // stateless chrome, so the host needn't thread scroll state through state.
+      h('button', { class: 'agentchat-jump', type: 'button', 'aria-label': 'jump to latest', title: 'jump to latest',
+        onclick: (e) => scrollThreadToBottom(e.currentTarget) },
+        Icon('arrow-down', { size: 16 }), h('span', { class: 'agentchat-jump-label' }, 'latest'))),
     composer,
   );
 }

package/src/components/chat.js

@@ -19,6 +19,21 @@ export function fmtBytes(n) {
     return (n / (1024 * 1024 * 1024)).toFixed(2) + ' GB';
 }
 
+// Reject dangerous URL schemes (javascript:, data:, vbscript:, file:) so an
+// inline markdown link or an image src built from untrusted text can't smuggle a
+// script-executing or data-exfiltrating URL past the inline renderer (which does
+// NOT pass through DOMPurify the way the full md path does). http(s), mailto,
+// protocol-relative, root/relative, and anchor links are allowed.
+export function safeUrl(url) {
+    const s = String(url == null ? '' : url).trim();
+    if (!s) return null;
+    // Allow relative / anchor / protocol-relative without a scheme.
+    if (/^(\/|\.|#|\?)/.test(s) || s.startsWith('//')) return s;
+    const scheme = (s.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/) || [])[1];
+    if (!scheme) return s; // schemeless relative
+    return /^(https?|mailto|tel)$/i.test(scheme) ? s : null;
+}
+
 // Inline-only markdown subset; safe for chat bubbles.
 export function renderInline(text) {
     if (text == null) return [];
@@ -31,7 +46,13 @@ export function renderInline(text) {
         if (m[2] != null) push(h('strong', { key: 's' + i }, m[2]));
         else if (m[3] != null) push(h('em', { key: 's' + i }, m[3]));
         else if (m[4] != null) push(h('code', { key: 's' + i, class: 'chat-tick' }, m[4]));
-        else if (m[5] != null) push(h('a', { key: 's' + i, href: m[6], target: '_blank', rel: 'noopener' }, m[5]));
+        else if (m[5] != null) {
+            const safe = safeUrl(m[6]);
+            // A link with a rejected (unsafe) scheme degrades to its plain label
+            // text rather than a clickable, scheme-smuggling anchor.
+            if (safe) push(h('a', { key: 's' + i, href: safe, target: '_blank', rel: 'noopener noreferrer' }, m[5]));
+            else push(h('span', { key: 's' + i }, m[5]));
+        }
         last = m.index + m[0].length; i += 1;
     }
     if (last < text.length) push(h('span', { key: 's' + i + 'a' }, text.slice(last)));
@@ -133,7 +154,13 @@ function ToolCallNode(p) {
                 h('pre', { class: 'chat-tool-pre' }, h('code', {}, argsText))),
             resultText ? h('div', { class: 'chat-tool-section' },
                 h('div', { class: 'chat-tool-section-label' }, p.error ? 'error' : 'result'),
-                h('pre', { class: 'chat-tool-pre' + (p.error ? ' is-error' : '') }, h('code', {}, resultText))) : null
+                h('pre', { class: 'chat-tool-pre' + (p.error ? ' is-error' : '') }, h('code', {}, resultText)))
+                // A finished tool with no output would otherwise render no result
+                // section, reading identically to a still-running tool. Show an
+                // explicit placeholder so "done, empty" is distinguishable.
+                : (status === 'done' ? h('div', { class: 'chat-tool-section' },
+                    h('div', { class: 'chat-tool-section-label' }, 'result'),
+                    h('pre', { class: 'chat-tool-pre chat-tool-empty' }, h('code', {}, '(no output)'))) : null)
         )
     );
 }
@@ -146,16 +173,24 @@ function ThinkingNode(p) {
 }
 
 const PART_RENDERERS = {
-    text:  (p) => h('div', { class: 'chat-bubble' }, ...renderInline(p.text || '')),
+    text:  (p) => h('div', { class: 'chat-bubble' + (p.mdShell ? ' chat-md' : '') }, ...renderInline(p.text || '')),
     md:    (p) => MdNode(p),
     code:  (p) => CodeNode(p),
     tool:        (p) => ToolCallNode(p),
     tool_call:   (p) => ToolCallNode(p),
     tool_result: (p) => ToolCallNode({ ...p, name: p.name || 'tool_result', result: p.text != null ? p.text : p.result }),
     thinking:    (p) => ThinkingNode(p),
-    image: (p) => h('a', { class: 'chat-image', href: p.href || p.src, target: '_blank', rel: 'noopener', 'aria-label': p.alt || `embedded image: ${p.src}` },
-        h('img', { src: p.src, alt: p.alt || `embedded image from ${p.src}`, loading: 'lazy' }),
-        p.caption ? h('span', { class: 'cap' }, p.caption) : null),
+    image: (p) => {
+        // Guard both the wrapping link and the img src against unsafe schemes
+        // (e.g. a data:text/html src) so an embedded-image part from untrusted
+        // markdown can't smuggle an active payload.
+        const imgSrc = safeUrl(p.src);
+        const linkHref = safeUrl(p.href || p.src);
+        if (!imgSrc) return h('span', { class: 'chat-image-blocked' }, p.alt || 'image blocked (unsafe url)');
+        return h('a', { class: 'chat-image', href: linkHref || imgSrc, target: '_blank', rel: 'noopener noreferrer', 'aria-label': p.alt || `embedded image: ${imgSrc}` },
+            h('img', { src: imgSrc, alt: p.alt || `embedded image from ${imgSrc}`, loading: 'lazy' }),
+            p.caption ? h('span', { class: 'cap' }, p.caption) : null);
+    },
     pdf:   (p) => h('div', { class: 'chat-pdf' },
         h('div', { class: 'chat-pdf-head' },
             h('span', { class: 'glyph', 'aria-hidden': 'true' }, Icon('file-pdf', { size: 18 })),
@@ -171,7 +206,7 @@ const PART_RENDERERS = {
             h('span', { class: 'size' }, [p.kindLabel || (p.name || '').split('.').pop().toUpperCase(), p.size != null ? fmtBytes(p.size) : null].filter(Boolean).join(' · '))
         ),
         h('span', { class: 'go', 'aria-hidden': 'true' }, Icon('arrow-down'))),
-    link:  (p) => h('a', { class: 'chat-link', href: p.href, target: '_blank', rel: 'noopener', 'aria-label': `link: ${p.title || p.href}` },
+    link:  (p) => h('a', { class: 'chat-link', href: safeUrl(p.href) || '#', target: '_blank', rel: 'noopener noreferrer', 'aria-label': `link: ${p.title || p.href}` },
         p.thumb ? h('img', { class: 'thumb', src: p.thumb, alt: `preview for ${p.title || p.href}` }) : null,
         h('span', { class: 'meta' },
             h('span', { class: 'host' }, p.host || (() => { try { return new URL(p.href).host; } catch { return ''; } })()),
@@ -188,7 +223,7 @@ function renderPart(p, key) {
     return node;
 }
 
-export function ChatMessage({ role, who = 'them', avatar, text, parts, time, typing, key, aicat, reactions, receipt, name }) {
+export function ChatMessage({ role, who = 'them', avatar, text, parts, time, typing, key, aicat, reactions, receipt, name, streaming, actions }) {
     _stats.messages += 1;
     // Support legacy 'who' prop, prefer 'role' with mapping:
     //   'user'      -> 'you'   (right-aligned, accent bubble)
@@ -212,6 +247,11 @@ export function ChatMessage({ role, who = 'them', avatar, text, parts, time, typ
     if (typing) bodyNodes = [h('div', { class: 'chat-bubble', key: 'typb' }, h('span', { class: 'chat-typing' }, h('span'), h('span'), h('span')))];
     else if (parts && parts.length) bodyNodes = parts.map((p, i) => renderPart(p, i));
     else bodyNodes = [h('div', { class: 'chat-bubble', key: 't' }, ...renderInline(text || ''))];
+    // A blinking caret at the stream head: while an assistant turn is streaming
+    // AND already shows content (so the inline typing dots have stopped), append
+    // a thin caret so the live edge reads as "still writing", not "done". Drawn as
+    // a CSS element, not a glyph character.
+    if (streaming && !typing) bodyNodes = [...bodyNodes, h('span', { key: '_caret', class: 'chat-stream-caret', 'aria-hidden': 'true' })];
     const reactionRow = reactions && reactions.length
         ? h('div', { class: 'chat-reactions' },
             ...reactions.map((r, i) => h('span', { class: 'rxn' + (r.you ? ' you' : ''), key: 'r' + i, 'aria-label': `${r.emoji} reaction (${String(r.count)} ${String(r.count) === '1' ? 'reaction' : 'reactions'})${r.you ? ' - you reacted' : ''}` },
@@ -225,7 +265,19 @@ export function ChatMessage({ role, who = 'them', avatar, text, parts, time, typ
     if (time) metaItems.push(h('span', { class: 't', key: 'ti' }, time));
     if (tickNode) metaItems.push(tickNode);
     const meta = metaItems.length ? h('div', { class: 'chat-meta' }, ...metaItems) : null;
-    const stack = h('div', { class: 'chat-stack' }, ...bodyNodes, reactionRow, meta);
+    // Per-message actions (copy / retry / edit) — a hover-revealed control row
+    // below the bubble, the way Claude-Desktop surfaces message-level actions.
+    // Each action is { label, icon, onClick, title }. Kept icon-only with an
+    // accessible name; no decorative glyphs (the Icon set is line-SVG).
+    const actionRow = (actions && actions.length)
+        ? h('div', { class: 'chat-msg-actions', role: 'group', 'aria-label': 'message actions' },
+            ...actions.filter(Boolean).map((a, i) => h('button', {
+                key: 'ma' + i, type: 'button', class: 'chat-msg-action',
+                title: a.title || a.label, 'aria-label': a.label || a.title,
+                onclick: (e) => { e.preventDefault(); a.onClick && a.onClick(e); },
+            }, a.icon ? Icon(a.icon, { size: 14 }) : (a.label || ''))))
+        : null;
+    const stack = h('div', { class: 'chat-stack' }, ...bodyNodes, reactionRow, actionRow, meta);
     // Centered roles (system/tool/thinking) skip the avatar column entirely so
     // the bubble owns the full row — the chrome reads as out-of-band signal,
     // not a participant turn.
@@ -293,7 +345,6 @@ export function Chat({ title = 'chat', sub, messages = [], composer, header, sug
     const msgCount = messages.length;
     return h('div', { class: 'chat' },
         header || h('div', { class: 'chat-head', role: 'banner' },
-            h('span', { class: 'dot', 'aria-hidden': 'true' }),
             h('h2', { class: 'ds-chat-title' }, title),
             sub ? h('span', { class: 'sub', 'aria-label': `subtitle: ${sub}` }, ' · ' + sub) : null,
             h('span', { class: 'spread' }),

package/src/components/content.js

@@ -253,8 +253,11 @@ export function ProjectView({ project = {}, copied, onCopy } = {}) {
     ].filter(Boolean).flat();
 }
 
-export function PageHeader({ title, lede, eyebrow, right }) {
-    return h('section', { class: 'ds-section' },
+export function PageHeader({ title, lede, eyebrow, right, compact }) {
+    // `compact` drops the large leading/trailing section margins so a PageHeader
+    // used as a page's first element top-aligns cleanly without the consumer
+    // having to !important-override the .ds-section margin.
+    return h('section', { class: 'ds-section' + (compact ? ' ds-section-compact' : '') },
         eyebrow ? h('span', { class: 'eyebrow' }, eyebrow) : null,
         title != null ? h('h1', {}, title) : null,
         lede != null ? h('p', { class: 'lede' }, lede) : null,

package/src/components/context-pane.js

@@ -0,0 +1,77 @@
+// ContextPane — a compact right-hand context panel for the chat surface.
+//
+// Surfaces the current conversation's agent, model, working directory, and a
+// live count of running tool calls in the in-flight turn. Built from the kit's
+// Panel + Row primitives so it inherits the design tokens and rail semantics.
+//
+// Usage (consumer wires its own state):
+//   ContextPane({ agent, model, cwd, toolCount, onSetCwd })
+//
+// Props:
+//   agent     : display name of the active agent (string) or falsy for "none"
+//   model     : model id/name (string) or falsy
+//   cwd       : the chat working directory (string) or falsy for server default
+//   toolCount : number of tool calls running in the current live turn (>=0)
+//   usage     : OPTIONAL last-turn usage { inputTokens, outputTokens, costUsd, turns, durationMs }
+//   session   : OPTIONAL session metadata { id, messages, startedAt } shown as a block
+//   onSetCwd  : optional callback for the "set working directory" affordance
+//
+// No decorative glyphs — words + the kit's Icon SVGs only.
+
+import * as webjsx from '../../vendor/webjsx/index.js';
+import { Panel, Row } from './content.js';
+import { Btn } from './shell.js';
+
+const h = webjsx.createElement;
+
+function fmtTok(n) {
+    if (n == null) return null;
+    if (n < 1000) return String(n);
+    if (n < 1000000) return (n / 1000).toFixed(n < 10000 ? 1 : 0) + 'k';
+    return (n / 1000000).toFixed(1) + 'M';
+}
+
+export function ContextPane({ agent, model, cwd, toolCount = 0, usage, session, onSetCwd } = {}) {
+    const running = Number(toolCount) > 0;
+    // Each Panel's children array is all-unkeyed (no key prop on any sibling),
+    // so webjsx never sees a mixed keyed/unkeyed array here.
+    const panels = [
+        Panel({
+            title: 'context',
+            children: [
+                Row({ title: 'agent', meta: agent || 'none' }),
+                Row({ title: 'model', meta: model || '—' }),
+                Row({
+                    title: 'working dir',
+                    sub: cwd || 'server default',
+                    // Use the rail tone consistently with the GUI-wide semantics:
+                    // green = active/ok. A default cwd carries no rail (neutral).
+                    rail: cwd ? 'green' : null,
+                }),
+                Row({
+                    title: 'running tools',
+                    meta: running ? String(toolCount) : 'idle',
+                    rail: running ? 'purple' : null,
+                }),
+            ],
+        }),
+    ];
+    // Usage block: surface the last turn's token/cost/turn/duration so the
+    // result event is no longer silently dropped.
+    if (usage && (usage.inputTokens != null || usage.outputTokens != null || usage.costUsd != null)) {
+        const tokRows = [];
+        if (usage.inputTokens != null) tokRows.push(Row({ title: 'input', meta: fmtTok(usage.inputTokens) + ' tok' }));
+        if (usage.outputTokens != null) tokRows.push(Row({ title: 'output', meta: fmtTok(usage.outputTokens) + ' tok' }));
+        if (usage.costUsd != null) tokRows.push(Row({ title: 'cost', meta: '$' + usage.costUsd.toFixed(4) }));
+        if (usage.turns != null) tokRows.push(Row({ title: 'turns', meta: String(usage.turns) }));
+        if (usage.durationMs != null) tokRows.push(Row({ title: 'duration', meta: (usage.durationMs / 1000).toFixed(1) + 's' }));
+        panels.push(Panel({ title: 'last turn', children: tokRows }));
+    }
+    return h('div', { class: 'ds-context' },
+        ...panels,
+        onSetCwd
+            ? h('div', { class: 'ds-context-actions' },
+                Btn({ onClick: onSetCwd, children: 'set working dir' }))
+            : null,
+    );
+}

package/src/components/files.js

@@ -77,7 +77,49 @@ export function FileRow({ name, type = 'other', size, modified, code, onOpen, on
     );
 }
 
-export function FileGrid({ files = [], onOpen, onAction, emptyText = 'no files here yet', columns = 'auto' } = {}) {
+// FileSkeleton — placeholder shimmer rows shown while a directory loads, so the
+// grid does not flash from a bare spinner to a full list (predictable perceived
+// perf, the file-manager feel). `rows` controls how many ghost rows render.
+export function FileSkeleton({ rows = 8 } = {}) {
+    return h('div', { class: 'ds-file-grid ds-file-skeleton', 'aria-hidden': 'true' },
+        ...Array.from({ length: Math.max(1, rows) }, (_, i) => h('div', { key: 'sk' + i, class: 'ds-file-row ds-file-row-skeleton' },
+            h('span', { class: 'ds-skel ds-skel-icon' }),
+            h('span', { class: 'ds-skel ds-skel-title' }),
+            h('span', { class: 'ds-skel ds-skel-meta' })))
+    );
+}
+
+// Sort a file list by a key (name/size/modified/type), dirs-first always so the
+// hierarchy reads top-down regardless of sort. `dir` is 'asc'|'desc'.
+// `modifiedTs` (epoch ms) is used for the modified sort when present, since the
+// `modified` field is a pre-formatted relative string the host passes for display.
+export function sortFiles(files = [], sort = 'name', dir = 'asc') {
+    const mul = dir === 'desc' ? -1 : 1;
+    const cmp = (a, b) => {
+        // Directories always cluster before files; within a cluster, apply the sort.
+        const ad = a.type === 'dir' ? 0 : 1, bd = b.type === 'dir' ? 0 : 1;
+        if (ad !== bd) return ad - bd;
+        let r = 0;
+        if (sort === 'size') r = (a.size || 0) - (b.size || 0);
+        else if (sort === 'modified') r = (a.modifiedTs || 0) - (b.modifiedTs || 0);
+        else if (sort === 'type') r = String(a.type || '').localeCompare(String(b.type || ''));
+        else r = String(a.name || '').localeCompare(String(b.name || ''), undefined, { numeric: true, sensitivity: 'base' });
+        return r * mul || String(a.name || '').localeCompare(String(b.name || ''));
+    };
+    return files.slice().sort(cmp);
+}
+
+// FileGrid — the directory listing. Optional in-grid sort + filter make it a
+// real file manager rather than a static dump:
+//   sort   : { key, dir, onSort(key) }  - clickable column headers (name/size/modified)
+//   filter : { value, onInput, placeholder } - a quick in-dir name filter
+//   onOpen(f) opens a row; onAction(act,f) wires the per-row download/rename/delete.
+// Keyboard nav: the grid is a focusable listbox - ArrowUp/Down move the active
+// row, Enter opens it, Backspace asks the host to go up (onUp). The host keeps no
+// focus state; the grid tracks it on the DOM via roving tabindex.
+export function FileGrid({ files = [], onOpen, onAction, onUp, emptyText = 'no files here yet',
+                          columns = 'auto', sort, filter, loading = false } = {}) {
+    if (loading) return FileSkeleton({});
     if (!files.length) return EmptyState({ text: emptyText });
     const gridAttrs = {};
     if (columns !== 'auto' && columns > 0) {
@@ -89,7 +131,27 @@ export function FileGrid({ files = [], onOpen, onAction, emptyText = 'no files h
             gap: 'var(--space-3)'
         };
     }
-    return h('div', { class: 'ds-file-grid', ...gridAttrs },
+    // Keyboard: roving focus over the .ds-file-open buttons inside the grid.
+    const onKeyDown = (e) => {
+        const grid = e.currentTarget;
+        const opens = Array.from(grid.querySelectorAll('.ds-file-open:not([disabled])'));
+        if (!opens.length) return;
+        const cur = opens.indexOf(document.activeElement);
+        if (e.key === 'ArrowDown') { e.preventDefault(); opens[Math.min(opens.length - 1, cur + 1)]?.focus(); }
+        else if (e.key === 'ArrowUp') { e.preventDefault(); (cur <= 0 ? opens[0] : opens[cur - 1])?.focus(); }
+        else if (e.key === 'Home') { e.preventDefault(); opens[0]?.focus(); }
+        else if (e.key === 'End') { e.preventDefault(); opens[opens.length - 1]?.focus(); }
+        else if (e.key === 'Backspace') { e.preventDefault(); onUp && onUp(); }
+    };
+    const head = sort ? FileSortHeader(sort) : null;
+    const filterBar = filter ? h('div', { class: 'ds-file-filter' },
+        h('input', {
+            class: 'ds-file-filter-input', type: 'search',
+            value: filter.value || '', placeholder: filter.placeholder || 'Filter files',
+            'aria-label': filter.placeholder || 'Filter files in this directory',
+            oninput: (e) => filter.onInput && filter.onInput(e.target.value),
+        })) : null;
+    const grid = h('div', { class: 'ds-file-grid', role: 'listbox', 'aria-label': 'files', tabindex: '0', onkeydown: onKeyDown, ...gridAttrs },
         ...files.map((f, i) => FileRow({
             key: f.path || f.name + i,
             name: f.name, type: f.type, size: f.size, modified: f.modified, code: f.code, active: f.active,
@@ -97,6 +159,23 @@ export function FileGrid({ files = [], onOpen, onAction, emptyText = 'no files h
             onAction: onAction ? (act) => onAction(act, f) : null
         }))
     );
+    return (head || filterBar)
+        ? h('div', { class: 'ds-file-listing' }, filterBar, head, grid)
+        : grid;
+}
+
+// Clickable column headers for FileGrid sort. Active column shows its direction
+// as an ASCII caret word (asc/desc) - never a glyph arrow.
+function FileSortHeader({ key: active = 'name', dir = 'asc', onSort } = {}) {
+    const cols = [['name', 'name'], ['size', 'size'], ['modified', 'modified']];
+    return h('div', { class: 'ds-file-sort', role: 'group', 'aria-label': 'sort files' },
+        ...cols.map(([k, label]) => h('button', {
+            key: k, type: 'button',
+            class: 'ds-file-sort-btn' + (active === k ? ' active' : ''),
+            'aria-pressed': active === k ? 'true' : 'false',
+            'aria-label': 'sort by ' + label + (active === k ? ' (' + (dir === 'asc' ? 'ascending' : 'descending') + ')' : ''),
+            onclick: () => onSort && onSort(k),
+        }, label + (active === k ? ' ' + (dir === 'asc' ? 'asc' : 'desc') : ''))));
 }
 
 export function FileToolbar({ left = [], right = [] } = {}) {

package/src/components/sessions.js

@@ -0,0 +1,147 @@
+// Session surfaces — a persistent conversation list (left-rail "Chats") and a
+// live multi-session dashboard. Pure factories: props in, webjsx vnode out, all
+// interaction via host callbacks. Styling lives in chat.css (.ds-session*,
+// .ds-dash*) using kit tokens; no transport, no decorative glyphs.
+
+import * as webjsx from '../../vendor/webjsx/index.js';
+import { Btn, Icon } from './shell.js';
+const h = webjsx.createElement;
+
+// ConversationList — the Claude-Desktop "Chats" column. Sessions grouped by a
+// caller-supplied group label, each row showing title/project, relative time,
+// agent badge, and a running/new-event indicator. Selecting a row switches the
+// active conversation.
+//
+//   sessions : [{ sid, title, project, agent, time, running, unread, rail }]
+//   selected : the active sid
+//   groups   : OPTIONAL [{ label, sids:[...] }] to bucket rows; else one flat list
+//   search   : { value, onInput, placeholder } inline filter (optional)
+//   onSelect(session), onNew() : intents
+//   emptyText, loading, error  : explicit states
+export function ConversationList({ sessions = [], selected, groups, search,
+                                   onSelect, onNew, newLabel = 'New chat',
+                                   emptyText = 'No conversations yet', loading = false, error = null } = {}) {
+  const rowFor = (s, i) => h('button', {
+    // Stable key: prefer sid, else position - a missing/duplicate sid would make
+    // key undefined and crash webjsx applyDiff ("reading 'key'" of undefined).
+    key: 'cs-' + (s.sid != null ? s.sid : 'i' + i),
+    type: 'button',
+    class: 'ds-session-row' + (s.sid === selected ? ' active' : '') + (s.rail ? ' rail-' + s.rail : ''),
+    'aria-current': s.sid === selected ? 'true' : null,
+    onclick: () => onSelect && onSelect(s),
+  },
+    // Positional children must NOT mix keyed VElements with null/strings (webjsx
+    // applyDiff crashes "reading 'key'"). Keep these unkeyed and filter nulls so
+    // each h() call gets a clean, consistent child list.
+    h('span', { class: 'ds-session-main' }, [
+      h('span', { class: 'ds-session-title' }, s.title || s.project || s.sid || ''),
+      (s.project || s.time) ? h('span', { class: 'ds-session-sub' },
+        [s.project, s.time].filter(Boolean).join(' · ')) : null,
+    ].filter(Boolean)),
+    h('span', { class: 'ds-session-meta' }, [
+      s.agent ? h('span', { class: 'ds-session-agent' }, s.agent) : null,
+      s.running
+        ? h('span', { class: 'status-dot-disc status-dot-live', 'aria-label': 'running', role: 'img' })
+        : (s.unread ? h('span', { class: 'ds-session-unread', 'aria-label': 'new activity', role: 'img' }) : null),
+    ].filter(Boolean)));
+
+  // The body is ALWAYS a single keyed wrapper element of the same tag, so webjsx
+  // diffs its children across state transitions (loading -> empty -> populated)
+  // instead of swapping the container type - the swap is what triggered the
+  // applyDiff "reading 'key'" crash on the first populated mount. Row children
+  // are uniformly keyed; non-row states render a single unkeyed status line.
+  let inner;
+  if (loading) {
+    inner = [h('div', { key: 'st', class: 'ds-session-state', role: 'status', 'aria-live': 'polite' }, 'Loading conversations…')];
+  } else if (error) {
+    inner = [h('div', { key: 'st', class: 'ds-session-state ds-session-state-error', role: 'status' }, String(error))];
+  } else if (!sessions.length) {
+    inner = [h('div', { key: 'st', class: 'ds-session-state', role: 'status' }, emptyText)];
+  } else if (groups && groups.length) {
+    const bySid = new Map(sessions.map((s) => [s.sid, s]));
+    inner = groups.map((g) => h('div', { key: 'g-' + g.label, class: 'ds-session-group', role: 'group', 'aria-label': g.label },
+      h('div', { key: 'gl', class: 'ds-session-group-label' }, g.label),
+      h('div', { key: 'gr', class: 'ds-session-group-rows', role: 'list' }, ...g.sids.map((sid) => bySid.get(sid)).filter(Boolean).map(rowFor))));
+  } else {
+    inner = sessions.map(rowFor);
+  }
+  const body = h('div', { key: 'body', class: 'ds-session-list', role: 'list' }, ...inner);
+
+  return h('div', { class: 'ds-sessions' },
+    h('div', { key: 'head', class: 'ds-session-head' },
+      onNew ? h('button', { key: 'new', type: 'button', class: 'ds-session-new', onclick: onNew, 'aria-label': newLabel },
+        Icon('pencil'), h('span', { key: 'l' }, newLabel)) : null,
+      search ? h('input', {
+        key: 'search', type: 'search', class: 'ds-session-search',
+        value: search.value || '', placeholder: search.placeholder || 'Search conversations',
+        'aria-label': search.placeholder || 'Search conversations',
+        oninput: (e) => search.onInput && search.onInput(e.target.value),
+      }) : null),
+    body);
+}
+
+// SessionCard — one running session in the live dashboard. Status dot, agent /
+// model / cwd, elapsed, live counter, last activity, and per-session controls
+// that each act on this session's id independently.
+//
+//   session : { sid, agent, model, cwd, elapsed, counter, lastActivity, currentTool, status }
+//   actions : { onStop, onOpen, onResume, onView } (any subset)
+// `counter` carries the live activity tally (e.g. "12 ev · 3 tools"); `lastActivity`
+// the relative time of the most-recent event ("4s ago"); `currentTool` the tool
+// name a still-running turn is executing - together they distinguish a busy
+// session from a stuck one (a frozen elapsed alone reads identically for both).
+export function SessionCard({ session = {}, onStop, onOpen, onResume, onView } = {}) {
+  const s = session;
+  const statusTone = s.status === 'error' ? 'flame' : 'live';
+  // The stat line composes elapsed + live counter; the activity line carries the
+  // last-activity time and the current tool so a card shows MOTION, not just a
+  // start offset. Both are middot-joined (kept product separator).
+  const statBits = [s.elapsed != null ? s.elapsed : null, s.counter != null ? s.counter : null].filter((x) => x != null && x !== '');
+  const activityBits = [
+    s.currentTool ? 'running: ' + s.currentTool : null,
+    s.lastActivity ? 'last ' + s.lastActivity : null,
+  ].filter(Boolean);
+  return h('div', { class: 'ds-dash-card' + (s.status === 'error' ? ' is-error' : ''), role: 'group', 'aria-label': 'session ' + (s.agent || s.sid) },
+    h('div', { class: 'ds-dash-card-head' },
+      h('span', { class: 'status-dot-disc ' + (statusTone === 'live' ? 'status-dot-live' : 'status-dot-error'), 'aria-hidden': 'true' }),
+      // Status is words + the disc, never colour alone (WCAG 1.4.1): the disc is
+      // aria-hidden, so the visible/AT status word carries the state.
+      h('span', { class: 'ds-dash-status ' + (s.status === 'error' ? 'is-error' : 'is-running') }, s.status === 'error' ? 'error' : 'running'),
+      h('span', { class: 'ds-dash-agent' }, s.agent || 'agent'),
+      s.model ? h('span', { class: 'ds-dash-model' }, s.model) : null),
+    h('div', { class: 'ds-dash-meta' },
+      s.cwd ? h('span', { class: 'ds-dash-cwd', title: s.cwd }, s.cwd) : null,
+      statBits.length ? h('span', { class: 'ds-dash-stat' }, statBits.join(' · ')) : null,
+      activityBits.length ? h('span', { class: 'ds-dash-activity' }, activityBits.join(' · ')) : null),
+    h('div', { class: 'ds-dash-actions', role: 'group', 'aria-label': 'session actions' },
+      onOpen ? Btn({ key: 'open', onClick: () => onOpen(s), children: 'open' }) : null,
+      onResume ? Btn({ key: 'resume', onClick: () => onResume(s), children: 'resume' }) : null,
+      onView ? Btn({ key: 'view', onClick: () => onView(s), children: 'events' }) : null,
+      onStop ? Btn({ key: 'stop', danger: true, onClick: () => onStop(s), children: 'stop' }) : null));
+}
+
+// SessionDashboard — grid of SessionCards for ALL live sessions, managed at once.
+//   sessions : [{ sid, agent, model, cwd, elapsed, counter, lastActivity, currentTool, status }]
+//   actions  : { onStop, onOpen, onResume, onView } passed to each card
+//   onStopAll : OPTIONAL bulk control - stop every running session at once
+//   emptyText, offline : explicit states
+// The bulk header is the "manage many at once" affordance: a live count plus a
+// stop-all button, so a user running several agents does not have to hunt each
+// card's stop. Rendered only when there are sessions AND onStopAll is wired.
+export function SessionDashboard({ sessions = [], onStop, onOpen, onResume, onView, onStopAll,
+                                   emptyText = 'No live sessions', offline = false } = {}) {
+  if (offline) {
+    return h('div', { class: 'ds-dash-state ds-dash-state-error', role: 'status' }, 'Backend offline — live sessions unavailable');
+  }
+  if (!sessions.length) {
+    return h('div', { class: 'ds-dash-state', role: 'status' }, emptyText);
+  }
+  const header = h('div', { class: 'ds-dash-header', role: 'group', 'aria-label': 'live session controls' },
+    h('span', { class: 'ds-dash-count', role: 'status', 'aria-live': 'polite' },
+      sessions.length + ' running'),
+    onStopAll ? Btn({ key: 'stopall', danger: true, onClick: () => onStopAll(sessions), children: 'stop all' }) : null);
+  const grid = h('div', { class: 'ds-dash-grid', role: 'list', 'aria-label': 'live sessions' },
+    ...sessions.map((s) => h('div', { key: s.sid, role: 'listitem' },
+      SessionCard({ session: s, onStop, onOpen, onResume, onView }))));
+  return h('div', { class: 'ds-dash' }, header, grid);
+}