dsh-better-display 0.3.7 → 0.3.9

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');
+}

package/src/client/styles.ts

@@ -0,0 +1,22 @@
+const plugin = 'dsh-better-display';
+const styles = new Map<string, string>();
+
+/** Retain injected CSS across host cleanup and restore it before Reader paints. */
+export function ensureStyles(): void {
+  if (typeof document === 'undefined') return;
+  const live = new Set<string>();
+  for (const tag of document.querySelectorAll<HTMLStyleElement>(`style[data-plugin="${plugin}"][data-plugin-css]`)) {
+    const id = tag.dataset.pluginCss;
+    if (id === undefined) continue;
+    styles.set(id, tag.textContent ?? '');
+    live.add(id);
+  }
+  for (const [id, text] of styles) {
+    if (live.has(id)) continue;
+    const tag = document.createElement('style');
+    tag.dataset.plugin = plugin;
+    tag.dataset.pluginCss = id;
+    tag.textContent = text;
+    document.head.appendChild(tag);
+  }
+}

package/src/client/text-transform.ts

@@ -0,0 +1,265 @@
+import { useEffect, useMemo, useState } from 'react';
+import type { ReaderBlockOwner, ReaderBlockPresentation } from './types.js';
+
+/**
+ * Cordis service name. Another client plugin lists this in `inject` and
+ * registers a transformer. The reading view paints the result. The session
+ * block, transcript, and fold inputs stay on the original text.
+ */
+export const TEXT_TRANSFORM_SERVICE = 'dsh-better-display.text-transform';
+
+export type DisplayTextKind = 'reasoning' | 'body';
+
+export interface DisplayTextRequest {
+  /** Original block text. Registrants must not write it back onto the block. */
+  text: string;
+  streaming: boolean;
+  /** Opaque id of this mounted block. Stable until the block unmounts. */
+  blockKey: string;
+  kind: DisplayTextKind;
+  /** Assistant body and reasoning are the usual targets. Tool prose uses `tool`. */
+  source?: ReaderBlockOwner['source'];
+}
+
+export interface DisplayText {
+  text: string;
+  /**
+   * True when this string is the settled display for the current source.
+   * False keeps the live reveal open, including after the model has stopped
+   * but a translation batch is still outstanding.
+   */
+  final: boolean;
+}
+
+/**
+ * Sync `read` on every paint, plus `subscribe` when a later batch changes
+ * what `read` returns. `subscribe` may be called once per kind and must
+ * accept more than one listener.
+ */
+export interface DisplayTextTransformer {
+  read(request: DisplayTextRequest): DisplayText | string | undefined;
+  subscribe?(listener: () => void): () => void;
+}
+
+export interface DisplayCursor extends DisplayText {
+  /**
+   * Increments when the displayed string or its `final` bit changes.
+   * This is not the reveal clock. Passing it to the word timeline as the
+   * motion revision replays or snaps the paragraph.
+   */
+  transformRevision: number;
+  /**
+   * Reveal identity. Stays put when the new string extends the previous
+   * display string, so an appended translation batch continues the fade.
+   * Increments only when the string is replaced, which settles the new
+   * text instead of typing it again from the first grapheme.
+   */
+  motionRevision: number;
+}
+
+export interface TextTransformRegistry {
+  register(kind: DisplayTextKind | readonly DisplayTextKind[], transformer: DisplayTextTransformer): () => void;
+  has(kind: DisplayTextKind): boolean;
+  read(request: DisplayTextRequest): DisplayCursor;
+  subscribe(kind: DisplayTextKind, listener: () => void): () => void;
+  release(kind: DisplayTextKind, blockKey: string): void;
+}
+
+const KINDS = new Set<DisplayTextKind>(['reasoning', 'body']);
+
+function isKind(value: string): value is DisplayTextKind {
+  return KINDS.has(value as DisplayTextKind);
+}
+
+function reportTransformError(error: unknown): void {
+  console.warn('[dsh-better-display] text transform failed; showing original text', error);
+}
+
+function passthrough(request: DisplayTextRequest): DisplayCursor {
+  return { text: request.text, final: !request.streaming, transformRevision: 0, motionRevision: 0 };
+}
+
+function normalize(value: DisplayText | string | undefined, request: DisplayTextRequest): DisplayText {
+  if (typeof value === 'string') return { text: value, final: !request.streaming };
+  if (!value || typeof value.text !== 'string') return { text: request.text, final: !request.streaming };
+  return { text: value.text, final: typeof value.final === 'boolean' ? value.final : !request.streaming };
+}
+
+/**
+ * Appends keep the motion revision. A replacement gets a new one so the
+ * timeline treats the swapped string as already settled.
+ */
+export function nextDisplayCursor(previous: DisplayCursor | undefined, display: DisplayText): DisplayCursor {
+  if (!previous) return { ...display, transformRevision: 0, motionRevision: 0 };
+  if (previous.text === display.text && previous.final === display.final) return previous;
+  const appended = display.text.startsWith(previous.text);
+  return {
+    text: display.text,
+    final: display.final,
+    transformRevision: previous.transformRevision + 1,
+    motionRevision: appended ? previous.motionRevision : previous.motionRevision + 1,
+  };
+}
+
+/**
+ * Streaming flag fed to the reveal. With no transformer this is the model's
+ * flag. A transformer that reports `final: !streaming` produces the same flag.
+ */
+export function displayStreaming(sourceStreaming: boolean, shown: Pick<DisplayCursor, 'final'>, active: boolean): boolean {
+  return active ? !shown.final : sourceStreaming;
+}
+
+/** No registry, or none for this kind: the source string, and no cursor write. */
+export function readDisplayText(registry: TextTransformRegistry | undefined, request: DisplayTextRequest): DisplayCursor {
+  if (!registry?.has(request.kind)) return passthrough(request);
+  return registry.read(request);
+}
+
+interface StackEntry {
+  transformer: DisplayTextTransformer;
+  unsubscribe?: () => void;
+}
+
+class TextTransformRegistryImpl implements TextTransformRegistry {
+  private readonly stacks = new Map<DisplayTextKind, StackEntry[]>();
+  private readonly listeners = new Map<DisplayTextKind, Set<() => void>>();
+  private readonly cursors = new Map<string, DisplayCursor>();
+
+  register(kind: DisplayTextKind | readonly DisplayTextKind[], transformer: DisplayTextTransformer): () => void {
+    const requested = [...new Set(Array.isArray(kind) ? kind : [kind])];
+    for (const item of requested) {
+      if (!isKind(item)) throw new Error(`Unknown display text kind: ${String(item)}`);
+    }
+    const bound: { kind: DisplayTextKind; entry: StackEntry }[] = [];
+    for (const item of requested) {
+      const entry: StackEntry = { transformer };
+      try {
+        entry.unsubscribe = transformer.subscribe?.(() => { this.emit(item); });
+      } catch (error) {
+        reportTransformError(error);
+      }
+      const stack = this.stacks.get(item) ?? [];
+      stack.push(entry);
+      this.stacks.set(item, stack);
+      bound.push({ kind: item, entry });
+      this.emit(item);
+    }
+    return () => {
+      for (const { kind: item, entry } of bound) {
+        try { entry.unsubscribe?.(); } catch (error) { reportTransformError(error); }
+        const stack = this.stacks.get(item);
+        if (!stack) continue;
+        const next = stack.filter(candidate => candidate !== entry);
+        if (next.length > 0) this.stacks.set(item, next);
+        else this.stacks.delete(item);
+        this.emit(item);
+      }
+    };
+  }
+
+  has(kind: DisplayTextKind): boolean {
+    return (this.stacks.get(kind)?.length ?? 0) > 0;
+  }
+
+  read(request: DisplayTextRequest): DisplayCursor {
+    const transformer = this.stacks.get(request.kind)?.at(-1)?.transformer;
+    if (!transformer) return passthrough(request);
+    let display: DisplayText;
+    try {
+      display = normalize(transformer.read(request), request);
+    } catch (error) {
+      // A broken transformer must never hide the original text. Show it and
+      // ask again on the next text change or notify, so a recovered
+      // transformer takes over without a remount.
+      reportTransformError(error);
+      display = { text: request.text, final: !request.streaming };
+    }
+    const key = `${request.kind}\u0000${request.blockKey}`;
+    const next = nextDisplayCursor(this.cursors.get(key), display);
+    this.cursors.set(key, next);
+    return next;
+  }
+
+  subscribe(kind: DisplayTextKind, listener: () => void): () => void {
+    const set = this.listeners.get(kind) ?? new Set();
+    set.add(listener);
+    this.listeners.set(kind, set);
+    return () => { set.delete(listener); };
+  }
+
+  release(kind: DisplayTextKind, blockKey: string): void {
+    this.cursors.delete(`${kind}\u0000${blockKey}`);
+  }
+
+  private emit(kind: DisplayTextKind): void {
+    const set = this.listeners.get(kind);
+    if (!set) return;
+    for (const listener of [...set]) listener();
+  }
+}
+
+export function createTextTransformRegistry(): TextTransformRegistry {
+  return new TextTransformRegistryImpl();
+}
+
+let active: TextTransformRegistry | undefined;
+
+/** Points the reading view at the registry this client plugin provides. */
+export function installTextTransformRegistry(registry: TextTransformRegistry | undefined): () => void {
+  const previous = active;
+  active = registry;
+  return () => { active = previous; };
+}
+
+export function activeTextTransform(): TextTransformRegistry | undefined {
+  return active;
+}
+
+/**
+ * Subscribe while mounted. The reveal components call this only after
+ * `has(kind)`, so an empty registry adds no hook and no listener.
+ */
+export function useDisplayText(registry: TextTransformRegistry, request: DisplayTextRequest): DisplayCursor {
+  const [epoch, setEpoch] = useState(0);
+  const { text, streaming, blockKey, kind, source } = request;
+  useEffect(() => registry.subscribe(kind, () => { setEpoch(value => value + 1); }), [registry, kind]);
+  useEffect(() => () => { registry.release(kind, blockKey); }, [registry, kind, blockKey]);
+  return useMemo(
+    () => registry.read({ text, streaming, blockKey, kind, source }),
+    [registry, text, streaming, blockKey, kind, source, epoch],
+  );
+}
+
+/** Chain-slot owner. Extra fields are optional so older callers still type-check. */
+export function readerBlockOwner(
+  block: ReaderBlockOwner['block'],
+  streaming: boolean,
+  source: ReaderBlockOwner['source'],
+  presentation: ReaderBlockPresentation,
+  holdFormatting: boolean,
+): ReaderBlockOwner {
+  return {
+    block,
+    streaming,
+    source,
+    presentation: {
+      startedAt: presentation.startedAt,
+      interrupted: presentation.interrupted,
+      liveText: presentation.liveText,
+    },
+    holdFormatting,
+    liveText: presentation.liveText,
+  };
+}
+
+/** Copy actions read this. Display text never replaces it. */
+export function originalAnswerText(blocks: readonly { readonly kind: string; readonly text?: string }[]): string {
+  return blocks.flatMap(block => block.kind === 'text' && typeof block.text === 'string' ? [block.text] : []).join('\n\n');
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Display-only reader text transforms. Present after this client plugin applies. */
+    'dsh-better-display.text-transform'?: TextTransformRegistry;
+  }
+}

package/src/client/timeline.ts

@@ -1,5 +1,3 @@
-import type { TurnLocation } from '@deepseek-ai/dsh-client-ui-conversation/client';
-
 export interface TimelineItem {
   readonly turn: number;
   readonly prompt: string;