anentrypoint-design 0.0.424 → 0.0.426

package/src/components/context-pane/meter.js

@@ -0,0 +1,42 @@
+// ContextMeter — horizontal meter bar showing proportional colored segments
+// of token usage (e.g. system/user/assistant) against a total, plus a
+// remaining-capacity sliver. Token-styled: each segment's color is a CSS
+// custom property set inline (the one runtime-value exception the inline-
+// style ban already carves out for percentage widths elsewhere in this kit,
+// e.g. BarRow/BarChart's --bar-pct), the palette itself lives in
+// context-pane.css as semantic classes, never a raw hex per segment.
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+const h = webjsx.createElement;
+
+// ContextMeter({ used, total, segments })
+//   used     : tokens consumed so far (number).
+//   total    : total budget (number) — the meter's 100%.
+//   segments : [{ label, value, tone }] — tone is a semantic class suffix
+//              ('system'|'user'|'assistant'|'other'); values need not sum to
+//              `used` exactly but are clamped to the remaining budget.
+export function ContextMeter({ used = 0, total = 0, segments = [] } = {}) {
+    const safeTotal = total > 0 ? total : 1;
+    let acc = 0;
+    const bars = segments.map((seg, i) => {
+        const val = Math.max(0, Number(seg.value) || 0);
+        const pct = Math.max(0, Math.min(100, (val / safeTotal) * 100));
+        acc += val;
+        return h('span', {
+            key: seg.id || i,
+            class: 'ds-context-meter-seg ds-context-meter-seg-' + (seg.tone || 'other'),
+            style: `width:${pct}%`,
+            title: `${seg.label || 'segment'}: ${val}`,
+        });
+    });
+    const usedPct = Math.max(0, Math.min(100, (used / safeTotal) * 100));
+    return h('div', { class: 'ds-context-meter' },
+        h('div', {
+            class: 'ds-context-meter-track', role: 'meter',
+            'aria-label': 'context usage', 'aria-valuenow': String(used),
+            'aria-valuemin': '0', 'aria-valuemax': String(total),
+        }, ...bars),
+        h('div', { class: 'ds-context-meter-foot' },
+            h('span', {}, `${used.toLocaleString()} / ${total.toLocaleString()} tokens`),
+            h('span', {}, `${Math.round(usedPct)}%`)));
+}

package/src/components/context-pane/pane.js

