@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/client/components/common/provider-icon/index.test.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The ink the provider marks are painted in.
+ *
+ * Almost every source art (`anthropic`, `openai`, `deepseek`, `google`, …) is
+ * drawn with NO paint attribute at all and relies on the SVG default — which is
+ * BLACK, not the surrounding ink. The table therefore cannot carry the fix (its
+ * entries are inner markup only), and the `<svg>` this component owns has to
+ * declare `fill="currentColor"`; `fill` is an inherited property, so that one
+ * attribute reaches every descendant that does not set its own paint.
+ *
+ * Without it the marks are black on every theme, which is invisible only on a
+ * dark canvas and so went unnoticed for the app's whole life: measured on the
+ * rendered Kabmo, a mark over `aura-dark`'s panel (#201E2B) composited to
+ * `rgb(0,0,0)` — contrast 1.28:1 — while the same mark under this component
+ * paints in the palette's ink (contrast 5.88:1).
+ *
+ * Rendered with `h()` (no JSX) against happy-dom, following `PluginMark`.
+ */
+
+import { afterAll, afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import type { ComponentChild } from 'preact';
+import { act } from 'preact/test-utils';
+import { ProviderIcon } from '@/client/components/common/provider-icon';
+import { PROVIDER_GLYPHS } from '@/client/components/common/provider-icon/glyphs';
+
+const DOM_GLOBALS = ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event'] as const;
+/** The runner's own globals, restored on teardown — deleting them would strip
+ *  natives (Event/CustomEvent) every later file needs. */
+const nativeGlobals: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+
+let container: HTMLElement;
+
+// Installed per CASE, not per file: another suite's teardown can strip `window`
+// mid-file when the runner interleaves files.
+beforeEach(() => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in nativeGlobals)) nativeGlobals[key] = win[key as keyof Window];
+    target[key] = win[key as keyof Window];
+  }
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  render(null, container);
+  container.remove();
+});
+
+afterAll(() => {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (key in nativeGlobals) target[key] = nativeGlobals[key];
+    else delete target[key];
+  }
+});
+
+function paint(node: ComponentChild): HTMLElement {
+  act(() => {
+    render(node, container);
+  });
+  return container;
+}
+
+describe('ProviderIcon ink', () => {
+  test('a mark is painted in the surrounding ink, never the SVG default black', () => {
+    const svg = paint(h(ProviderIcon, { slug: 'deepseek', name: 'DeepSeek' })).querySelector('svg');
+
+    expect(svg).not.toBeNull();
+    // The glyph body carries no paint of its own (`glyphs.test.ts` pins that),
+    // so this attribute is the only thing keeping the mark off black.
+    expect(svg?.getAttribute('fill')).toBe('currentColor');
+  });
+
+  test('every glyph in the table resolves to that ink', () => {
+    for (const [name, glyph] of Object.entries(PROVIDER_GLYPHS)) {
+      const el = paint(h(ProviderIcon, { slug: name }));
+      const svg = el.querySelector('svg');
+      expect(svg, `${name} must draw an svg`).not.toBeNull();
+      expect(svg?.getAttribute('fill'), `${name} ink`).toBe('currentColor');
+      expect(svg?.getAttribute('viewBox'), `${name} box`).toBe(glyph.viewBox);
+    }
+  });
+
+  test('the size and the caller class ride on the svg, not the inner markup', () => {
+    const svg = paint(h(ProviderIcon, { slug: 'openai', size: 20, className: 'shrink-0' })).querySelector('svg');
+
+    expect(svg?.getAttribute('width')).toBe('20');
+    expect(svg?.getAttribute('height')).toBe('20');
+    expect(svg?.getAttribute('class')).toContain('shrink-0');
+  });
+
+  test('a provider with no mark keeps its initials instead of an empty box', () => {
+    const el = paint(h(ProviderIcon, { slug: 'definitely-not-a-provider', name: 'Toktok ID' }));
+
+    expect(el.querySelector('svg')).toBeNull();
+    expect(el.textContent).toBe('ti.');
+  });
+});

