@workerdeck/ui 0.13.0 → 0.16.0

package/README.md

@@ -150,3 +150,75 @@ lose by forgetting a second mount isn't one.
   `2h 10m`) with no React in the graph — for a host that renders session readings outside
   React, like an extension host drawing them into a window status bar, and wants them spelled
   exactly as the panel spells them.
+
+## Rules you cannot infer from the types
+
+- **Remount `SessionPanel` by key when the session id changes**, and never let its position in the
+  tree change otherwise: a remount drops the WebSocket attach and the whole transcript. That is why
+  the workspace keeps the panel's child index across the editor appearing and disappearing.
+- **The panel owns the session's one attach.** External chrome reads live values through
+  `onVitals` and changes them through `onControls`; opening a second attach to render a status bar
+  means the tool bridge may ask the wrong client.
+- **`transcriptVariant` and `transcriptDensity` ride context, not props.** A row component composed
+  by hand still gets the right treatment; restyling `data-slot`s from outside is not the seam.
+- **`statusSurface: 'external'` takes the `⋯` menu's only home with it.** Combining it with
+  `panelSurface: 'internal'` needs a *function* `header` to receive the menu, or those panels
+  become unreachable.
+- **The terminal theme (`variant: 'terminal'`) is a renderer, not a second set of branches.** It
+  draws every row itself from `components/terminal/` and the shell mounts it *instead* of the
+  components under `components/agent/`, so nothing in there asks which variant it is in — if it is
+  drawing at all, it is drawing cards.
+- **The panel mounts three terminal surfaces, and they must agree.** The transcript, the pending
+  prompts and the composer each establish their own cell, because each sits in a different part of
+  the flex column. `terminalMetrics` is one prop for exactly that reason: hand two of them
+  different numbers and the caret lands on a different column from the text above it.
+- **`transcriptDensity` and `transcriptFont` reach `cards` only.** A terminal has one line height
+  and is monospace by construction. Under `terminal` both are inert rather than broken — a host
+  offering them as settings should say so, or hide them (the dashboard hides them).
+- **`scrubber` and `stickyPrompt` reach `terminal` only**, and by construction rather than policy.
+  Both rest on the theme's premise — one line height and one cell make a row's height computable —
+  and under `cards` the flags are inert.
+- **`stickyPrompt` pins the real row, not a copy of it.** The prompt at the top of the scroller is
+  the same DOM node the transcript already rendered, with its transform clamped to the scroll
+  offset. A duplicate header cannot be made to line up with the rows beneath it, which is why this
+  is worth the machinery (`rangeExtractor` to keep it mounted, a manual push-off — `position:
+  sticky` does nothing on an absolutely positioned element).
+- **Terminal row heights are computed, and the cache invalidates by object identity.** The height
+  calculator keys a `WeakMap<TranscriptItem, …>` per (width, cell) epoch, which works only because
+  the react reducer replaces item objects on every mutation. Mutate a `TranscriptItem` in place and
+  you will serve a stale height for a row that has changed. The epoch is rebuilt from a
+  `ResizeObserver` on the **content** element, not the scroller — the panel can resize without the
+  wrap width moving, since the content column caps at 48rem.
+- **An item index is not a virtual row index.** `terminalBlocks` folds consecutive tool calls into
+  one row and the catch-up recap splices another, so `scrollToIndex(itemIndex)` lands off by the
+  fold on any transcript that has either. Go through `rowIndexForItem`.
+- **A row's rendered strings are also its height.** `height.ts` predicts each row's pixel height
+  with no DOM, so anything the terminal renderer *writes* must come from the module both sides
+  import — `tool-run.ts` for a folded run's summary line, `result-preview.ts` for a collapsed tool
+  result and its `… +N` label. Re-spelling either one in the renderer alone desynchronises
+  `estimateSize` and the transcript grows a phantom scrollable tail. `dev/height-audit.ts` is the
+  gate; it measures against real browser layout, which no jsdom test can do.
+- **`affordances={false}` must leave a way to scroll.** The scrubber replaces the native scrollbar
+  while it is interactive; with affordances off, the marks stay painted but inert *and the native
+  scrollbar comes back*. A rail that kept the scrollbar hidden while refusing the pointer would
+  strand the reader.
+- **Its two metrics must be whole pixels.** `--term-font-size` and `--term-line` are the character
+  cell; a line height of `1.5 x 13px` is 19.5px and puts every other row on a half-pixel, which
+  softens the text and shows a seam through the diff bands. Horizontal measures are `ch` and
+  vertical measures are whole multiples of `--term-line` — nothing in the theme is a px constant.
+- **`--term-bleed` is a contract, not a decoration.** A full-bleed band (a diff hunk, a user
+  prompt, a hover fill) cancels it with matched negative margin and padding, so it must equal the
+  scroller's own horizontal padding. `TerminalSurface` sets both; a host that pads the scroller
+  itself will see bands stop short.
+- **Line numbers come from the wire and nowhere else.** A diff renders `protocol`'s `FilePatch`,
+  whose hunks are the engine's own; this package has never read the file, so a number it computed
+  would be authoritative-looking and wrong. A patch whose hunks all start at 0 (an approval, where
+  the edit has not happened yet) renders *without* a number column rather than a column of zeroes.
+- **Affordances cost no layout, which is what makes `false` a real option.** The hover fill is a
+  background and the copy actions are absolutely-positioned overlays one line tall, so
+  `affordances={false}` changes no glyph's position — it is the pure article, not a degraded mode.
+- **Keep `monaco-editor` unreachable from `src/index.ts`.** Tree-shaking does not cover it: Vite
+  resolves Monaco's worker `new URL(...)`s while *transforming* the module, before shaking, and
+  emits megabytes of worker assets it never retracts. That is what the `/workspace` entry point is
+  for, and why Vite hosts need `optimizeDeps: { exclude: ['monaco-editor'] }`.
+

