@sigrun/shared 0.0.0-stage → 0.1.0

package/dist/settings.js

@@ -0,0 +1,19 @@
+/**
+ * The settings-file TYPES (Task 8a, pi parity spec: the settings file) —
+ * the persisted `SettingsFile` shape and its sections.
+ *
+ * The CANONICAL type declarations live here (the shared leaf package);
+ * `src/harness/settings.ts` imports them (type-only) for the store/
+ * validation runtime. The `GET/PATCH /v1/settings` wire serves this
+ * shape verbatim (`SettingsResponse` = `SettingsFile` + the
+ * server-computed `toolRoster`; see `@sigrun/shared/views`), so both
+ * clients read these fields straight off the wire.
+ *
+ * The file is a JSON document at `<config-dir>/settings.json`. It
+ * carries the `HarnessSettings` pass-throughs (`steeringMode`,
+ * `followUpMode`, `retry`, `stream`) plus sigrun's own resolved fields
+ * (`defaultTools`, `perModelThinking`, `extensions`, `jobs`, `jobHistory`,
+ * `defaultModel`, `namingModel`, `defaultProvider`, `server`). Credentials
+ * never live here (they live in the sibling `auth.json`).
+ */
+export {};

package/dist/themes.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The shared theme data (Task B1, UI refresh): the four palettes and
+ * seven accents of the UI refresh, plus their name guards.
+ *
+ * PURE module: no imports at all (test/views-purity.test.ts enforces
+ * this). Both clients — webui (bundler, DOM) and tui (NodeNext) —
+ * consume this file from a single source; any import would drag a
+ * dependency only one client can load or resolve.
+ *
+ * Colour values are copied verbatim from the palette mockup
+ * (docs/superpowers/specs/assets/2026-10-17-ui-refresh/palettes.html),
+ * with the mockup ids renamed to the plan ids: palette `iron` →
+ * `iron-ember`, `aurora` → `polar-night`, `birch` → `birch-moss`;
+ * accent `amber` → `baltic-amber`; token key `surface-2` → `surface2`.
+ */
+export type PaletteName = "fjord" | "iron-ember" | "polar-night" | "birch-moss";
+export type AccentName = "baltic-amber" | "ember" | "lingonberry" | "glacier" | "aurora" | "lichen" | "heather";
+export type ModeName = "dark" | "light";
+/** One mode's tokens: every value a CSS colour literal. */
+export interface PaletteTokens {
+    readonly bg: string;
+    readonly surface: string;
+    readonly surface2: string;
+    readonly border: string;
+    readonly text: string;
+    readonly muted: string;
+    readonly faint: string;
+    readonly ok: string;
+    readonly code: string;
+}
+export interface Palette {
+    readonly label: string;
+    readonly defaultAccent: AccentName;
+    readonly dark: PaletteTokens;
+    readonly light: PaletteTokens;
+}
+export interface Accent {
+    readonly label: string;
+    readonly dark: string;
+    readonly light: string;
+}
+export declare const PALETTES: Readonly<Record<PaletteName, Palette>>;
+export declare const ACCENTS: Readonly<Record<AccentName, Accent>>;
+export declare const PALETTE_NAMES: readonly PaletteName[];
+export declare const ACCENT_NAMES: readonly AccentName[];
+/** The shipped default: Polar Night + Baltic Amber. */
+export declare const DEFAULT_PALETTE: PaletteName;
+export declare const DEFAULT_ACCENT: AccentName;
+export declare function isPaletteName(value: unknown): value is PaletteName;
+export declare function isAccentName(value: unknown): value is AccentName;

package/dist/themes.js