package/src/client/components/common/provider-icon/index.tsx

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The brand mark for a provider, or its initials when no mark is registered.
+ *
+ * Every provider surface draws through this one component — the settings
+ * sidebar, the provider header, the login/reconnect modals, the "add provider"
+ * preset list, the composer's model picker and the usage panel — so a provider
+ * cannot be a whale emoji in one place and a generic cloud in another.
+ *
+ * Resolution order is the `providerIcon` slot's contract: a plugin's registered
+ * mark for a provider wins over the built-in table, and only for the provider it
+ * names ({@link resolveProviderMark}). Because there is one component, there is
+ * one place that order lives.
+ *
+ * The mark is painted in `currentColor`, so it takes the surrounding ink and
+ * follows the theme. That is deliberate: the app's palette is a monochrome
+ * paper/ink system (`DESIGN.md`), and a full-colour logo per row would be the
+ * only chroma in a dense list. Brand identity is carried by the shape.
+ *
+ * Fallback rule: a provider with no registered mark shows its initials, each
+ * followed by a dot — `Tooker` -> `t.`, `Toktok ID` -> `ti.`
+ * ({@link providerInitials}). A provider that is not in the table still gets a
+ * stable, readable badge rather than an empty box.
+ */
+
+import type { ProviderIconRegistration } from '@kabmo-labs/kabmo-sdk';
+import { resolveProviderMark } from '@/client/components/common/provider-icon/resolve';
+import { useListSlotRows } from '@/client/hooks/workspace/list-slots';
+import { providerInitials } from '@/shared/lib/models/provider/glyph';
+
+interface ProviderIconProps {
+  /**
+   * The provider row's stored icon key (`ProviderItem.icon`). Tried first, so a
+   * legacy key keeps resolving after the provider's slug changes.
+   */
+  icon?: string;
+  /** The provider slug — the primary brand key. */
+  slug?: string;
+  /** Display name; only the initials fallback reads it. */
+  name?: string;
+  size?: number;
+  className?: string;
+}
+
+export function ProviderIcon({ icon, slug, name, size = 16, className = '' }: ProviderIconProps) {
+  // The ONE resolution point: a plugin's `providerIcon` registration for this
+  // provider wins over the built-in table, and any other provider is untouched.
+  // Read reactively, so a bundle that registers after this icon mounted still
+  // reaches it — the same contract every other list slot has.
+  const registered = useListSlotRows<ProviderIconRegistration>('providerIcon');
+  const glyph = resolveProviderMark([icon, slug, name], registered);
+
+  if (!glyph) {
+    // No mark: the initials badge. It is a PILL, not a square — the text has to
+    // sit at the same visual weight as a brand mark, and `ti.` is far wider than
+    // it is tall, so a square column would force a font size half the height of
+    // its neighbours' ink (measured: `ti.` fits a 15px column only at 9.5px,
+    // whose glyph ink is 6.4px against the marks' 13.8px median). Height stays
+    // `size`, width follows the text.
+    //
+    // 1.2x is the largest size whose ink still lands inside the box (measured on
+    // canvas: ink 10-15px in a 16px band with >=1px clearance, versus clipping
+    // at 1.3x), and it brings the text level with the marks' ink.
+    // `aria-hidden` because the provider's name is always rendered beside it —
+    // a screen reader announcing "t." first is noise.
+    return (
+      <span
+        aria-hidden="true"
+        className={`inline-flex flex-shrink-0 items-center justify-center font-semibold lowercase leading-none ${className}`}
+        style={{ height: size, minWidth: size, paddingInline: Math.max(1, Math.round(size * 0.12)), fontSize: Math.round(size * 1.2) }}
+      >
+        {providerInitials(name || slug || icon || '')}
+      </span>
+    );
+  }
+
+  return (
+    <svg
+      viewBox={glyph.viewBox}
+      width={size}
+      height={size}
+      // The caller owns the ink, and it MUST be declared here. Most source
+      // marks (`anthropic`, `openai`, `deepseek`, …) are drawn with no paint
+      // attribute at all and rely on the SVG default, which is BLACK — so the
+      // mark stayed black on every theme and vanished against a dark canvas.
+      // `fill` is an inherited property, so declaring it on the root paints
+      // every descendant that does not set its own paint; the marks that DO
+      // carry their own attributes (`azure`'s `fill-opacity`, `synthetic`'s
+      // stroked outline, the baked `currentColor` paths) keep them.
+      fill="currentColor"
+      className={`flex-shrink-0 ${className}`}
+      aria-hidden="true"
+      focusable="false"
+      // A built-in body is bake-time data from this repo; a registered one is
+      // the plugin's own SVG source, reduced to its inner markup. Both are
+      // trusted the same way: a plugin's bundle already runs in this document.
+      dangerouslySetInnerHTML={{ __html: glyph.body }}
+    />
+  );
+}