package/build/{SessionPanel-CZMA44NM.d.mts → SessionPanel-B9CHoq8x.d.mts}

@@ -2,7 +2,7 @@ import * as _$react from "react";
 import { ReactNode } from "react";
 import { LucideIcon } from "lucide-react";
 import { ModelOption, PermissionMode } from "@workerdeck/protocol";
-import { ConnectionState, TranscriptState } from "@workerdeck/react";
+import { ConnectionState, TranscriptState, UseToolCallHostOptions } from "@workerdeck/react";
 import { WorkerDeckClient } from "@workerdeck/client";
 
 //#region src/components/agent/PermissionModeSelect.d.ts
@@ -78,23 +78,85 @@ declare function PermissionModeSelect({
   className
 }: PermissionModeSelectProps): _$react.JSX.Element;
 //#endregion
+//#region src/components/terminal/affordances.d.ts
+/**
+ * The things a terminal cannot do, and this can.
+ *
+ * The theme's whole discipline is that it renders like a CLI — but it is not a
+ * CLI, and refusing every affordance a pointer makes possible would be cosplay
+ * rather than design. A terminal cannot highlight the row under your cursor and
+ * cannot put a copy button on a block of output; a web view can do both for free
+ * and they are genuinely useful.
+ *
+ * The rule that keeps this honest is that **each one costs no layout**. A hover
+ * fill is a background. An action button is an overlay at the row's right edge,
+ * one line tall, absolutely positioned so it displaces nothing. Turn them all
+ * off and every glyph is on exactly the same cell it was on — which is what
+ * makes `off` a real option rather than a degraded mode, and why it is the mode
+ * a host projecting to a real terminal would choose.
+ *
+ * Off by nothing in particular: both default **on**, because the surface these
+ * render on is a browser and pretending otherwise helps nobody. A host that
+ * wants the pure article passes `affordances={false}`.
+ */
+type TerminalAffordances = {
+  /** Fill the row under the pointer, on anything pressable. */hover?: boolean; /** Reveal a row's actions (copy, and whatever a row adds) on hover or focus. */
+  actions?: boolean;
+};
+declare function useAffordances(): Required<TerminalAffordances>;
+/**
+ * A block that reveals its actions on hover.
+ *
+ * Wraps rather than decorates because the actions belong to the *block* — a
+ * message is many rows and its copy button belongs at the top right of all of
+ * them, not on whichever row the pointer happens to be over.
+ */
+declare function WithActions({
+  actions,
+  children,
+  className
+}: {
+  actions: ReactNode;
+  children: ReactNode;
+  className?: string;
+}): _$react.JSX.Element;
+/**
+ * Copy, as a character.
+ *
+ * `⧉` and `✓` rather than an SVG for the same reason the rest of the theme uses
+ * glyphs: an icon drawn at some other size sits between the cells everything
+ * else is on, and reads as a button borrowed from another application. The tick
+ * replaces the glyph in place, so the confirmation costs no width either.
+ */
+declare function CopyAction({
+  text,
+  label
+}: {
+  text: string;
+  label?: string;
+}): _$react.JSX.Element;
+//#endregion
 //#region src/components/agent/transcript-variant.d.ts
 /**
  * How the transcript draws a turn.
  *
  * - `cards` — the chat convention: bubbles, bordered tool cards, generous gaps.
  *   Right for a wide dashboard where the transcript is the page.
- * - `lines` — one full-width line item per event, transparent, hover-highlit,
- *   with a glyph in a fixed left gutter. Right where vertical space is the
- *   scarce resource (a VS Code dock) and the terminal is the reference UX:
- *   nothing is boxed, the content and its marker carry the comprehension.
+ * - `terminal` — the CLI's own form: every row on a character cell, no boxes
+ *   anywhere, diffs as full-width bands. Right where the transcript sits beside
+ *   a terminal (a VS Code dock) and where vertical space is scarce.
+ *
+ * `terminal` is **not** a second set of branches in the components under
+ * `components/agent/`: it is its own renderer (`components/terminal/`) that the
+ * shell mounts *instead* of them. So a row component here never asks which
+ * variant it is in — if it is drawing at all, it is drawing cards.
  *
- * A context rather than a prop chain because every row component needs it and
- * only the transcript root knows it — and because `Message`/`ToolCallCard` are
- * exported on their own, so an embedder composing them by hand gets the right
- * treatment for free.
+ * A context rather than a prop chain because the pieces that DO need it sit
+ * outside the transcript (the composer, the pending prompts) and because
+ * `Message`/`ToolCallCard` are exported on their own, so an embedder composing
+ * them by hand gets the right treatment for free.
  */