@@ -0,0 +1,127 @@
+// 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 whole-conversation totals { turns, cost } shown as a block
+//   recentFiles: OPTIONAL [{ path, time }] files touched by tool calls this
+//                session (most-recent first), rendered as a compact panel -
+//                Claude Desktop's context surfaces recently-touched files.
+//   onSetCwd   : optional callback for the "set working directory" affordance
+//   onOpenFile : optional callback(path) for clicking a recent-files row
+//
+// 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';
+import { fmtDuration } from '../sessions.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, recentFiles, onSetCwd, onOpenFile } = {}) {
+    const running = Number(toolCount) > 0;
+    const hasUsage = usage && (usage.inputTokens != null || usage.outputTokens != null || usage.costUsd != null);
+    const hasSession = session && (session.turns != null || session.cost != null);
+    // Empty state: before an agent is picked AND with no usage/session, four
+    // placeholder rows (agent: none / model: dash / ...) read as a dead panel.
+    // Show one honest line instead.
+    if (!agent && !hasUsage && !hasSession && !cwd) {
+        return h('div', { class: 'ds-context' },
+            h('div', { class: 'ds-context-empty', role: 'status' },
+                'No active conversation — start a chat to see context here'),
+            onSetCwd ? h('div', { class: 'ds-context-actions' }, Btn({ onClick: onSetCwd, children: 'set working dir' })) : null);
+    }
+    // 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 || '—' }),
+                // Wrapped in a scoping div (`ds-context-cwd-row`) so the cwd
+                // fact's `.sub` text can be styled monospace to match
+                // .ds-dash-cwd/.ds-session-agent/.ds-dash-model without
+                // affecting every other Row's `.sub` in the app.
+                h('div', { class: 'ds-context-cwd-row' }, 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,
+                    // The change-cwd affordance belongs ON the working-dir fact,
+                    // not as a button floating under the panels.
+                    onClick: onSetCwd || undefined,
+                    meta: onSetCwd ? 'change' : undefined,
+                })),
+                Row({
+                    title: 'running tools',
+                    meta: running ? String(toolCount) : 'idle',
+                    rail: running ? 'purple' : null,
+                }),
+            ],
+        }),
+    ];
+    // Conversation block: whole-session totals (turn count + accumulated cost)
+    // between the context panel and the per-turn usage panel. All-zero totals
+    // are noise, not context - hide the block until there is a conversation.
+    // Rendered as a lighter fact group (no card chrome) since it's 1-2 short
+    // facts, not enough weight to justify a full bordered Panel.
+    if (hasSession && (Number(session.turns) > 0 || Number(session.cost) > 0)) {
+        const sesRows = [];
+        if (session.turns != null) sesRows.push(Row({ title: 'turns', meta: String(session.turns) }));
+        if (session.cost != null) sesRows.push(Row({ title: 'total cost', meta: '$' + Number(session.cost).toFixed(4) }));
+        panels.push(h('div', { class: 'ds-context-group' },
+            h('div', { class: 'ds-context-group-label' }, 'conversation'),
+            ...sesRows));
+    }
+    // Usage block: surface the last turn's token/cost/turn/duration so the
+    // result event is no longer silently dropped. Lighter fact group, not a
+    // full Panel - same reasoning as the conversation block above.
+    if (hasUsage) {
+        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) }));
+        // One duration vocabulary kit-wide: shared fmtDuration (s -> m -> h).
+        if (usage.durationMs != null) tokRows.push(Row({ title: 'duration', meta: fmtDuration(usage.durationMs) }));
+        panels.push(h('div', { class: 'ds-context-group' },
+            h('div', { class: 'ds-context-group-label' }, 'last turn'),
+            ...tokRows));
+    }
+    // Recent files: files touched by tool calls this session, most-recent
+    // first, capped to 5 rows so the panel stays a glance not a log. Lighter
+    // fact group, not a full Panel - same reasoning as above.
+    if (Array.isArray(recentFiles) && recentFiles.length) {
+        const fileRows = recentFiles.slice(0, 5).map((f) => Row({
+            title: f.path.split(/[/\\]/).filter(Boolean).pop() || f.path,
+            sub: f.path,
+            meta: f.time || undefined,
+            onClick: onOpenFile ? () => onOpenFile(f.path) : undefined,
+        }));
+        panels.push(h('div', { class: 'ds-context-group' },
+            h('div', { class: 'ds-context-group-label' }, 'recent files'),
+            ...fileRows));
+    }
+    // The cwd action lives on the working-dir row above; no floating footer button.
+    return h('div', { class: 'ds-context' }, ...panels);
+}

package/src/components/context-pane/treemap.js