package/src/client/components/common/provider-icon/resolve.test.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `providerIcon` slot's resolution order.
+ *
+ * These lock the two things a caller cannot see and a broken implementation
+ * would break silently: a plugin's registration must win for the provider it
+ * names and leave every other provider on its built-in mark, and a glyph that
+ * is not a usable SVG must fall through rather than leave an empty tile.
+ *
+ * `ProviderIcon` is the only caller, so the order is asserted here against the
+ * resolver it delegates to, without a DOM.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { parseRegisteredGlyph, resolveProviderMark } from '@/client/components/common/provider-icon/resolve';
+import { PROVIDER_GLYPHS } from '@/client/components/common/provider-icon/glyphs';
+import type { ListSlotEntry } from '@/client/lib/plugins/list-slots';
+import type { ProviderIconRegistration } from '@kabmo-labs/kabmo-sdk';
+
+const CUSTOM = '<svg viewBox="0 0 32 32"><path d="M4 4h24v24H4z"/></svg>';
+const OTHER = "<svg viewBox='0 0 10 10'><circle cx='5' cy='5' r='4'/></svg>";
+const MALFORMED = 'not an svg at all';
+
+function row(pluginId: string, provider: string, glyph: string, order?: number): ListSlotEntry<ProviderIconRegistration> {
+  return { pluginId, slot: 'providerIcon', registration: { id: provider, provider, glyph, order } };
+}
+
+describe('parseRegisteredGlyph', () => {
+  test('takes the root viewBox and the inner markup', () => {
+    expect(parseRegisteredGlyph(CUSTOM)).toEqual({
+      viewBox: '0 0 32 32',
+      body: '<path d="M4 4h24v24H4z"/>',
+    });
+  });
+
+  test('accepts a single-quoted viewBox and content before the root', () => {
+    expect(parseRegisteredGlyph(`<?xml version="1.0"?>${OTHER}`)).toEqual({
+      viewBox: '0 0 10 10',
+      body: "<circle cx='5' cy='5' r='4'/>",
+    });
+  });
+
+  test('refuses anything that is not one svg element with a viewBox and a body', () => {
+    expect(parseRegisteredGlyph(MALFORMED)).toBeNull();
+    expect(parseRegisteredGlyph('<svg viewBox="0 0 24 24">')).toBeNull();
+    expect(parseRegisteredGlyph('<svg viewBox="0 0 24 24"></svg>')).toBeNull();
+    expect(parseRegisteredGlyph('<svg><path d="M0 0h1v1z"/></svg>')).toBeNull();
+    expect(parseRegisteredGlyph('<svg viewBox="0 0 24 24"/>')).toBeNull();
+    expect(parseRegisteredGlyph('')).toBeNull();
+  });
+});
+
+describe('resolveProviderMark', () => {
+  test('a registered glyph wins over the built-in mark for that provider', () => {
+    const mark = resolveProviderMark(['deepseek'], [row('demo', 'deepseek', CUSTOM)]);
+
+    expect(mark).toEqual({ viewBox: '0 0 32 32', body: '<path d="M4 4h24v24H4z"/>' });
+  });
+
+  test('a registration leaves every other provider on its built-in mark', () => {
+    const rows = [row('demo', 'deepseek', CUSTOM)];
+
+    expect(resolveProviderMark(['openai'], rows)).toBe(PROVIDER_GLYPHS.openai);
+    expect(resolveProviderMark(['deepseek'], rows)).not.toBe(PROVIDER_GLYPHS.deepseek);
+  });
+
+  test('an unregistered provider is unchanged, unknown ones still fall to initials', () => {
+    expect(resolveProviderMark(['deepseek'], [])).toBe(PROVIDER_GLYPHS.deepseek);
+    expect(resolveProviderMark(['my-private-gateway'], [])).toBeNull();
+  });
+
+  test('the registration is found by every spelling the built-in table folds together', () => {
+    const rows = [row('demo', 'google-vertex', CUSTOM)];
+
+    for (const spelling of ['google-vertex', 'Google Vertex', 'GOOGLE_VERTEX', 'googlevertex ']) {
+      expect(resolveProviderMark([spelling], rows)?.viewBox, spelling).toBe('0 0 32 32');
+    }
+  });
+
+  test('candidates keep the built-in precedence: the icon key before the slug', () => {
+    const rows = [row('a', 'claude', CUSTOM), row('b', 'deepseek', OTHER)];
+
+    expect(resolveProviderMark(['claude', 'deepseek'], rows)?.viewBox).toBe('0 0 32 32');
+  });
+
+  test('two plugins on one provider: the first merged row wins, deterministically', () => {
+    const rows = [row('alpha', 'acme', CUSTOM), row('beta', 'acme', OTHER)];
+
+    expect(resolveProviderMark(['acme'], rows)?.viewBox).toBe('0 0 32 32');
+  });
+
+  test('a malformed glyph falls through instead of rendering a broken mark', () => {
+    // On a provider the built-in table knows, the built-in mark comes back.
+    expect(resolveProviderMark(['deepseek'], [row('demo', 'deepseek', MALFORMED)])).toBe(
+      PROVIDER_GLYPHS.deepseek,
+    );
+    // With no built-in either, there is nothing to draw and the badge runs.
+    expect(resolveProviderMark(['acme'], [row('demo', 'acme', MALFORMED)])).toBeNull();
+  });
+
+  test('the first registration is authoritative, so its broken glyph falls to the built-in', () => {
+    // The second plugin's glyph is valid, but `alpha` won the provider: the
+    // mark shown must not depend on which plugin shipped a broken string.
+    const rows = [row('alpha', 'acme', MALFORMED), row('beta', 'acme', CUSTOM)];
+
+    expect(resolveProviderMark(['acme'], rows)).toBeNull();
+  });
+});