-type TranscriptVariant = 'cards' | 'lines';
+type TranscriptVariant = 'cards' | 'terminal';
 declare function TranscriptVariantProvider({
   value,
   children
@@ -107,16 +169,17 @@ declare function useTranscriptVariant(): TranscriptVariant;
  * How much room the transcript gives each row.
  *
  * - `comfortable` — a blank line between messages, which is what the Claude Code
- *   CLI does and what the `lines` variant is trying to read like. The default:
- *   a transcript is prose before it is a table.
+ *   CLI does. The default: a transcript is prose before it is a table.
  * - `compact` — rows tight against each other, for a dock where every line of
  *   vertical space is contested.
  *
  * Separate from the variant, and deliberately: they answer different questions.
- * The variant decides *how a row is drawn* (boxed or not) and follows from the
- * surface; density decides *how much air is around it* and is a preference the
- * reader holds. Coupling them would mean a dock could not be roomy and a
- * dashboard could not be dense.
+ * The variant decides *how a row is drawn* and follows from the surface; density
+ * decides *how much air is around it* and is a preference the reader holds.
+ *
+ * Reaches `cards` only. The terminal theme's spacing is a blank *line*, decided
+ * per pair of blocks by `needsBlank` — a terminal has one line height, which is
+ * the whole premise — so there is nothing there for this to turn.
  */
 type TranscriptDensity = 'comfortable' | 'compact';
 declare function TranscriptDensityProvider({
@@ -127,8 +190,38 @@ declare function TranscriptDensityProvider({
   children: ReactNode;
 }): _$react.JSX.Element;
 declare function useTranscriptDensity(): TranscriptDensity;
+/**
+ * The typeface the panel runs in.
+ *
+ * `sans` is the host's UI font; `mono` repoints the sans token at the mono stack
+ * for the panel's subtree (see the `[data-agent-font='mono']` rule in
+ * `theme.css`), so the transcript reads as part of a terminal rather than as a
+ * web app beside one.
+ *
+ * No context and no hook, unlike variant and density: nothing branches on it in
+ * JS. It is one attribute on the panel root and the cascade does the rest, which
+ * is also what keeps it from leaking past the panel.
+ */
+type TranscriptFont = 'sans' | 'mono';
 //#endregion
 //#region src/components/agent/SessionPanel.d.ts
+/**
+ * The character cell the terminal theme draws on, in **whole pixels**.
+ *
+ * One object rather than two props because the panel mounts three separate
+ * `TerminalSurface`s — the transcript, the pending prompts, the composer — and
+ * they must agree: a prompt drawn at a different line height from the rows above
+ * it is three surfaces on three grids, which is the failure this theme is built
+ * to make impossible. Passing one value through one prop is what keeps them from
+ * drifting.
+ *
+ * Absent means the CLI's own 13/18. A host that follows an editor font size
+ * (VS Code) hands that down instead.
+ */
+type TerminalMetrics = {
+  fontSize?: number;
+  lineHeight?: number;
+};
 interface SessionPanelProps {
   client: WorkerDeckClient;
   sessionId: string | undefined;
@@ -191,12 +284,55 @@ interface SessionPanelProps {
    * internal ref, so an inline closure is fine). */
   onVitals?: (vitals: SessionVitals) => void;
   /**
-   * How the transcript draws a turn — `'cards'` (default) or `'lines'`, the
-   * space-efficient terminal treatment: no boxes, no bubbles, one full-width
-   * hover-highlit row per event behind a gutter glyph. An embedder in a dock
-   * (the VS Code panel) wants `'lines'`; a full-width dashboard usually doesn't.
+   * How the transcript draws a turn — `'cards'` (default, the chat convention)
+   * or `'terminal'`, the CLI's own form: every row on a character cell, no boxes
+   * anywhere, diffs as full-width bands. An embedder in a dock (the VS Code
+   * panel) wants `'terminal'`; a full-width dashboard may prefer cards.
    */
   transcriptVariant?: TranscriptVariant;
+  /**
+   * Terminal theme only: the pointer affordances a real terminal cannot offer —
+   * the hover fill, the hover-revealed copy. `false` for none. None of them
+   * costs layout, so turning them off changes no glyph's position. See
+   * {@link TerminalAffordances}.
+   */
+  affordances?: TerminalAffordances | boolean;
+  /**
+   * Terminal theme only: the character cell, in whole pixels. See
+   * {@link TerminalMetrics} — it reaches all three of the panel's terminal
+   * surfaces, which is why it is one prop and not two per surface.
+   */
+  terminalMetrics?: TerminalMetrics;
+  /**
+   * Terminal theme only: replace the scrollbar with the **overview ruler** — a
+   * `2ch` rail of coloured marks in three lanes (what you typed, the answer and
+   * its turn end, errors and a waiting approval), which you can hover to peek,
+   * click to jump, and drag to scrub.
+   *
+   * Its premise is the terminal theme's own: one line height and one cell make
+   * every row's height derivable, so a mark's position is *computed* rather than
+   * guessed from rows that have not mounted. That is why it is not offered under
+   * `cards` — there the flag is inert.
+   *
+   * `false` keeps the native scrollbar. So does `affordances={false}`, which
+   * leaves the marks painted but inert rather than removing a reader's only way
+   * to scroll.
+   */
+  scrubber?: boolean;
+  /**
+   * Bookmarked **item indices**, painted full-width on the rail. Paint only —
+   * the panel neither stores bookmarks nor offers a way to set one, because who
+   * owns that store is the embedder's question (a private pin belongs with the
+   * client's watermarks; a shared one is session metadata on the gateway).
+   */
+  scrubberMarks?: readonly number[];
+  /**
+   * Terminal theme only: hold the prompt of the turn you are reading at the top
+   * of the transcript, as the Claude Code CLI does. The **real row** is pinned
+   * rather than a copy drawn above it, so it lines up with the rows beneath by
+   * construction — see `TranscriptRows`.
+   */
+  stickyPrompt?: boolean;
   /**
    * How much air the transcript gives each row — `'comfortable'` (default: a
    * blank line between messages, as the Claude Code CLI leaves) or `'compact'`
@@ -205,18 +341,36 @@ interface SessionPanelProps {
    * dock is allowed to be roomy.
    */
   transcriptDensity?: TranscriptDensity;
+  /**
+   * The panel's typeface — `'sans'` (default, the host's UI font) or `'mono'`,
+   * which repoints the sans token at the mono stack **for this subtree only**.
+   *
+   * The third reader preference beside variant and density, and the same kind of
+   * thing: how a transcript should read is a property of the person reading it.
+   * Scoped to the panel because that is the whole claim — a monospace agent view
+   * next to an ordinary app, not a monospace app.
+   */
+  transcriptFont?: TranscriptFont;
   /**
    * Where the session's own controls — model and permission mode — live.
    * `'internal'` (default) draws them in the composer's toolbar row.
-   * `'external'` draws neither, and the composer collapses to a single line
-   * with its attach/send buttons beside the field: the embedder renders the
-   * pickers in its own chrome (VS Code's status bar, where a click opens a
-   * QuickPick) and drives them through {@link onControls}.
+   * `'status'` draws them in the panel's OWN status bar, beside the readings
+   * they act on; the composer collapses to a single line either way. That is
+   * VS Code's arrangement without VS Code — a host whose panel carries a status
+   * bar of its own (`statusPlacement: 'bottom'`) gets the same streamlined
+   * shape without having to host the pickers itself.
+   * `'external'` draws neither: the embedder renders the pickers in its own
+   * chrome (VS Code's window status bar, where a click opens a QuickPick) and
+   * drives them through {@link onControls}.
+   *
+   * `'status'` needs a status bar to put them in — with
+   * `statusSurface: 'external'` there is none, and the two together would hide
+   * the controls entirely, so that combination falls back to the composer.
    *
    * The options themselves ride {@link SessionVitals} — an embedder must not
    * attach a second time to learn what the models are.
    */
-  controlsSurface?: 'internal' | 'external';
+  controlsSurface?: 'internal' | 'external' | 'status';
   /**
    * Handed the session's setters once the panel is live, and `undefined` on
    * unmount. The counterpart to `controlsSurface: 'external'`: vitals carry the
@@ -265,6 +419,30 @@ interface SessionPanelProps {
    * enforcement lives on the gateway.
    */
   readOnly?: boolean;
+  /**
+   * Options for the browser tool host this panel runs on its own attach — or
+   * `false` to run none at all.
+   *
+   * The panel hosts server-bridged tool calls itself, because the bridge asks
+   * the *first attached client* and the panel owns the session's one attach: an
+   * embedder subscribing to the same handle separately would find this host
+   * already answering, and refusing, anything outside its allow-list. So the
+   * options come through here.
+   *
+   * Merged over the defaults, which host `eval_script` alone. Widening `tools`
+   * is a real grant — this tab will execute what the gateway asks it to for
+   * every name in the list — so it names them explicitly rather than accepting
+   * a wildcard.
+   */
+  toolHost?: UseToolCallHostOptions | false;
+  /**
+   * Keep this session's transcript warm across remounts (default true), so
+   * switching back to a recently viewed session paints instantly and replays
+   * only what it missed — `UseClaudeSessionOptions.cacheTranscript`. Set
+   * `false` for an embedder whose principal varies on one gateway URL by means
+   * the client cannot see.
+   */
+  cacheTranscript?: boolean;
   className?: string;
 }
 /** What an embedder needs to *change* a session it doesn't own the attach for. */
@@ -336,13 +514,21 @@ declare function SessionPanel({
   onVitals,
   transcriptVariant,
   transcriptDensity,
+  transcriptFont,
+  affordances,
+  terminalMetrics,
+  scrubber,
+  scrubberMarks,
+  stickyPrompt,
   controlsSurface,
   onControls,
   focusComposerOnClick,
   unseen,
   readOnly,
+  toolHost,
+  cacheTranscript,
   className
 }: SessionPanelProps): _$react.JSX.Element;
 //#endregion
-export { permissionModeChoices as _, SessionVitals as a, TranscriptVariant as c, useTranscriptVariant as d, PERMISSION_MODES as f, PermissionModeSelectProps as g, PermissionModeSelect as h, SessionSurfacePanel as i, TranscriptVariantProvider as l, PermissionModeMeta as m, SessionPanel as n, TranscriptDensity as o, PermissionModeChoice as p, SessionPanelProps as r, TranscriptDensityProvider as s, SessionControls as t, useTranscriptDensity as u, permissionModeMeta as v };
-//# sourceMappingURL=SessionPanel-CZMA44NM.d.mts.map
+export { permissionModeChoices as C, PermissionModeSelectProps as S, useAffordances as _, SessionVitals as a, PermissionModeMeta as b, TranscriptDensityProvider as c, TranscriptVariantProvider as d, useTranscriptDensity as f, WithActions as g, TerminalAffordances as h, SessionSurfacePanel as i, TranscriptFont as l, CopyAction as m, SessionPanel as n, TerminalMetrics as o, useTranscriptVariant as p, SessionPanelProps as r, TranscriptDensity as s, SessionControls as t, TranscriptVariant as u, PERMISSION_MODES as v, permissionModeMeta as w, PermissionModeSelect as x, PermissionModeChoice as y };
+//# sourceMappingURL=SessionPanel-B9CHoq8x.d.mts.map