@@ -0,0 +1,81 @@
+// ContextTreemap — squarified-treemap SVG layout for a token/cost breakdown,
+// nested rectangles sized by value. Raw SVG, no charting library — the only
+// reusable precedent in this kit is charts.js's Sparkline, which maps values
+// to a single polyline (no area-layout code to build on), so the squarified
+// algorithm here is self-contained. Token-stroke/fill only, same convention
+// as Sparkline/BarChart in content/charts.js.
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+const h = webjsx.createElement;
+
+// squarify(items, x, y, w, h) -> [{ item, x, y, w, h }]
+// Classic squarified treemap (Bruls/Huizing/Wijk): lays out `items` (each
+// with a numeric `.value`) into the x/y/w/h rect, recursively slicing off
+// rows that keep aspect ratios closest to 1.
+function worstRatio(row, len, totalArea) {
+    const sum = row.reduce((s, v) => s + v, 0);
+    if (sum === 0) return Infinity;
+    const rowLenSq = len * len, sumSq = sum * sum;
+    let worst = 0;
+    for (const v of row) {
+        const r = Math.max((rowLenSq * v) / sumSq, sumSq / (rowLenSq * v));
+        if (r > worst) worst = r;
+    }
+    return worst;
+}
+
+export function squarify(items, x, y, w, h) {
+    const values = items.map((it) => Math.max(0, Number(it.value) || 0));
+    const total = values.reduce((s, v) => s + v, 0);
+    if (!items.length || total <= 0) return [];
+    const scale = (w * h) / total;
+    const scaled = values.map((v) => v * scale);
+    const out = [];
+    let idx = 0, rx = x, ry = y, rw = w, rh = h;
+    while (idx < items.length) {
+        const horizontal = rw >= rh;
+        const len = horizontal ? rh : rw;
+        let row = [scaled[idx]], rowItems = [idx];
+        let i = idx + 1;
+        while (i < scaled.length) {
+            const trial = [...row, scaled[i]];
+            if (worstRatio(trial, len, 0) <= worstRatio(row, len, 0)) { row = trial; rowItems.push(i); i++; }
+            else break;
+        }
+        const rowSum = row.reduce((s, v) => s + v, 0);
+        const thickness = len > 0 ? rowSum / len : 0;
+        let cursor = horizontal ? ry : rx;
+        rowItems.forEach((itemIdx, k) => {
+            const size = len > 0 ? row[k] / thickness : 0;
+            const rect = horizontal
+                ? { x: rx, y: cursor, w: thickness, h: size }
+                : { x: cursor, y: ry, w: size, h: thickness };
+            out.push({ item: items[itemIdx], ...rect });
+            cursor += size;
+        });
+        if (horizontal) { rx += thickness; rw -= thickness; }
+        else { ry += thickness; rh -= thickness; }
+        idx = i;
+    }
+    return out;
+}
+
+// ContextTreemap({ items, width=280, height=160 })
+//   items: [{ id, label, value, tone }] — tone is a semantic class suffix,
+//   same vocabulary as ContextMeter's segment tone.
+export function ContextTreemap({ items = [], width = 280, height = 160 } = {}) {
+    const rects = squarify(items, 0, 0, width, height);
+    if (!rects.length) return h('div', { class: 'ds-context-treemap-empty' }, 'no breakdown yet');
+    return h('svg', {
+        class: 'ds-context-treemap', viewBox: `0 0 ${width} ${height}`, width, height,
+        role: 'img', 'aria-label': 'context breakdown treemap',
+    },
+        ...rects.map((r, i) => h('g', { key: r.item.id || i },
+            h('rect', {
+                x: r.x.toFixed(1), y: r.y.toFixed(1), width: Math.max(0, r.w - 1).toFixed(1), height: Math.max(0, r.h - 1).toFixed(1),
+                class: 'ds-context-treemap-rect ds-context-treemap-rect-' + (r.item.tone || 'other'),
+            }),
+            r.w > 40 && r.h > 18
+                ? h('text', { x: (r.x + 4).toFixed(1), y: (r.y + 14).toFixed(1), class: 'ds-context-treemap-label' }, r.item.label)
+                : h('title', {}, `${r.item.label}: ${r.item.value}`))));
+}

package/src/components/context-pane/xray.js

@@ -0,0 +1,30 @@
+// ContextXRayPanel — per-segment expandable/collapsible breakdown list.
+// Reuses editor-primitives/collapse.js's CollapseGroup for the actual
+// expand/collapse behavior (single-open-at-a-time accordion) rather than
+// reimplementing that state machine; this module only supplies the
+// segment-row content (label, value, sub-items) that goes inside each
+// Collapse body.
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+import { CollapseGroup } from '../editor-primitives/collapse.js';
+const h = webjsx.createElement;
+
+// ContextXRayPanel({ segments, openId, onOpenIdChange })
+//   segments: [{ id, label, value, tone, items: [{ label, value }] }]
+//   openId/onOpenIdChange: accordion state, forwarded straight to CollapseGroup.
+export function ContextXRayPanel({ segments = [], openId, onOpenIdChange } = {}) {
+    if (!segments.length) return h('div', { class: 'ds-context-xray-empty' }, 'no segments yet');
+    const items = segments.map((seg) => ({
+        id: seg.id,
+        title: h('span', { class: 'ds-context-xray-head' },
+            h('span', { class: 'ds-context-xray-dot ds-context-xray-dot-' + (seg.tone || 'other') }),
+            h('span', { class: 'ds-context-xray-label' }, seg.label),
+            h('span', { class: 'ds-context-xray-value' }, String(seg.value))),
+        children: h('div', { class: 'ds-context-xray-body' },
+            ...(seg.items || []).map((it, i) => h('div', { key: i, class: 'ds-context-xray-row' },
+                h('span', {}, it.label),
+                h('span', {}, String(it.value))))),
+    }));
+    return h('div', { class: 'ds-context-xray' },
+        CollapseGroup({ items, openId, onOpenChange: onOpenIdChange, accordion: true }));
+}

package/src/components/context-pane.js