package/src/client/components/common/provider-icon/resolve.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `providerIcon` slot's half of the provider-mark resolution.
+ *
+ * `ProviderIcon` is the ONE component every provider surface draws through, so
+ * this is the ONE place a plugin's mark can enter the app: registrations are
+ * resolved here, ahead of the built-in table, and nowhere else. A per-surface
+ * lookup would let one provider be a plugin's mark in Settings and a built-in
+ * one in the model picker.
+ *
+ * Two properties are load-bearing:
+ *
+ * - A registration affects ONLY the provider it names. Matching folds the
+ *   provider with the same rule the built-in table uses ({@link foldProviderKey}),
+ *   so `google-vertex`, `Google Vertex` and a legacy icon key all find a
+ *   registration, while an unmatched key falls through untouched.
+ * - A glyph that does not parse falls through to the built-in mark. The plugin
+ *   layer supplies raw SVG source, and a broken string must leave the provider
+ *   with its built-in mark rather than an empty tile.
+ */
+
+import type { ProviderIconRegistration } from '@kabmo-labs/kabmo-sdk';
+import type { ProviderGlyph } from '@/client/components/common/provider-icon/glyphs';
+import { PROVIDER_GLYPHS } from '@/client/components/common/provider-icon/glyphs';
+import type { ListSlotRows } from '@/client/lib/plugins/list-slots';
+import { foldProviderKey, resolveProviderGlyph } from '@/shared/lib/models/provider/glyph';
+
+/**
+ * The root `<svg>` of a plugin's glyph source: its opening tag and the index of
+ * the closing one. Null when the string is not one SVG element.
+ */
+function svgRoot(source: string): { attributes: string; bodyStart: number; bodyEnd: number } | null {
+  const open = /<svg\b([^>]*)>/i.exec(source);
+  if (!open) return null;
+  const bodyEnd = source.lastIndexOf('</svg>');
+  if (bodyEnd < 0) return null;
+  return { attributes: open[1], bodyStart: open.index + open[0].length, bodyEnd };
+}
+
+/**
+ * A plugin's `glyph` (a complete SVG source string) as the same
+ * `{ viewBox, body }` shape the built-in table holds, or null when it is not a
+ * usable SVG.
+ *
+ * Only the root's `viewBox` and its inner markup are taken: the host owns the
+ * `<svg>` element so the mark inherits `currentColor` and the caller's size and
+ * class exactly like a built-in one, and injecting a second svg root inside it
+ * would not.
+ */
+export function parseRegisteredGlyph(source: string): ProviderGlyph | null {
+  const root = svgRoot(source);
+  if (!root) return null;
+  const body = source.slice(root.bodyStart, root.bodyEnd).trim();
+  if (!body) return null;
+  const viewBox = /viewBox\s*=\s*(?:"([^"]*)"|'([^']*)')/i.exec(root.attributes);
+  const box = (viewBox?.[1] ?? viewBox?.[2] ?? '').trim();
+  if (!box) return null;
+  return { viewBox: box, body };
+}
+
+/**
+ * The mark to draw for a provider: a plugin's registration when one matches,
+ * otherwise the built-in table entry.
+ *
+ * Candidates are tried in the order the built-in resolver uses (`icon` before
+ * `slug` before `name`), and registrations in the order the store merged them —
+ * `order`, then plugin id, then registration id — so the FIRST registration for
+ * a provider wins deterministically and the loser is still an accepted
+ * registration, not a refused one. That first registration is authoritative: a
+ * glyph that does not parse falls through to the built-in mark rather than
+ * reaching for a later plugin's, so the mark shown never depends on which plugin
+ * happened to ship a broken string.
+ */
+export function resolveProviderMark(
+  candidates: ReadonlyArray<string | null | undefined>,
+  registered: ListSlotRows<ProviderIconRegistration>,
+): ProviderGlyph | null {
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const key = foldProviderKey(candidate);
+    if (!key) continue;
+    const entry = registered.find((row) => foldProviderKey(row.registration.provider) === key);
+    if (!entry) continue;
+    const glyph = parseRegisteredGlyph(entry.registration.glyph);
+    if (glyph) return glyph;
+    break;
+  }
+  const name = resolveProviderGlyph(...candidates);
+  return name ? (PROVIDER_GLYPHS[name] ?? null) : null;
+}

