dsh-better-display 0.3.8 → 0.3.9

package/src/client/motion.tsx

@@ -2,6 +2,7 @@ import { useCallback, useContext, useEffect, useLayoutEffect, useRef, useState }
 import type { ReactNode, RefObject } from 'react';
 import css from './Reader.module.css';
 import { StreamMotionContext } from './streaming.js';
+import { reconcileTurnSlots, type TurnSlot } from './turn-slots.js';
 
 const EASING = 'cubic-bezier(.22,1,.36,1)';
 
@@ -16,7 +17,7 @@ export function useMotionAllowed(enabled: boolean): boolean {
   return enabled && !reduced;
 }
 
-export function usePinnedSelection(root: RefObject<HTMLElement>, selector = '[data-reader-answer], [data-reader-process]'): readonly string[] {
+export function usePinnedSelection(root: RefObject<HTMLElement>, selector = '[data-reader-answer], [data-reader-body], [data-reader-process]'): readonly string[] {
   const [keys, setKeys] = useState<readonly string[]>([]);
   useEffect(() => {
     const update = () => {
@@ -89,7 +90,7 @@ export function StatusText({ text, motion, shimmer = false }: { text: string; mo
 
 export function Disclosure({ open, onChange, label, controls, buttonRef, ariaLabel }: {
   open: boolean; onChange: (value: boolean) => void; label: ReactNode;
-  controls?: string; buttonRef: RefObject<HTMLButtonElement>;
+  controls?: string; buttonRef?: RefObject<HTMLButtonElement>;
   ariaLabel?: string;
 }) {
   const name = ariaLabel ?? '思考与过程';
@@ -170,12 +171,16 @@ export function ProcessFragment({ open, motion, onRead, returnFocusTo, nodeKey,
 }
 
 /** Retire only narration that was actually visible; historical rows stay folded. */
-export function RetiringContent({ visible, children }: { visible: boolean; children: ReactNode }) {
+export function RetiringContent({ visible, children, onRetired }: { visible: boolean; children: ReactNode; onRetired?: () => void }) {
   const { enabled } = useContext(StreamMotionContext);
   const root = useRef<HTMLDivElement>(null);
   const animation = useRef<Animation | null>(null);
   const [present, setPresent] = useState(visible);
   const [focusHeld, setFocusHeld] = useState(false);
+  // Held in a ref so a caller passing an inline closure does not restart the
+  // collapse every render, and so the settle path always sees the latest one.
+  const retired = useRef(onRetired);
+  retired.current = onRetired;
   useLayoutEffect(() => {
     const element = root.current;
     if (visible) {
@@ -184,18 +189,49 @@ export function RetiringContent({ visible, children }: { visible: boolean; child
       return;
     }
     if (!element) return;
-    if (element.contains(document.activeElement)) { setFocusHeld(true); return; }
-    if (focusHeld) return;
+    // Reduced motion and a hidden page settle immediately. Focus may defer a
+    // collapse that will actually play; it must not pin a reduced-motion rewind.
+    // Move it to a surviving turn or the reading column first, or the browser
+    // drops it on the document when this subtree unmounts.
+    let retiredNow = false;
+    const retireNow = () => {
+      if (retiredNow) return;
+      retiredNow = true;
+      animation.current?.cancel(); animation.current = null;
+      focusSurvivesRetire(element);
+      setPresent(false); retired.current?.();
+    };
+    if (!enabled || document.hidden) { retireNow(); return; }
+    // The retiring-content harness stubs document without addEventListener.
+    const canListen = typeof document.addEventListener === 'function';
+    const holdsFocus = element.contains(document.activeElement);
+    if (holdsFocus || focusHeld) {
+      if (holdsFocus) setFocusHeld(true);
+      // Focus defers only a collapse that will play. `document.hidden` is not
+      // state, so a page hidden while focus waits must retire from here.
+      const onHiddenWhileHeld = () => { if (document.hidden) retireNow(); };
+      if (canListen) document.addEventListener('visibilitychange', onHiddenWhileHeld);
+      return () => { if (canListen) document.removeEventListener('visibilitychange', onHiddenWhileHeld); };
+    }
     const from = element.getBoundingClientRect().height;
     animation.current?.cancel(); animation.current = null;
-    if (!enabled || from < 1) { setPresent(false); return; }
+    if (from < 1) { setPresent(false); retired.current?.(); return; }
     const next = element.animate([{ height: `${from}px`, opacity: 1 }, { height: '0px', opacity: 0 }], { duration: 220, easing: EASING, fill: 'both' });
     animation.current = next;
-    const settle = () => { if (animation.current === next) { animation.current = null; next.cancel(); setPresent(false); } };
+    let settled = false;
+    const settle = () => {
+      if (settled || animation.current !== next) return;
+      settled = true;
+      animation.current = null; next.cancel(); setPresent(false); retired.current?.();
+    };
     next.onfinish = settle;
+    // #60: a stalled WAAPI finish must not leave the row mounted.
     const deadline = window.setTimeout(settle, 220 + 240);
+    const onHide = () => { if (document.hidden) settle(); };
+    if (canListen) document.addEventListener('visibilitychange', onHide);
     return () => {
       window.clearTimeout(deadline);
+      if (canListen) document.removeEventListener('visibilitychange', onHide);
       if (animation.current === next) animation.current = null;
       next.cancel();
     };
@@ -208,6 +244,98 @@ export function RetiringContent({ visible, children }: { visible: boolean; child
   </div>;
 }
 
+/**
+ * Keeps a departing turn mounted for the length of its own collapse.
+ *
+ * A rewind removes turns from the visible order, and unmounting them outright
+ * snapped the transcript: every withdrawn row disappeared in one frame with
+ * nothing to scroll. Instead each departing turn is retained, rendered with
+ * `visible={false}` so it animates to zero height, and released only once the
+ * collapse has settled — so the reader watches the rows fold away and the rows
+ * below glide up into their place.
+ *
+ * Live slots follow the incoming group order, so older history stays above the
+ * tail. A collapsing turn stays next to the live neighbour that preceded it;
+ * appending it would jump it to the bottom for the length of the animation.
+ * Retention is bounded by the animation itself: `onRetired`
+ * drops the slot, so a departing turn lives for one collapse and no longer —
+ * and a key that comes back later is re-added as a live slot.
+ */
+export function RetiringTurns<T extends { readonly key: string }>({ groups, render }: {
+  groups: readonly T[];
+  render: (group: T) => ReactNode;
+}) {
+  const [slots, setSlots] = useState<readonly TurnSlot<T>[]>(() =>
+    groups.map((group) => ({ group, live: true })),
+  );
+  // Reconcile after every commit rather than during render: a key that left the
+  // order becomes `live: false` and keeps its index, which is what lets the
+  // collapse play in place instead of jumping the turn to the bottom.
+  useLayoutEffect(() => {
+    setSlots(current => reconcileTurnSlots(current, groups));
+  }, [groups]);
+  return (
+    <>
+      {slots.map((slot) => (
+        <RetiringContent
+          key={slot.group.key}
+          visible={slot.live}
+          onRetired={() => setSlots((current) => current.filter((candidate) =>
+            candidate.live || candidate.group.key !== slot.group.key))}
+        >
+          {render(slot.group)}
+        </RetiringContent>
+      ))}
+    </>
+  );
+}
+
+/** A turn that is still on screen, not one this commit is about to unmount. */
+function survivingTurn(node: Element): HTMLElement | null {
+  if (!(node instanceof HTMLElement) || node.dataset.readerRetiring === 'retiring') return null;
+  const turn = node.hasAttribute('data-reader-turn') ? node : node.querySelector<HTMLElement>('[data-reader-turn]');
+  if (turn === null) return null;
+  const retiring = turn.closest('[data-reader-retiring]');
+  if (retiring instanceof HTMLElement && retiring.dataset.readerRetiring === 'retiring') return null;
+  return turn;
+}
+
+/**
+ * Where focus goes when cut content is removed without an animation.
+ * Prefer the nearest turn that is still live. Otherwise the reading column
+ * (or the host scrollport) so focus does not fall through to the document.
+ */
+function retireFocusTarget(element: HTMLElement): HTMLElement | null {
+  const parent = element.parentElement;
+  if (parent) {
+    const siblings = [...parent.children];
+    const index = siblings.indexOf(element);
+    for (let cursor = index - 1; cursor >= 0; cursor--) {
+      const turn = survivingTurn(siblings[cursor]!);
+      if (turn) return turn;
+    }
+    for (let cursor = index + 1; cursor < siblings.length; cursor++) {
+      const turn = survivingTurn(siblings[cursor]!);
+      if (turn) return turn;
+    }
+  }
+  const column = element.closest<HTMLElement>('[data-chat-flow]');
+  if (column && !element.contains(column)) return column;
+  const scroll = element.closest<HTMLElement>('[data-conversation-scroll]');
+  if (scroll && !element.contains(scroll)) return scroll;
+  return null;
+}
+
+/** Move focus out of `element` before it unmounts. A no-op when focus is elsewhere. */
+function focusSurvivesRetire(element: HTMLElement): void {
+  const active = document.activeElement;
+  if (active === null || !element.contains(active)) return;
+  const target = retireFocusTarget(element);
+  if (target === null || element.contains(target)) return;
+  if (target.tabIndex < 0) target.tabIndex = -1;
+  target.focus({ preventScroll: true });
+}
+
 // DOM-only behavior: the native Session remains the sole source of business data.
 export function useReadingScroll(root: RefObject<HTMLElement>, motion: boolean): {
   detached: boolean;

package/src/client/official-slots.tsx

@@ -56,12 +56,28 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
   }
 }
 
-// Existing Reader presentations own these rows. All other node kinds, including
-// future registrations, reach the official renderer through the mirror seat.
-// 'user' and 'steering' are mirrored too, so third-party renderers registered
-// on the official node slot (e.g. message-recall buttons) keep working inside
-// the Reader instead of being silently dropped.
-const READER_OWNED_NODES = new Set(['assistant-step', 'tool-call', 'turn-tail', 'turn-process']);
+// Reader draws these rows itself. Everything else, including future kinds, is
+// mirrored so the official renderer still runs inside the reading view.
+// 'user' and 'steering' stay mirrored (message-recall buttons and the like).
+// 'assistant-step' is special: the official renderer is priority 0 and Reader
+// keeps that presentation. A strictly lower priority is a keyed-slot
+// replacement (lowest priority renders) and is mirrored for body content.
+const READER_OWNED_NODES = new Set(['tool-call', 'turn-tail', 'turn-process']);
+
+/** Official `AssistantNodeView` registers at priority 0. Lower wins. */
+export const OFFICIAL_ASSISTANT_PRIORITY = 0;
+
+/**
+ * Mirror a chat-node registration into the Reader seat.
+ * Assistant replacements are the entries that would actually replace the
+ * official renderer on the host. The official priority itself stays out, so
+ * Reader keeps its own answer markdown until a plugin opts in.
+ */
+export function acceptMirroredChatNode(entry: StoredEntry): boolean {
+  const key = entry.options.key ?? '';
+  if (key === 'assistant-step') return (entry.options.priority ?? OFFICIAL_ASSISTANT_PRIORITY) < OFFICIAL_ASSISTANT_PRIORITY;
+  return !READER_OWNED_NODES.has(key);
+}
 const EXPECTED: Record<OfficialFamily, Spec> = {
   actions: { kind: 'list', scope: 'session' },
   tools: { kind: 'keyed', scope: 'session' },
@@ -201,7 +217,7 @@ export function installOfficialSlots(ctx: Context): () => void {
           throw new Error(`Official slot contract changed: ${source}`);
         }
         return mirrorOfficialSlot(slots, source, target, `dsh-better-display.official.${family}`,
-          family === 'nodes' ? entry => !READER_OWNED_NODES.has(entry.options.key ?? '') : undefined);
+          family === 'nodes' ? acceptMirroredChatNode : undefined);
       }));
     }
   } catch (error) {

package/src/client/projection.ts

@@ -33,6 +33,13 @@ export function boundaryOf(turn: TurnLocation | undefined): TurnBoundary {
   };
 }
 
+/**
+ * A settled body step before the closing step of a successful turn.
+ *
+ * This is presentation classification only. Narration is never process content
+ * and never folds. The flag only marks body text that is no longer the turn's
+ * final answer, so copy and fork stay on that final answer.
+ */
 export function isEarlierNarration(data: AssistantChatData, boundary: TurnBoundary): boolean {
   // New body text, a tool call, or a settled step is not a completed turn.
   if (data.status !== 'settled' || boundary.status !== 'closed' || boundary.reason !== 'completed') return false;
@@ -49,13 +56,18 @@ export function processChoiceKey(groupKey: string, boundary: TurnBoundary): stri
   return `${groupKey}:${boundary.status}:${boundary.reason ?? 'pending'}`;
 }
 
-/** A body-only assistant step is not a thinking/process disclosure. */
-export function hasProcessContent(node: ChatConversationViewNode | undefined, boundary: TurnBoundary): boolean {
+/**
+ * A body-only assistant step is not a thinking/process disclosure.
+ *
+ * Narration (text/image/other blocks) is always visible, so it never counts as
+ * foldable process content; only literal reasoning does. Tool calls arrive as
+ * their own flow entries and are checked separately by the reader.
+ */
+export function hasProcessContent(node: ChatConversationViewNode | undefined, _boundary: TurnBoundary): boolean {
   if (!node || node.visibility === 'hidden') return false;
   if (node.kind === 'assistant-step') {
     const data = node.data as AssistantChatData;
-    return data.blocks.some(block => block.kind === 'reasoning' && block.text.trim() !== '')
-      || (isEarlierNarration(data, boundary) && hasVisibleBody(data.blocks));
+    return data.blocks.some(block => block.kind === 'reasoning' && block.text.trim() !== '');
   }
   return node.kind === 'context' || node.kind === 'model-retry' || node.kind === 'system-prompt' || node.kind === 'turn-process'
     || node.kind === 'command' || node.kind === 'manual-compaction' || node.kind === 'compaction';

package/src/client/rewind-cut.ts

@@ -0,0 +1,340 @@
+/**
+ * Which chat rows a `/rewind` withdrew, expressed as a pure function of the
+ * chat snapshot.
+ *
+ * WHY THIS EXISTS. A rewind never deletes history: the host appends one
+ * replacement `user/message` marker whose `surfaceOp` shadows everything after
+ * the target, and the transcript must then read as it did *before* the target
+ * was sent. The official ChatView is a per-node renderer, so the rewind plugin
+ * (`dsh-rewind-plugin`) hides withdrawn rows by DOM: it computes the shadowed
+ * anchor seqs from the command node and sets `display:none` on every element
+ * carrying the official `data-chat-anchor-key` seat attribute.
+ *
+ * The Reader replaces ChatView's message list and renders its own row shapes
+ * (turn sections, answer articles, tool rows), so it does not republish that
+ * seat attribute on every row. DOM hiding therefore reaches only the user and
+ * steering bubbles, and every other withdrawn row — the answer, the tool rows,
+ * and the `/rewind` command row itself — stayed on screen. That is the reported
+ * defect: the command is recorded as a rewind row instead of the Reader rolling
+ * back to the state before the message was sent.
+ *
+ * The Reader decides visibility from React state, so it must apply the same
+ * contract itself instead of waiting for a third-party MutationObserver. The
+ * marker node is not admitted as a chat node (only append-origin surface events
+ * become nodes), so the command node's `outcome.sourceEventSeq` — the marker's
+ * log seq — plus the `@<seq>` target in its `args` are the only client-side
+ * signal for the shadowed range. This mirrors the plugin's own reader of that
+ * contract, and is pinned by `tests/rewind-cut.test.ts` so a plugin or host
+ * change cannot silently regress it.
+ *
+ * @module dsh-better-display/rewind-cut
+ */
+
+/** A chat-snapshot view node, read structurally (only the fields this module needs). */
+export interface CutChatNode {
+  readonly key: string;
+  readonly kind?: string;
+  readonly anchorSeq?: number;
+  readonly visibility?: string;
+  readonly data?: unknown;
+  /**
+   * Where the host placed the node in the session's location index. Only the
+   * owning turn is read from it, and an absent or foreign location is fine.
+   */
+  readonly location?: unknown;
+}
+
+/** The minimal chat-snapshot reader the cut logic needs. */
+export interface CutChat {
+  readonly order: readonly string[];
+  readonly nodes: {
+    get(key: string): CutChatNode | undefined;
+  };
+}
+
+/** One closed shadow range `[start, end]` in surface/anchor seq space. */
+export interface CutSpan {
+  readonly start: number;
+  readonly end: number;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function safeSeq(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+/** The command payload of a `command` chat node, when it is structurally readable. */
+function commandOf(node: CutChatNode): Record<string, unknown> | undefined {
+  if (node.kind !== 'command') return undefined;
+  return asRecord(node.data);
+}
+
+/**
+ * The engine names an executed rewind command node can carry. The plugin
+ * registers its command as `rewind-plugin` (`ENGINE_COMMANDS = new
+ * Set(['rewind-plugin', 'rewind'])` in dsh-rewind-plugin's
+ * `src/client/hidden.ts`), and that is the name the client projection actually
+ * publishes — the session log's `command/run.name` is not what the Reader sees.
+ * `rewind` stays accepted because older logs and the bili-side proxy record the
+ * shorter spelling.
+ */
+const REWIND_COMMANDS: ReadonlySet<string> = new Set(['rewind-plugin', 'rewind']);
+
+/** True when a command payload is the rewind engine command, in either spelling. */
+function isRewindCommand(command: Record<string, unknown>): boolean {
+  return typeof command.name === 'string' && REWIND_COMMANDS.has(command.name);
+}
+
+/**
+ * The render POSITION a row is anchored at: the view node's `anchorSeq`, else
+ * its payload seq.
+ *
+ * This is deliberately NOT integer-only. The host anchors synthetic rows at
+ * fractional offsets off a real seq (`CHAT_SYNTHETIC_SEQ_OFFSETS` in the
+ * official ChatView: `turn-process` at `controlAnchorSeq - 0.1`, `turn-tail` at
+ * `seq + 0.1`, an interrupted assistant step at `seq - 0.9`). An integer-only
+ * read made those rows invisible to the cut, so the last `turn-process` of a
+ * withdrawn turn survived on its own. Log seqs (marker, target) stay integer:
+ * see `safeSeq`.
+ */
+export function anchorSeqOf(node: CutChatNode): number | undefined {
+  const raw = node.anchorSeq ?? asRecord(node.data)?.seq;
+  return typeof raw === 'number' && Number.isFinite(raw) && raw >= 0 ? raw : undefined;
+}
+
+/**
+ * Extract the rewind target seq from a `/rewind` command's structured `args`
+ * (e.g. `@5 chat`, `preview @5 both`). Locale-independent: it never parses the
+ * host's human outcome copy.
+ */
+export function rewindTargetOfArgs(args: unknown): number | undefined {
+  if (typeof args !== 'string') return undefined;
+  const match = args.match(/@(\d+)/);
+  return match === null ? undefined : Number(match[1]);
+}
+
+/** True for the internal candidate-list probe (`/rewind __candidates`). */
+function isCandidateCommand(command: Record<string, unknown>): boolean {
+  return typeof command.args === 'string' && command.args.includes('__candidates');
+}
+
+/** True for an impact preview (`/rewind preview @5 both`). */
+function isPreviewCommand(command: Record<string, unknown>): boolean {
+  return typeof command.args === 'string' && command.args.includes('preview');
+}
+
+/**
+ * Merge overlapping or touching shadow ranges.
+ *
+ * Spans are kept SEPARATE unless they genuinely overlap: collapsing every cut
+ * to `[min target, max marker]` would hide a still-on-surface gap of new traffic
+ * between an earlier marker and a later target.
+ */
+export function coalesceCutSpans(spans: readonly CutSpan[]): CutSpan[] {
+  if (spans.length < 2) return [...spans];
+  const sorted = [...spans].sort((left, right) => left.start - right.start || left.end - right.end);
+  const merged: { start: number; end: number }[] = [];
+  for (const span of sorted) {
+    const last = merged.at(-1);
+    if (last !== undefined && span.start <= last.end) {
+      if (span.end > last.end) last.end = span.end;
+      continue;
+    }
+    merged.push({ start: span.start, end: span.end });
+  }
+  return merged;
+}
+
+/**
+ * True when a row anchored at `seq` falls inside one of the cut spans.
+ *
+ * A cut runs from the target seq through the marker's own log seq, inclusive
+ * (`target <= anchorSeq && anchorSeq <= marker`), the same comparison
+ * `dsh-rewind-plugin`'s `RewindVisibilityBuilder` uses. The upper bound stops
+ * at the marker. Extending it to the next integer hides the following turn's
+ * process row, which the host anchors at `startSeq - 0.1` and therefore in
+ * `[marker, marker + 1)`. Fractional anchors inside the closed range still
+ * match: `anchorSeqOf` keeps them. A process or tail row parked outside the
+ * range is handled by `summaryTurns`, not by widening the cut. Spans stay
+ * disjoint, so new traffic between two rewinds survives.
+ */
+export function cutContains(cuts: readonly CutSpan[], seq: number): boolean {
+  let low = 0;
+  let high = cuts.length - 1;
+  let found = -1;
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    const cut = cuts[middle];
+    if (cut === undefined) return false;
+    if (seq < cut.start) high = middle - 1;
+    else {
+      found = middle;
+      low = middle + 1;
+    }
+  }
+  const span = found < 0 ? undefined : cuts[found];
+  return span !== undefined && seq <= span.end;
+}
+
+/** The turn id a node belongs to (absent outside a turn). */
+function turnIdOf(node: CutChatNode): unknown | undefined {
+  // The location's own `kind` varies (`turn` for a turn's synthetic rows,
+  // `step` for one of its messages); only the turn it carries matters here.
+  const turn = asRecord(asRecord(node.location)?.turn);
+  if (turn === undefined || !Object.hasOwn(turn, 'turn')) return undefined;
+  return turn.turn;
+}
+
+/**
+ * Node kinds that SUMMARIZE a turn instead of carrying its content, so the host
+ * anchors them at the turn's edges rather than at an event inside it.
+ */
+const TURN_SUMMARY_KINDS: ReadonlySet<string> = new Set(['turn-process', 'turn-tail']);
+
+/**
+ * True for a rewind command row the transcript should not keep.
+ *
+ * Probes (`preview`, `__candidates`) exist only to feed the popover. An
+ * executed rewind — success plus a marker seq — is the command that performed
+ * the cut, and the plugin hides that row even when its anchor sits outside
+ * the numeric range. A failed or still-running command stays visible.
+ */
+function commandHidden(node: CutChatNode): boolean {
+  const command = commandOf(node);
+  if (command === undefined || !isRewindCommand(command)) return false;
+  if (isPreviewCommand(command) || isCandidateCommand(command)) return true;
+  const outcome = asRecord(command.outcome);
+  return outcome?.kind === 'success' && safeSeq(outcome.sourceEventSeq) !== undefined;
+}
+
+/** True when the row's own anchor falls in a cut, or the row is a rewind command to hide. */
+function anchorWithdrawn(node: CutChatNode, cuts: readonly CutSpan[]): boolean {
+  if (commandHidden(node)) return true;
+  const seq = anchorSeqOf(node);
+  return seq !== undefined && cutContains(cuts, seq);
+}
+
+/**
+ * Turns whose process and tail rows must leave.
+ *
+ * The host opens a turn before its user message is logged and anchors
+ * `turn-process` at `controlAnchorSeq - 0.1`, below the first withdrawn
+ * event, and `turn-tail` at `turn.end.seq + 0.1`, which can sit past the
+ * marker. Containment therefore misses those two rows, and the transcript
+ * kept announcing `执行过程 / 本轮已停止，已生成的内容仍保留。`
+ *
+ * A summary leaves only when every content row of its turn is already
+ * withdrawn — the same rule as the plugin's `deriveTurnProcess`. One content
+ * row before the target (a mid-turn steering rewind) keeps the summary and
+ * that earlier message. A turn with no content rows is left alone.
+ */
+function summaryTurns(chat: CutChat, cuts: readonly CutSpan[]): Set<unknown> {
+  const stays = new Map<unknown, boolean>();
+  for (const key of chat.order) {
+    const node = chat.nodes.get(key);
+    if (node === undefined || TURN_SUMMARY_KINDS.has(node.kind ?? '')) continue;
+    const id = turnIdOf(node);
+    if (id === undefined) continue;
+    const visible = node.visibility !== 'hidden' && !anchorWithdrawn(node, cuts);
+    stays.set(id, (stays.get(id) ?? false) || visible);
+  }
+  const withdrawn = new Set<unknown>();
+  for (const [id, visible] of stays) if (!visible) withdrawn.add(id);
+  return withdrawn;
+}
+
+/** True when this row is a summary of a turn whose content is fully withdrawn. */
+function summaryWithdrawn(node: CutChatNode, summaries: ReadonlySet<unknown>): boolean {
+  if (!TURN_SUMMARY_KINDS.has(node.kind ?? '')) return false;
+  const id = turnIdOf(node);
+  return id !== undefined && summaries.has(id);
+}
+
+/**
+ * The shadow ranges a session's executed rewinds produced, newest state last.
+ * An executed rewind cuts `[target, marker]` — the target itself is included,
+ * because a rewind restores the state *before* that message was sent (its text
+ * goes back to the composer).
+ */
+export function rewindCutSpans(chat: CutChat | undefined): CutSpan[] {
+  if (chat === undefined) return [];
+  const spans: CutSpan[] = [];
+  for (const key of chat.order) {
+    const node = chat.nodes.get(key);
+    if (node === undefined) continue;
+    const command = commandOf(node);
+    if (command === undefined || !isRewindCommand(command)) continue;
+    // Probes never open a span, even when a later host stamps them with a
+    // success marker. Matching them would roll the transcript back on preview.
+    if (isPreviewCommand(command) || isCandidateCommand(command)) continue;
+    const outcome = asRecord(command.outcome);
+    if (outcome?.kind !== 'success') continue;
+    const marker = safeSeq(outcome.sourceEventSeq);
+    if (marker === undefined) continue;
+    const target = rewindTargetOfArgs(command.args);
+    if (target === undefined || target > marker) continue;
+    spans.push({ start: target, end: marker });
+  }
+  return coalesceCutSpans(spans);
+}
+
+/**
+ * The anchor seqs the Reader must not render: every withdrawn message (the
+ * target, everything after it, and the unrendered marker), plus every `/rewind`
+ * row that exists only to feed the popover — the candidate-list probe and each
+ * impact preview. A SUCCESSFUL executed command row is covered by its own cut;
+ * a failed or unsettled one stays visible as an ordinary command record.
+ */
+export function hiddenRewindSeqs(chat: CutChat | undefined): Set<number> {
+  const hidden = new Set<number>();
+  if (chat === undefined) return hidden;
+  const cuts = rewindCutSpans(chat);
+  const summaries = summaryTurns(chat, cuts);
+  for (const key of chat.order) {
+    const node = chat.nodes.get(key);
+    if (node === undefined) continue;
+    if (!anchorWithdrawn(node, cuts) && !summaryWithdrawn(node, summaries)) continue;
+    const seq = anchorSeqOf(node);
+    if (seq !== undefined) hidden.add(seq);
+  }
+  return hidden;
+}
+
+/**
+ * The chat keys the Reader should render, in snapshot order: withdrawn rows and
+ * rows the host itself marked hidden are dropped, everything else keeps its
+ * position. Returns the snapshot's own `order` array when nothing is filtered,
+ * so React selectors see a stable reference.
+ */
+export function visibleChatKeys(chat: CutChat): readonly string[] {
+  const cuts = rewindCutSpans(chat);
+  const summaries = summaryTurns(chat, cuts);
+  const visible: string[] = [];
+  for (const key of chat.order) {
+    const node = chat.nodes.get(key);
+    if (node === undefined) continue;
+    if (node.visibility === 'hidden') continue;
+    if (anchorWithdrawn(node, cuts) || summaryWithdrawn(node, summaries)) continue;
+    visible.push(key);
+  }
+  return visible.length === chat.order.length ? chat.order : visible;
+}
+
+/**
+ * A comparable signal for the visible row set, built for
+ * `useSyncExternalStore`-style subscription: the host re-runs a chat selector
+ * on every publish and compares the RESULT by `Object.is`, and a rewind
+ * publishes an in-place upsert of an existing command row. The snapshot's
+ * `order` array and node store are therefore both reference-stable across a
+ * rewind, so a selector on them never re-renders; a string does change exactly
+ * when the visible set does. Never return the array itself from a selector —
+ * a fresh array fails the `Object.is` check on every publish.
+ */
+export function visibleChatSignature(chat: CutChat): string {
+  return visibleChatKeys(chat).join('\u0000');
+}