@@ -1,127 +1,12 @@
-// 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 whole-conversation totals { turns, cost } shown as a block
-//   recentFiles: OPTIONAL [{ path, time }] files touched by tool calls this
-//                session (most-recent first), rendered as a compact panel -
-//                Claude Desktop's context surfaces recently-touched files.
-//   onSetCwd   : optional callback for the "set working directory" affordance
-//   onOpenFile : optional callback(path) for clicking a recent-files row
-//
-// 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';
-import { fmtDuration } from './sessions.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, recentFiles, onSetCwd, onOpenFile } = {}) {
-    const running = Number(toolCount) > 0;
-    const hasUsage = usage && (usage.inputTokens != null || usage.outputTokens != null || usage.costUsd != null);
-    const hasSession = session && (session.turns != null || session.cost != null);
-    // Empty state: before an agent is picked AND with no usage/session, four
-    // placeholder rows (agent: none / model: dash / ...) read as a dead panel.
-    // Show one honest line instead.
-    if (!agent && !hasUsage && !hasSession && !cwd) {
-        return h('div', { class: 'ds-context' },
-            h('div', { class: 'ds-context-empty', role: 'status' },
-                'No active conversation — start a chat to see context here'),
-            onSetCwd ? h('div', { class: 'ds-context-actions' }, Btn({ onClick: onSetCwd, children: 'set working dir' })) : null);
-    }
-    // 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 || '—' }),
-                // Wrapped in a scoping div (`ds-context-cwd-row`) so the cwd
-                // fact's `.sub` text can be styled monospace to match
-                // .ds-dash-cwd/.ds-session-agent/.ds-dash-model without
-                // affecting every other Row's `.sub` in the app.
-                h('div', { class: 'ds-context-cwd-row' }, 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,
-                    // The change-cwd affordance belongs ON the working-dir fact,
-                    // not as a button floating under the panels.
-                    onClick: onSetCwd || undefined,
-                    meta: onSetCwd ? 'change' : undefined,
-                })),
-                Row({
-                    title: 'running tools',
-                    meta: running ? String(toolCount) : 'idle',
-                    rail: running ? 'purple' : null,
-                }),
-            ],
-        }),
-    ];
-    // Conversation block: whole-session totals (turn count + accumulated cost)
-    // between the context panel and the per-turn usage panel. All-zero totals
-    // are noise, not context - hide the block until there is a conversation.
-    // Rendered as a lighter fact group (no card chrome) since it's 1-2 short
-    // facts, not enough weight to justify a full bordered Panel.
-    if (hasSession && (Number(session.turns) > 0 || Number(session.cost) > 0)) {
-        const sesRows = [];
-        if (session.turns != null) sesRows.push(Row({ title: 'turns', meta: String(session.turns) }));
-        if (session.cost != null) sesRows.push(Row({ title: 'total cost', meta: '$' + Number(session.cost).toFixed(4) }));
-        panels.push(h('div', { class: 'ds-context-group' },
-            h('div', { class: 'ds-context-group-label' }, 'conversation'),
-            ...sesRows));
-    }
-    // Usage block: surface the last turn's token/cost/turn/duration so the
-    // result event is no longer silently dropped. Lighter fact group, not a
-    // full Panel - same reasoning as the conversation block above.
-    if (hasUsage) {
-        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) }));
-        // One duration vocabulary kit-wide: shared fmtDuration (s -> m -> h).
-        if (usage.durationMs != null) tokRows.push(Row({ title: 'duration', meta: fmtDuration(usage.durationMs) }));
-        panels.push(h('div', { class: 'ds-context-group' },
-            h('div', { class: 'ds-context-group-label' }, 'last turn'),
-            ...tokRows));
-    }
-    // Recent files: files touched by tool calls this session, most-recent
-    // first, capped to 5 rows so the panel stays a glance not a log. Lighter
-    // fact group, not a full Panel - same reasoning as above.
-    if (Array.isArray(recentFiles) && recentFiles.length) {
-        const fileRows = recentFiles.slice(0, 5).map((f) => Row({
-            title: f.path.split(/[/\\]/).filter(Boolean).pop() || f.path,
-            sub: f.path,
-            meta: f.time || undefined,
-            onClick: onOpenFile ? () => onOpenFile(f.path) : undefined,
-        }));
-        panels.push(h('div', { class: 'ds-context-group' },
-            h('div', { class: 'ds-context-group-label' }, 'recent files'),
-            ...fileRows));
-    }
-    // The cwd action lives on the working-dir row above; no floating footer button.
-    return h('div', { class: 'ds-context' }, ...panels);
-}
+// context-pane barrel — thin barrel over ./context-pane/*.js. ContextPane's
+// public export name/shape is unchanged for existing consumers; ContextMeter,
+// ContextTreemap (+ its squarify layout helper) and ContextXRayPanel are new
+// additions living in their own single-responsibility submodules alongside
+// it, split out purely to respect the 200-line module cap.
+
+import { ContextPane } from './context-pane/pane.js';
+import { ContextMeter } from './context-pane/meter.js';
+import { ContextTreemap, squarify } from './context-pane/treemap.js';
+import { ContextXRayPanel } from './context-pane/xray.js';
+
+export { ContextPane, ContextMeter, ContextTreemap, squarify, ContextXRayPanel };