@@ -0,0 +1,156 @@
+/**
+ * The shared theme data (Task B1, UI refresh): the four palettes and
+ * seven accents of the UI refresh, plus their name guards.
+ *
+ * PURE module: no imports at all (test/views-purity.test.ts enforces
+ * this). Both clients — webui (bundler, DOM) and tui (NodeNext) —
+ * consume this file from a single source; any import would drag a
+ * dependency only one client can load or resolve.
+ *
+ * Colour values are copied verbatim from the palette mockup
+ * (docs/superpowers/specs/assets/2026-10-17-ui-refresh/palettes.html),
+ * with the mockup ids renamed to the plan ids: palette `iron` →
+ * `iron-ember`, `aurora` → `polar-night`, `birch` → `birch-moss`;
+ * accent `amber` → `baltic-amber`; token key `surface-2` → `surface2`.
+ */
+export const PALETTES = {
+    fjord: {
+        label: "Fjord",
+        defaultAccent: "baltic-amber",
+        dark: {
+            bg: "#0b0f13",
+            surface: "#11171e",
+            surface2: "#18202a",
+            border: "#222d39",
+            text: "#dde6ee",
+            muted: "#8d9cab",
+            faint: "#5f6e7d",
+            ok: "#7fbf9a",
+            code: "rgba(255,255,255,.06)",
+        },
+        light: {
+            bg: "#eef2f5",
+            surface: "#ffffff",
+            surface2: "#e3e9ef",
+            border: "#d3dbe3",
+            text: "#18212a",
+            muted: "#4d5b69",
+            faint: "#8593a1",
+            ok: "#2f8a5a",
+            code: "rgba(0,0,0,.05)",
+        },
+    },
+    "iron-ember": {
+        label: "Iron & Ember",
+        defaultAccent: "ember",
+        dark: {
+            bg: "#0e0e0f",
+            surface: "#161618",
+            surface2: "#1e1e21",
+            border: "#2a2a2e",
+            text: "#e6e1da",
+            muted: "#9a958e",
+            faint: "#66625d",
+            ok: "#8fb58a",
+            code: "rgba(255,255,255,.06)",
+        },
+        light: {
+            bg: "#f3f1ee",
+            surface: "#fbfaf8",
+            surface2: "#e9e6e1",
+            border: "#dbd7d1",
+            text: "#1c1b1a",
+            muted: "#55524d",
+            faint: "#8e8a84",
+            ok: "#3e7a3a",
+            code: "rgba(0,0,0,.05)",
+        },
+    },
+    "polar-night": {
+        label: "Polar Night",
+        defaultAccent: "aurora",
+        dark: {
+            bg: "#090d16",
+            surface: "#0f1524",
+            surface2: "#161e31",
+            border: "#1f2942",
+            text: "#e2e8f3",
+            muted: "#8e9ab2",
+            faint: "#5d6984",
+            ok: "#5fd4a8",
+            code: "rgba(255,255,255,.06)",
+        },
+        light: {
+            bg: "#f0f3f9",
+            surface: "#ffffff",
+            surface2: "#e4e9f3",
+            border: "#d2d9e6",
+            text: "#141b2b",
+            muted: "#4b5670",
+            faint: "#8691a8",
+            ok: "#13866a",
+            code: "rgba(0,0,0,.05)",
+        },
+    },
+    "birch-moss": {
+        label: "Birch & Moss",
+        defaultAccent: "lichen",
+        dark: {
+            bg: "#0d100d",
+            surface: "#141a15",
+            surface2: "#1b221c",
+            border: "#263027",
+            text: "#e8e6dc",
+            muted: "#9ba091",
+            faint: "#666d60",
+            ok: "#9cc48a",
+            code: "rgba(255,255,255,.06)",
+        },
+        light: {
+            bg: "#f3f2ea",
+            surface: "#fbfbf6",
+            surface2: "#e7e7dc",
+            border: "#d8d8ca",
+            text: "#1b1e18",
+            muted: "#525849",
+            faint: "#8b9080",
+            ok: "#4a7a35",
+            code: "rgba(0,0,0,.05)",
+        },
+    },
+};
+export const ACCENTS = {
+    "baltic-amber": { label: "Baltic Amber", dark: "#d6a24a", light: "#a8741f" },
+    ember: { label: "Ember", dark: "#d9773a", light: "#b8571c" },
+    lingonberry: { label: "Lingonberry", dark: "#d0606a", light: "#a83440" },
+    glacier: { label: "Glacier", dark: "#8fb8d0", light: "#2f6f93" },
+    aurora: { label: "Aurora", dark: "#5fd4a8", light: "#13866a" },
+    lichen: { label: "Lichen", dark: "#b9c46a", light: "#6f7a1f" },
+    heather: { label: "Heather", dark: "#a993c9", light: "#6c4f99" },
+};
+export const PALETTE_NAMES = [
+    "fjord",
+    "iron-ember",
+    "polar-night",
+    "birch-moss",
+];
+export const ACCENT_NAMES = [
+    "baltic-amber",
+    "ember",
+    "lingonberry",
+    "glacier",
+    "aurora",
+    "lichen",
+    "heather",
+];
+/** The shipped default: Polar Night + Baltic Amber. */
+export const DEFAULT_PALETTE = "polar-night";
+export const DEFAULT_ACCENT = "baltic-amber";
+export function isPaletteName(value) {
+    return (typeof value === "string" &&
+        Object.prototype.hasOwnProperty.call(PALETTES, value));
+}
+export function isAccentName(value) {
+    return (typeof value === "string" &&
+        Object.prototype.hasOwnProperty.call(ACCENTS, value));
+}