package/src/client/components/common/session-actions-menu/index.tsx

@@ -0,0 +1,220 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One overflow menu for a session row, shared by the desktop sidebar and the
+ * mobile one.
+ *
+ * The row used to carry its actions as side-by-side hover icons (rename,
+ * archive, delete). That does not scale: three icons cost roughly a third of
+ * the title's width in the 268px sidebar, and every action added from here
+ * takes another slice. One trigger whose contents grow is the shape that
+ * survives the next action.
+ *
+ * Two ways in, one menu out:
+ *   - the `⋯` button, which is the discoverable affordance;
+ *   - a right-click anywhere on the row, which is the accelerator. Both are
+ *     wired by the row component through `useRowMenu`.
+ *
+ * The menu positions itself from its OWN measured size. The item list is
+ * conditional (a pending `new-…` chat has no Rename or Delete), so a constant
+ * height would put the last row off-screen at the viewport edge — the same
+ * class of bug the file explorer's context menu works around with hand-tuned
+ * numbers.
+ */
+
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
+import type { TargetedMouseEvent } from 'preact';
+import { createPortal } from 'preact/compat';
+import { Archive, ArchiveRestore, Pencil, Trash2, WandSparkles } from 'lucide-preact';
+
+/** Viewport coordinates the menu hangs off, plus which edge it aligns to. */
+export interface MenuAnchor {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+  /**
+   * `end` hangs the menu's right edge off the anchor's — what a row's overflow
+   * button expects, since it sits at the row's end. `start` puts the menu's
+   * left edge at the anchor's, so a context-menu click opens away from the
+   * pointer rather than under it.
+   */
+  align: 'start' | 'end';
+}
+
+export interface RowMenuHandle {
+  /** Non-null while the menu is open. */
+  anchor: MenuAnchor | null;
+  /** Open below the clicked element (the `⋯` button). */
+  openBelow: (event: TargetedMouseEvent<HTMLElement>) => void;
+  /** Open at the pointer (a right-click on the row). */
+  openAtCursor: (event: TargetedMouseEvent<HTMLElement>) => void;
+  close: () => void;
+}
+
+/** Anchor state for one row's overflow menu. */
+export function useRowMenu(): RowMenuHandle {
+  const [anchor, setAnchor] = useState<MenuAnchor | null>(null);
+
+  const openBelow = useCallback((event: TargetedMouseEvent<HTMLElement>) => {
+    event.preventDefault();
+    // The row underneath selects the session on click; opening its menu is not
+    // a selection.
+    event.stopPropagation();
+    const rect = event.currentTarget.getBoundingClientRect();
+    setAnchor({ top: rect.top, right: rect.right, bottom: rect.bottom, left: rect.left, align: 'end' });
+  }, []);
+
+  const openAtCursor = useCallback((event: TargetedMouseEvent<HTMLElement>) => {
+    event.preventDefault();
+    event.stopPropagation();
+    const { clientX, clientY } = event;
+    setAnchor({ top: clientY, right: clientX, bottom: clientY, left: clientX, align: 'start' });
+  }, []);
+
+  const close = useCallback(() => setAnchor(null), []);
+
+  return { anchor, openBelow, openAtCursor, close };
+}
+
+export interface SessionActionsMenuProps {
+  anchor: MenuAnchor;
+  isArchived?: boolean;
+  /** Omitted when the row cannot be renamed (a pending `new-…` chat). */
+  onRename?: () => void;
+  /** Ask omp to name the session from its transcript. Omitted for a pending
+   *  `new-…` chat, which has no transcript to derive a title from. */
+  onRenameWithAi?: () => void;
+  onArchive?: () => void;
+  onDelete?: () => void;
+  onClose: () => void;
+}
+
+export function SessionActionsMenu({
+  anchor,
+  isArchived = false,
+  onRename,
+  onRenameWithAi,
+  onArchive,
+  onDelete,
+  onClose,
+}: SessionActionsMenuProps) {
+  const menuRef = useRef<HTMLDivElement>(null);
+  const [pos, setPos] = useState<{ top: number; left: number } | null>(null);
+
+  useLayoutEffect(() => {
+    const el = menuRef.current;
+    if (!el) return;
+    const { width, height } = el.getBoundingClientRect();
+    const margin = 8;
+    const below = anchor.bottom + 4;
+    // Flip above the trigger rather than overflowing the bottom edge.
+    const top = below + height + margin <= window.innerHeight
+      ? below
+      : Math.max(margin, anchor.top - height - 4);
+    const desiredLeft = anchor.align === 'end' ? anchor.right - width : anchor.left;
+    setPos({
+      top,
+      left: Math.max(margin, Math.min(desiredLeft, window.innerWidth - width - margin)),
+    });
+  }, [anchor]);
+
+  useEffect(() => {
+    const onKeyDown = (e: globalThis.KeyboardEvent) => {
+      if (e.key !== 'Escape') return;
+      e.preventDefault();
+      onClose();
+    };
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [onClose]);
+
+  // Every item closes the menu first: Rename opens an inline editor in the row,
+  // and leaving the menu over it would cover the input.
+  const run = (action?: () => void) => () => {
+    onClose();
+    action?.();
+  };
+
+  return createPortal(
+    <div
+      className="fixed inset-0 z-[70]"
+      onClick={onClose}
+      onContextMenu={(e) => {
+        e.preventDefault();
+        onClose();
+      }}
+    >
+      <div
+        ref={menuRef}
+        role="menu"
+        aria-label="Session actions"
+        style={{
+          top: pos?.top ?? anchor.bottom + 4,
+          left: pos?.left ?? anchor.left,
+          // Hidden for the single pre-measure render; `useLayoutEffect` settles
+          // the position before the browser paints, so this never flashes.
+          visibility: pos ? 'visible' : 'hidden',
+        }}
+        className="fixed z-[70] w-44 bg-paper border border-ink/15 rounded-lg shadow-xl py-1 text-xs text-ink font-sans"
+        onClick={(e) => e.stopPropagation()}
+      >
+        {onRename && (
+          <button
+            type="button"
+            role="menuitem"
+            onClick={run(onRename)}
+            className="w-full text-left px-3 py-1.5 hover:bg-ink/5 flex items-center gap-2 transition-colors cursor-pointer"
+          >
+            <Pencil size={12} className="text-ink/60" />
+            <span>Rename</span>
+          </button>
+        )}
+        {/* Next to Rename because it is the same intent, done for you: omp
+            reads the transcript and names the session itself. It replaces an
+            existing name, which is why it is an explicit click and never
+            something that happens on its own. */}
+        {onRenameWithAi && (
+          <button
+            type="button"
+            role="menuitem"
+            onClick={run(onRenameWithAi)}
+            className="w-full text-left px-3 py-1.5 hover:bg-ink/5 flex items-center gap-2 transition-colors cursor-pointer"
+          >
+            <WandSparkles size={12} className="text-ink/60" />
+            <span>Rename with AI</span>
+          </button>
+        )}
+        {onArchive && (
+          <button
+            type="button"
+            role="menuitem"
+            onClick={run(onArchive)}
+            className="w-full text-left px-3 py-1.5 hover:bg-ink/5 flex items-center gap-2 transition-colors cursor-pointer"
+          >
+            {isArchived
+              ? <ArchiveRestore size={12} className="text-ink/60" />
+              : <Archive size={12} className="text-ink/60" />}
+            <span>{isArchived ? 'Unarchive' : 'Archive'}</span>
+          </button>
+        )}
+        {(onRename || onRenameWithAi || onArchive) && onDelete && <div className="my-1 border-t border-ink/10" />}
+        {onDelete && (
+          <button
+            type="button"
+            role="menuitem"
+            onClick={run(onDelete)}
+            className="w-full text-left px-3 py-1.5 hover:bg-error/10 text-error flex items-center gap-2 transition-colors cursor-pointer"
+          >
+            <Trash2 size={12} className="text-error" />
+            <span>Delete</span>
+          </button>
+        )}
+      </div>
+    </div>,
+    document.body,
+  );
+}