package/src/components/data-density/progress.js

@@ -0,0 +1,20 @@
+// Progress — plain value/max progress bar. Sibling module of data-density.js
+// (kept separate purely to respect the 200-line module cap, not a
+// barrel-over-submodules split of the whole group): the percentage-width
+// bar-fill approach is the same one BarRow uses in data-density.js, just
+// without BarRow's label/meta column chrome — track + fill only.
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+const h = webjsx.createElement;
+
+export function Progress({ value = 0, max = 100, label } = {}) {
+    const pct = max > 0 ? Math.max(0, Math.min(100, (value / max) * 100)) : 0;
+    return h('div', {
+        class: 'ds-progress', role: 'progressbar',
+        'aria-valuenow': String(value), 'aria-valuemin': '0', 'aria-valuemax': String(max),
+        'aria-label': label != null ? String(label) : 'progress',
+    },
+        label ? h('span', { class: 'ds-progress-label' }, label) : null,
+        h('div', { class: 'ds-progress-track' },
+            h('div', { class: 'ds-progress-fill', style: `width:${pct}%` })));
+}

package/src/components/data-density.js

@@ -8,8 +8,11 @@
 
 import * as webjsx from '../../vendor/webjsx/index.js';
 import { Pill } from './shell.js';
+import { Progress } from './data-density/progress.js';
 const h = webjsx.createElement;
 
+export { Progress };
+
 // ---------------------------------------------------------------------------
 // PhaseWalk — compact horizontal phase-progress indicator.
 //   phases  : ordered phase names (default the 5-stage gm chain).

package/src/components/editor-primitives/layout.js

@@ -87,3 +87,15 @@ export function Divider({ label, vertical = false, key } = {}) {
     return h('div', { key, class: 'ds-ep-divider ds-ep-divider-labeled', role: 'separator' },
         h('span', { class: 'ds-ep-divider-label' }, label));
 }
+
+// ---------------------------------------------------------------------------
+// AspectRatio — thin wrapper over the `.ds-aspect` CSS utility (app-shell's
+// base.css), matching Divider's own trivial-CSS-only-primitive-still-gets-a-
+// factory convention. `ratio` accepts a CSS ratio string ('1/1', '16/9') or
+// a number (interpreted as width/height); falls back to the utility's own
+// 16/9 default when omitted.
+// ---------------------------------------------------------------------------
+export function AspectRatio({ ratio, children, key } = {}) {
+    const cssRatio = typeof ratio === 'number' ? `${ratio} / 1` : ratio;
+    return h('div', { key, class: 'ds-aspect', style: cssRatio ? `--aspect:${cssRatio}` : null }, children);
+}

package/src/components/editor-primitives.js

@@ -11,7 +11,7 @@
 import { Toolbar, ToolbarRow, Tabs, IconButtonGroup } from './editor-primitives/chrome.js';
 import { TreeView, TreeItem } from './editor-primitives/tree.js';
 import { PropertyGrid, PropertyField, PropertyGridRow, InlineEditableField } from './editor-primitives/property-grid.js';
-import { Dock, BP_SM, BP_MD, BP_LG, BP_XL, useMediaQuery, Grid, GridItem, Divider } from './editor-primitives/layout.js';
+import { Dock, BP_SM, BP_MD, BP_LG, BP_XL, useMediaQuery, Grid, GridItem, Divider, AspectRatio } from './editor-primitives/layout.js';
 import { ResizeHandle, SplitPanel } from './editor-primitives/split-panel.js';
 import { Collapse, CollapseGroup } from './editor-primitives/collapse.js';
 import { FocusTrap } from './editor-primitives/focus-trap.js';