package/dist/turns.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Turn grouping (Task B1, UI refresh): fold a flat pi-durable entry
+ * list into the renderable turns both clients draw.
+ *
+ * PURE module: no imports at all (test/views-purity.test.ts enforces
+ * this). The entry/message/block types below are deliberately LOOSE
+ * (`role: string`, `content: string | readonly TurnBlock[]`) so both
+ * clients' wire types fit structurally — a shared import would defeat
+ * the single-source rule.
+ *
+ * Grouping: consecutive `pi.assistant` and `pi.tool-result` entries
+ * form ONE assistant turn; a `pi.user` entry is its own turn; every
+ * other kind (compaction records, summaries) is an `other` turn. A
+ * user or other entry also ENDS the assistant run.
+ *
+ * Task 2c: an EXPANDED input (`/skill:name`, a prompt template) is
+ * placed as ONE entry whose kind REPLACES `pi.user` —
+ * {@link EXPANDED_USER_KIND}, with `data {typed, command}` and the
+ * EXPANDED text on `model` (pi-durable's `SubmissionDraft.entry`).
+ * The grouping classifies it as a user turn (the renderers show the
+ * TYPED text with a chip); the server-side twin of the kind constant
+ * is `EXPANDED_ENTRY_KIND` in `src/commands/expand.ts`.
+ */
+/** The user-entry kind an expanded `/skill:` or template input is placed
+ *  as (see the module doc); grouping treats it exactly like `pi.user`. */
+export declare const EXPANDED_USER_KIND = "sigrun.user.expanded";
+export interface TurnBlock {
+    readonly type: string;
+    readonly text?: string;
+    readonly thinking?: string;
+    readonly id?: string;
+    readonly name?: string;
+    readonly arguments?: unknown;
+}
+export interface TurnMessage {
+    readonly role: string;
+    readonly content: string | readonly TurnBlock[];
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+    readonly isError?: boolean;
+}
+export interface TurnEntry {
+    readonly id: number;
+    readonly kind: string;
+    readonly model?: readonly TurnMessage[];
+    /** The entry's kind-specific JSON payload — `sigrun.user.expanded`'s
+     *  `{typed, command}` (see {@link expandedUserEntry}). */
+    readonly data?: unknown;
+}
+/** The narrowed `data` of a {@link EXPANDED_USER_KIND} entry: what the
+ *  user TYPED (the bubble's text) and the command that expanded. */
+export interface ExpandedUserEntryData {
+    readonly typed: string;
+    readonly command?: string;
+}
+/** Narrow one entry to its expanded-user `data` — defined exactly when
+ *  the kind is {@link EXPANDED_USER_KIND} and `typed` is a non-empty
+ *  string; undefined for every other shape (a plain `pi.user`, missing
+ *  or malformed data). */
+export declare function expandedUserEntry(entry: {
+    readonly kind: string;
+    readonly data?: unknown;
+}): ExpandedUserEntryData | undefined;
+export interface ToolCall {
+    readonly callId: string;
+    readonly name: string;
+    readonly preview: string;
+    readonly resultEntryId?: number;
+    readonly isError: boolean;
+}
+export type Turn<E extends TurnEntry> = {
+    readonly kind: "user";
+    readonly entry: E;
+} | {
+    readonly kind: "assistant";
+    readonly entries: readonly E[];
+    readonly thinking: readonly string[];
+    readonly tools: readonly ToolCall[];
+    readonly text: string;
+    readonly lastEntryId: number;
+} | {
+    readonly kind: "other";
+    readonly entry: E;
+};
+export declare function groupTurns<E extends TurnEntry>(entries: readonly E[]): Turn<E>[];
+export declare function toolPreview(name: string, args: unknown): string;
+/**
+ * The FULL argument a tool's preview shows, uncut — the transcript's
+ * copy-command action copies it verbatim: the same name-keyed argument
+ * the preview selects, before its first-line/80-char truncation.
+ * Undefined when the arguments carry no previewable string.
+ */
+export declare function previewArgument(name: string, args: unknown): string | undefined;
+/**
+ * The collapsed activity line under an assistant turn: thinking and
+ * tool COUNTS only — the entry wire carries no per-block timing, so
+ * durations are never shown (plan deviation, Task D records it).
+ */
+export declare function activityLabel(turn: {
+    thinking: readonly string[];
+    tools: readonly ToolCall[];
+}): string;

package/dist/turns.js

@@ -0,0 +1,166 @@
+/**
+ * Turn grouping (Task B1, UI refresh): fold a flat pi-durable entry
+ * list into the renderable turns both clients draw.
+ *
+ * PURE module: no imports at all (test/views-purity.test.ts enforces
+ * this). The entry/message/block types below are deliberately LOOSE
+ * (`role: string`, `content: string | readonly TurnBlock[]`) so both
+ * clients' wire types fit structurally — a shared import would defeat
+ * the single-source rule.
+ *
+ * Grouping: consecutive `pi.assistant` and `pi.tool-result` entries
+ * form ONE assistant turn; a `pi.user` entry is its own turn; every
+ * other kind (compaction records, summaries) is an `other` turn. A
+ * user or other entry also ENDS the assistant run.
+ *
+ * Task 2c: an EXPANDED input (`/skill:name`, a prompt template) is
+ * placed as ONE entry whose kind REPLACES `pi.user` —
+ * {@link EXPANDED_USER_KIND}, with `data {typed, command}` and the
+ * EXPANDED text on `model` (pi-durable's `SubmissionDraft.entry`).
+ * The grouping classifies it as a user turn (the renderers show the
+ * TYPED text with a chip); the server-side twin of the kind constant
+ * is `EXPANDED_ENTRY_KIND` in `src/commands/expand.ts`.
+ */
+/** The user-entry kind an expanded `/skill:` or template input is placed
+ *  as (see the module doc); grouping treats it exactly like `pi.user`. */
+export const EXPANDED_USER_KIND = "sigrun.user.expanded";
+/** Narrow one entry to its expanded-user `data` — defined exactly when
+ *  the kind is {@link EXPANDED_USER_KIND} and `typed` is a non-empty
+ *  string; undefined for every other shape (a plain `pi.user`, missing
+ *  or malformed data). */
+export function expandedUserEntry(entry) {
+    if (entry.kind !== EXPANDED_USER_KIND)
+        return undefined;
+    const data = entry.data;
+    if (typeof data !== "object" || data === null)
+        return undefined;
+    const typed = data.typed;
+    if (typeof typed !== "string" || typed === "")
+        return undefined;
+    const command = data.command;
+    return typeof command === "string" && command !== ""
+        ? { typed, command }
+        : { typed };
+}
+/** The assistant text blocks of one message, in order. */
+function blocks(message) {
+    return typeof message.content === "string" ? [] : message.content;
+}
+export function groupTurns(entries) {
+    const turns = [];
+    let pending = null;
+    const flush = () => {
+        if (pending === null)
+            return;
+        turns.push({
+            kind: "assistant",
+            entries: pending.entries,
+            thinking: pending.thinking,
+            tools: pending.tools,
+            text: pending.texts.join("\n\n"),
+            lastEntryId: pending.entries[pending.entries.length - 1].id,
+        });
+        pending = null;
+    };
+    for (const entry of entries) {
+        if (entry.kind === "pi.assistant" || entry.kind === "pi.tool-result") {
+            pending ??= { entries: [], thinking: [], tools: [], texts: [] };
+            pending.entries.push(entry);
+            if (entry.kind === "pi.assistant") {
+                for (const message of entry.model ?? []) {
+                    for (const block of blocks(message)) {
+                        if (block.type === "text" && block.text !== undefined) {
+                            pending.texts.push(block.text);
+                        }
+                        else if (block.type === "thinking" && block.thinking !== undefined) {
+                            pending.thinking.push(block.thinking);
+                        }
+                        else if (block.type === "toolCall") {
+                            pending.tools.push({
+                                callId: block.id ?? "",
+                                name: block.name ?? "",
+                                preview: toolPreview(block.name ?? "", block.arguments),
+                                isError: false,
+                            });
+                        }
+                    }
+                }
+            }
+            else {
+                for (const message of entry.model ?? []) {
+                    if (message.toolCallId === undefined)
+                        continue;
+                    const tool = pending.tools.find((candidate) => candidate.callId === message.toolCallId &&
+                        candidate.resultEntryId === undefined);
+                    if (tool !== undefined) {
+                        tool.resultEntryId = entry.id;
+                        tool.isError = message.isError === true;
+                    }
+                }
+            }
+            continue;
+        }
+        flush();
+        if (entry.kind === "pi.user" || entry.kind === EXPANDED_USER_KIND) {
+            turns.push({ kind: "user", entry });
+        }
+        else {
+            turns.push({ kind: "other", entry });
+        }
+    }
+    flush();
+    return turns;
+}
+/** Which argument each known tool previews, by tool name. */
+const PREVIEW_ARGUMENT = {
+    bash: "command",
+    read: "path",
+    write: "path",
+    edit: "path",
+    ls: "path",
+    find: "path",
+    grep: "pattern",
+};
+const PREVIEW_MAX = 80;
+export function toolPreview(name, args) {
+    const candidate = previewArgument(name, args);
+    if (candidate === undefined)
+        return "";
+    const firstLine = candidate.split("\n", 1)[0];
+    return firstLine.length > PREVIEW_MAX
+        ? `${firstLine.slice(0, PREVIEW_MAX)}…`
+        : firstLine;
+}
+/**
+ * The FULL argument a tool's preview shows, uncut — the transcript's
+ * copy-command action copies it verbatim: the same name-keyed argument
+ * the preview selects, before its first-line/80-char truncation.
+ * Undefined when the arguments carry no previewable string.
+ */
+export function previewArgument(name, args) {
+    if (typeof args !== "object" || args === null || Array.isArray(args)) {
+        return undefined;
+    }
+    const record = args;
+    const key = PREVIEW_ARGUMENT[name];
+    const candidate = key === undefined
+        ? Object.values(record).find((value) => typeof value === "string")
+        : record[key];
+    return typeof candidate === "string" && candidate.length > 0
+        ? candidate
+        : undefined;
+}
+/**
+ * The collapsed activity line under an assistant turn: thinking and
+ * tool COUNTS only — the entry wire carries no per-block timing, so
+ * durations are never shown (plan deviation, Task D records it).
+ */
+export function activityLabel(turn) {
+    const parts = [];
+    if (turn.thinking.length > 0)
+        parts.push("Thinking");
+    if (turn.tools.length > 0) {
+        parts.push(`${turn.tools.length} ${turn.tools.length === 1 ? "tool" : "tools"}`);
+    }
+    return parts.join(" · ");
+}

package/dist/view-delta.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Delta view frames (core hardening W3, spec §7.3 ruling 11): the SSE view
+ * stream's incremental frame shape and its pure diff/fold functions, shared
+ * by the server (which diffs) and both clients (which fold).
+ *
+ * The stream keeps `event: snapshot` (the full wire view) on connect and as
+ * the fallback; each later revision is a `event: delta` frame carrying only
+ * what changed:
+ *
+ * - `entries.append` / `entries.remove` — the entry list keyed by `id`;
+ *   removals plus a pure suffix append are representable, anything else
+ *   (a head insert, a reorder — e.g. a compaction's new head marker) makes
+ *   {@link diffViews} return `undefined` and the server sends a fresh
+ *   snapshot instead;
+ * - `docs.set` / `docs.unset` — the changed/removed named documents;
+ * - `conversation` / `steer` — present only when they differ.
+ *
+ * Purity: a shared wire module — `import type` sibling-only (the purity
+ * guard in test/views-purity.test.ts); the runtime functions below are
+ * dependency-free so both clients (DOM-only webui, NodeNext tui) and the
+ * server fold identically.
+ */
+import type { JsonObject } from "./json.js";
+import type { ConversationViewWire, SteerField, ViewConversation, ViewEntry } from "./views.js";
+/** One `event: delta` frame's payload. Absent slots mean "no change". */
+export interface ViewDelta {
+    readonly entries?: {
+        readonly append?: readonly ViewEntry[];
+        readonly remove?: readonly number[];
+    };
+    readonly docs?: {
+        readonly set?: Readonly<Record<string, JsonObject>>;
+        readonly unset?: readonly string[];
+    };
+    readonly conversation?: ViewConversation;
+    readonly steer?: SteerField;
+}
+/**
+ * Diff two consecutive wire views into a delta, or `undefined` when the
+ * change is not representable: entries are keyed by `id`, `remove` is the
+ * prev ids absent from next, and AFTER removal prev's remaining ids must be
+ * a PREFIX of next's (append-only tail). A head insert or reorder fails the
+ * prefix rule → `undefined` → the caller sends a fresh snapshot.
+ */
+export declare function diffViews(prev: ConversationViewWire, next: ConversationViewWire): ViewDelta | undefined;
+/**
+ * Fold a delta into a view: filter removed entry ids, concat the appended
+ * suffix, shallow-merge docs (set over, unset out), replace
+ * `conversation`/`steer` when present. NEVER mutates `view` — every changed
+ * slot is a fresh object/array (unchanged slots keep their references).
+ */
+export declare function applyDelta(view: ConversationViewWire, delta: ViewDelta): ConversationViewWire;
+/** True when every slot is absent or empty (the server skips these frames). */
+export declare function isEmptyDelta(delta: ViewDelta): boolean;

package/dist/view-delta.js

@@ -0,0 +1,135 @@
+/**
+ * Delta view frames (core hardening W3, spec §7.3 ruling 11): the SSE view
+ * stream's incremental frame shape and its pure diff/fold functions, shared
+ * by the server (which diffs) and both clients (which fold).
+ *
+ * The stream keeps `event: snapshot` (the full wire view) on connect and as
+ * the fallback; each later revision is a `event: delta` frame carrying only
+ * what changed:
+ *
+ * - `entries.append` / `entries.remove` — the entry list keyed by `id`;
+ *   removals plus a pure suffix append are representable, anything else
+ *   (a head insert, a reorder — e.g. a compaction's new head marker) makes
+ *   {@link diffViews} return `undefined` and the server sends a fresh
+ *   snapshot instead;
+ * - `docs.set` / `docs.unset` — the changed/removed named documents;
+ * - `conversation` / `steer` — present only when they differ.
+ *
+ * Purity: a shared wire module — `import type` sibling-only (the purity
+ * guard in test/views-purity.test.ts); the runtime functions below are
+ * dependency-free so both clients (DOM-only webui, NodeNext tui) and the
+ * server fold identically.
+ */
+/** Structural equality for the JSON-shaped slots (docs/conversation/steer). */
+function jsonEqual(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Diff two consecutive wire views into a delta, or `undefined` when the
+ * change is not representable: entries are keyed by `id`, `remove` is the
+ * prev ids absent from next, and AFTER removal prev's remaining ids must be
+ * a PREFIX of next's (append-only tail). A head insert or reorder fails the
+ * prefix rule → `undefined` → the caller sends a fresh snapshot.
+ */
+export function diffViews(prev, next) {
+    const delta = {};
+    // Entries: removals, then the prefix rule, then the appended suffix.
+    const nextIds = new Set(next.entries.map((entry) => entry.id));
+    const remove = prev.entries
+        .filter((entry) => !nextIds.has(entry.id))
+        .map((entry) => entry.id);
+    const remaining = prev.entries.filter((entry) => nextIds.has(entry.id));
+    const prefix = remaining.every((entry, index) => entry.id === next.entries[index]?.id);
+    if (!prefix)
+        return undefined;
+    const append = next.entries.slice(remaining.length);
+    if (remove.length > 0 || append.length > 0) {
+        delta.entries = {};
+        if (remove.length > 0)
+            delta.entries.remove = remove;
+        if (append.length > 0)
+            delta.entries.append = [...append];
+    }
+    // Docs: reference-equal first (the common no-op revision), JSON second.
+    const docKeys = new Set([
+        ...Object.keys(prev.docs),
+        ...Object.keys(next.docs),
+    ]);
+    const set = {};
+    const unset = [];
+    for (const key of docKeys) {
+        const before = prev.docs[key];
+        const after = next.docs[key];
+        if (after === undefined) {
+            if (before !== undefined)
+                unset.push(key);
+            continue;
+        }
+        if (before === undefined || !jsonEqual(before, after))
+            set[key] = after;
+    }
+    if (unset.length > 0 || Object.keys(set).length > 0) {
+        delta.docs = {};
+        if (unset.length > 0)
+            delta.docs.unset = unset;
+        if (Object.keys(set).length > 0)
+            delta.docs.set = set;
+    }
+    if (!jsonEqual(prev.conversation, next.conversation)) {
+        delta.conversation = next.conversation;
+    }
+    if (!jsonEqual(prev.steer, next.steer)) {
+        delta.steer = next.steer;
+    }
+    return delta;
+}
+/**
+ * Fold a delta into a view: filter removed entry ids, concat the appended
+ * suffix, shallow-merge docs (set over, unset out), replace
+ * `conversation`/`steer` when present. NEVER mutates `view` — every changed
+ * slot is a fresh object/array (unchanged slots keep their references).
+ */
+export function applyDelta(view, delta) {
+    let entries = view.entries;
+    if (delta.entries !== undefined) {
+        const removed = new Set(delta.entries.remove ?? []);
+        entries = [
+            ...view.entries.filter((entry) => !removed.has(entry.id)),
+            ...(delta.entries.append ?? []),
+        ];
+    }
+    let docs = view.docs;
+    if (delta.docs !== undefined) {
+        const unset = new Set(delta.docs.unset ?? []);
+        const merged = {};
+        for (const [key, value] of Object.entries(view.docs)) {
+            if (!unset.has(key))
+                merged[key] = value;
+        }
+        for (const [key, value] of Object.entries(delta.docs.set ?? {})) {
+            merged[key] = value;
+        }
+        docs = merged;
+    }
+    return {
+        ...view,
+        entries,
+        docs,
+        conversation: delta.conversation ?? view.conversation,
+        steer: delta.steer ?? view.steer,
+    };
+}
+/** True when every slot is absent or empty (the server skips these frames). */
+export function isEmptyDelta(delta) {
+    const entries = delta.entries;
+    if (entries !== undefined &&
+        ((entries.append?.length ?? 0) > 0 || (entries.remove?.length ?? 0) > 0)) {
+        return false;
+    }
+    const docs = delta.docs;
+    if (docs !== undefined &&
+        (Object.keys(docs.set ?? {}).length > 0 || (docs.unset?.length ?? 0) > 0)) {
+        return false;
+    }
+    return delta.conversation === undefined && delta.steer === undefined;
+}