@@ -27,7 +27,7 @@ export {
     Toolbar, ToolbarRow, Tabs, IconButtonGroup,
     TreeView, TreeItem,
     PropertyGrid, PropertyField, PropertyGridRow, InlineEditableField,
-    Dock, BP_SM, BP_MD, BP_LG, BP_XL, useMediaQuery, Grid, GridItem, Divider,
+    Dock, BP_SM, BP_MD, BP_LG, BP_XL, useMediaQuery, Grid, GridItem, Divider, AspectRatio,
     ResizeHandle, SplitPanel,
     Collapse, CollapseGroup,
     FocusTrap,

package/src/components/overlay-primitives/hover-card.js

@@ -0,0 +1,60 @@
+// HoverCard — Popover composed with a delayed hover trigger. Wraps `trigger`
+// in a span with pointerenter/pointerleave listeners that manage open state
+// via a pair of setTimeout delays (open delay on enter, close delay on
+// leave), clearing any pending timer before scheduling a new one so a quick
+// re-enter cancels a pending close. Popover itself is controlled — this
+// component owns the open/close timers and calls back into the caller so the
+// caller can hold `open` in state (same controlled-component pattern as
+// every other overlay in this group).
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+import { Popover } from './popover.js';
+import { kids } from './floating.js';
+const h = webjsx.createElement;
+
+const _timers = new WeakMap();
+
+function _clear(el) {
+    const t = _timers.get(el);
+    if (t) { clearTimeout(t.open); clearTimeout(t.close); }
+}
+
+// HoverCard({ trigger, content, open, onOpenChange, openDelay=700, closeDelay=300, placement, ariaLabel })
+//   trigger      : a single webjsx VElement (e.g. a link or button) — the hover target.
+//   content      : Popover children (rendered only while open).
+//   open         : caller-owned boolean — HoverCard schedules onOpenChange(true/false)
+//                  via the hover timers rather than holding its own state.
+//   onOpenChange : callback(nextOpen) — required to actually see the card open.
+// The wrapper span itself doubles as the Popover anchor element. Popover is
+// imperative (it owns a WeakMap keyed on anchorEl and creates/tears down its
+// own body-level node outside the webjsx diff), so it is invoked from the
+// anchor's ref callback via queueMicrotask rather than inline during this
+// declarative render pass — mirrors CommandPalette/EmojiPicker's own
+// ref-then-queueMicrotask imperative-child pattern in this same group.
+export function HoverCard({ trigger, content, open, onOpenChange, openDelay = 700, closeDelay = 300, placement = 'top', ariaLabel } = {}) {
+    const child = kids(trigger)[0];
+    if (!child) return null;
+    const schedule = (el, kind, ms) => {
+        _clear(el);
+        const timers = _timers.get(el) || {};
+        if (kind === 'open') timers.open = setTimeout(() => onOpenChange && onOpenChange(true), ms);
+        else timers.close = setTimeout(() => onOpenChange && onOpenChange(false), ms);
+        _timers.set(el, timers);
+    };
+    const runPopover = (el) => Popover({
+        open: Boolean(open), anchorEl: el, onClose: () => onOpenChange && onOpenChange(false),
+        placement, ariaLabel, children: content,
+    });
+    const anchorRef = (el) => {
+        if (!el) return;
+        queueMicrotask(() => runPopover(el));
+        if (el._dsHoverCard) return;
+        el._dsHoverCard = true;
+        el.addEventListener('pointerenter', () => schedule(el, 'open', openDelay));
+        el.addEventListener('pointerleave', () => schedule(el, 'close', closeDelay));
+        el.addEventListener('focusin', () => schedule(el, 'open', openDelay));
+        el.addEventListener('focusout', () => schedule(el, 'close', closeDelay));
+    };
+    return h('span', { class: 'ds-hovercard', ref: anchorRef },
+        webjsx.createElement(child.type, { ...(child.props || {}) }, ...(child.children || [])));
+}

package/src/components/overlay-primitives/menubar.js

@@ -0,0 +1,65 @@
+// Menubar — a horizontal row of Dropdown-style menus (built on the same
+// useRovingMenu state machine that ./menus.js's Dropdown uses) sharing
+// cross-menu-hover-switch state. Dropdown itself keeps its open/close state
+// private (no onOpenChange prop), so a true hover-driven switch — closing
+// whichever menu is open and opening the one now under the pointer, without
+// a second click — needs the shared state machine directly rather than a
+// black-box Dropdown instance per item; each trigger still renders the exact
+// role=menu / .ds-dropdown-item DOM Dropdown itself builds, so it is visually
+// and semantically identical to a row of Dropdowns.
+//
+// Controlled component: the caller owns `openIndex`/`onOpenIndexChange`
+// (which menu, if any, is open), matching the rest of this overlay group.
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+import { useRovingMenu } from './roving-menu.js';
+const h = webjsx.createElement;
+
+function buildMenuEl(items, onSelect, close, ariaLabel) {
+    const el = document.createElement('div');
+    el.className = 'ds-popover ds-dropdown-menu';
+    el.setAttribute('role', 'menu');
+    if (ariaLabel) el.setAttribute('aria-label', ariaLabel);
+    const select = (it) => { if (it.disabled || it.separator) return; if (onSelect) onSelect(it.id, it); close(); };
+    const tree = h('div', { class: 'ds-dropdown-list' },
+        ...items.map((it, i) => it.separator
+            ? h('div', { key: 'sep' + i, class: 'ds-dropdown-separator', role: 'separator' })
+            : h('button', {
+                key: it.id || i, type: 'button', role: 'menuitem',
+                class: 'ds-dropdown-item' + (it.danger ? ' is-danger' : ''),
+                'aria-disabled': it.disabled ? 'true' : 'false',
+                tabindex: '-1', onclick: () => select(it),
+            }, h('span', { class: 'ds-dropdown-label' }, it.label))));
+    webjsx.applyDiff(el, tree);
+    return el;
+}
+
+// Menubar({ menus, openIndex, onOpenIndexChange })
+//   menus: [{ id?, label, items, onSelect }].
+//   openIndex: caller-owned index of the currently open menu, or null.
+//   onOpenIndexChange(next): called with the new open index (or null on close).
+export function Menubar({ menus = [], openIndex = null, onOpenIndexChange, ariaLabel = 'Menu bar' } = {}) {
+    return h('div', { class: 'ds-menubar', role: 'menubar', 'aria-label': ariaLabel },
+        ...menus.map((menu, i) => {
+            const isOpen = openIndex === i;
+            const roving = useRovingMenu({
+                itemSelector: '[role="menuitem"]:not([aria-disabled="true"])',
+                items: menu.items || [], typeahead: true, placement: 'bottom-start',
+                onOpenChange: (open) => onOpenIndexChange && onOpenIndexChange(open ? i : null),
+            });
+            const open = () => roving.openMenu(() => buildMenuEl(menu.items || [], menu.onSelect, roving.close, menu.label), true);
+            const onTrigClick = () => { if (roving.isOpen()) roving.close(); else open(); };
+            const onTrigKey = (e) => { if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') { e.preventDefault(); if (!roving.isOpen()) open(); else roving.focusItem(0); } };
+            // Cross-menu hover switch: only steal focus when a DIFFERENT menu
+            // is already open — plain hover with nothing open still requires
+            // a click, matching standard menubar behavior.
+            const onEnter = () => { if (openIndex != null && openIndex !== i && !roving.isOpen()) open(); };
+            const refFn = roving.refFn('_dsMenubarTrig');
+            const wireRef = (el) => { refFn(el); if (el) { el.addEventListener('click', onTrigClick); el.addEventListener('keydown', onTrigKey); } };
+            return h('div', { key: menu.id || i, class: 'ds-menubar-item', onpointerenter: onEnter },
+                h('button', {
+                    type: 'button', class: 'ds-menubar-trigger' + (isOpen ? ' is-open' : ''),
+                    role: 'menuitem', ref: wireRef,
+                }, menu.label));
+        }));
+}

package/src/components/overlay-primitives.js

@@ -21,6 +21,8 @@ import { EmojiPicker } from './overlay-primitives/emoji-picker.js';
 import { SettingsPopover } from './overlay-primitives/settings-popover.js';
 import { AuthModal } from './overlay-primitives/auth-modal.js';
 import { BootOverlay, VideoLightbox } from './overlay-primitives/full-screen.js';
+import { HoverCard } from './overlay-primitives/hover-card.js';
+import { Menubar } from './overlay-primitives/menubar.js';
 
 export {
     useFloating, useLongPress, withBusy, trapTab,
@@ -34,4 +36,6 @@ export {
     SettingsPopover,
     AuthModal,
     BootOverlay, VideoLightbox,
+    HoverCard,
+    Menubar,
 };