@startsimpli/ui 0.4.135 → 0.4.136

package/src/components/history/revision-history.ts

@@ -0,0 +1,484 @@
+/**
+ * The render-time fold, and what one field change actually SAYS
+ * (bd startsim-g4rwo; trail bd startsim-o1qib; extraction bd startsim-m7fdm.1).
+ *
+ * Pure — no React, no fetching — so every rule below unit-tests without a
+ * backend and without a render.
+ *
+ * ── WHY THE FOLD IS HERE AND NOT ON THE SERVER ──────────────────────────────
+ *
+ * There is NO server-side coalescing, deliberately: the trail is one bare
+ * INSERT per write, because growing an open row inside a window is a
+ * read-modify-write on a path where the autosave debounce is 1200ms and two
+ * saves from one reviewer are routinely in flight — which is precisely the
+ * mechanism that drops `data._edit_history` entries today, one table over. A
+ * revision that claims text the record does not hold is worse than a missing
+ * one. So the server stays dumb and correct, and the folding happens here.
+ *
+ * The consequence this module exists to absorb: a reviewer working through a
+ * 500-word blog issues DOZENS of PATCHes, so a sitting is dozens of rows. One
+ * row per PATCH is not accountability, it is a wall of near-identical
+ * timestamps that nobody reads — and the wall is worse than nothing, because it
+ * hides the one thing the customer asked for.
+ *
+ * ── WHY FIVE MINUTES ────────────────────────────────────────────────────────
+ *
+ * Not because five is special — because of where the gaps actually fall. Inside
+ * one sitting at the keyboard the gaps are SECONDS (the debounce is 1.2s and
+ * typing is continuous), so almost any window kills the autosave noise. What a
+ * window has to get right is the other side: the smallest gap that means "she
+ * stopped, and came back". Five minutes is comfortably longer than reading a
+ * rendered preview or fixing an issue in the rail, and comfortably shorter than
+ * leaving the desk. Longer windows only merge sittings that really were
+ * separate, which is a loss of truth for no gain in quiet.
+ *
+ * AND IT IS ONE NUMBER: 0 gives a row per save, higher gives a row per visit.
+ * Nothing else in this module knows which a tenant wants.
+ */
+import type {
+  ActorKind,
+  ActorKindSource,
+  EntityRevision,
+  RevisionFieldChange,
+} from './types';
+
+/**
+ * How close two writes by the same actor have to be to count as one sitting.
+ * See this module's header for why five minutes. Carried over verbatim from
+ * `marketing-agents-web/src/lib/edit-history.ts`, whose `COLLAPSE_WINDOW_MS`
+ * this replaces.
+ */
+export const COLLAPSE_WINDOW_MS = 5 * 60 * 1000;
+
+/** A side of a field change, with ABSENCE made explicit.
+ *
+ *  `hasBefore`/`hasAfter` exist because `before`/`after` can legitimately BE
+ *  `null` — a stored null and a key that was never there are different facts,
+ *  and `entry.after === undefined` collapses them. */
+export interface FoldedFieldChange {
+  hasBefore: boolean;
+  before?: unknown;
+  hasAfter: boolean;
+  after?: unknown;
+  /** Either side was too large to store, anywhere in the fold. */
+  truncated: boolean;
+  /** The per-field read gate withheld this field from this caller. */
+  withheld: boolean;
+  /** The ROW was over the byte cap: the field moved, the values are not here. */
+  omitted: boolean;
+}
+
+/**
+ * What a field entry actually says, as one word.
+ *
+ * THE ORDER IS LOAD-BEARING. `withheld` and `omitted` are checked FIRST because
+ * both arrive as `{}` — indistinguishable from each other and from a created
+ * key by shape alone, and distinguishable only by the row's `redacted_fields`
+ * and `values_omitted`. `truncated` is checked BEFORE the created/deleted
+ * inference because a truncated side's absence says nothing, so calling it a
+ * deletion would invent one.
+ */
+export type FieldChangeKind =
+  | 'withheld'
+  | 'omitted'
+  | 'truncated'
+  | 'created'
+  | 'deleted'
+  | 'updated';
+
+export function classifyFieldChange(change: FoldedFieldChange): FieldChangeKind {
+  if (change.withheld) return 'withheld';
+  if (change.omitted) return 'omitted';
+  if (change.truncated) return 'truncated';
+  if (!change.hasBefore && change.hasAfter) return 'created';
+  if (change.hasBefore && !change.hasAfter) return 'deleted';
+  return 'updated';
+}
+
+/** Whether a within-field diff can honestly be rendered for this change.
+ *
+ *  REFUSES A TRUNCATED SIDE, which is the whole point: a diff over a silently
+ *  truncated value shows a deletion that never happened. Also refuses anything
+ *  withheld or omitted (there are no values), and anything that is not text on
+ *  both sides (a line diff over a dict is noise). */
+export function canDiffFieldChange(change: FoldedFieldChange): boolean {
+  if (change.truncated || change.withheld || change.omitted) return false;
+  return typeof change.before === 'string' && typeof change.after === 'string';
+}
+
+/* -------------------------------------------------------------------------- */
+/*  READING THE WIRE                                                          */
+/* -------------------------------------------------------------------------- */
+
+/** First non-empty of several candidate spellings — the snake/camel tolerance
+ *  described in `types.ts`. */
+function pick<T>(...values: Array<T | null | undefined>): T | undefined {
+  for (const value of values) {
+    if (value !== null && value !== undefined && value !== '') return value;
+  }
+  return undefined;
+}
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : [];
+}
+
+/** The three-state kind, FAILING CLOSED.
+ *
+ *  Anything outside the vocabulary — absent, empty, a value from a future
+ *  build — reads `unknown`, and NEVER `person`. A trail that labels a machine
+ *  as your colleague is worse than no trail at all, so the floor is the state
+ *  that claims nothing. */
+export function actorKindOf(revision: EntityRevision): ActorKind {
+  const raw = pick(revision.actor_kind, revision.actorKind);
+  return raw === 'person' || raw === 'machine' ? raw : 'unknown';
+}
+
+/** Whether the kind was CLAIMED or GUESSED. `undefined` when the row does not
+ *  say, which a row from a pre-rollout build will not. */
+export function actorKindSourceOf(revision: EntityRevision): ActorKindSource | undefined {
+  const raw = pick(revision.actor_kind_source, revision.actorKindSource);
+  return raw === 'claim' || raw === 'inferred' ? raw : undefined;
+}
+
+/**
+ * One `changed` entry read into {@link FoldedFieldChange}.
+ *
+ * `'before' in entry` rather than `entry.before !== undefined`, because `null`
+ * is a legal stored value and the server never writes `after: null` to mean
+ * "deleted" — it omits the key. Collapsing the two would turn every
+ * null-valued field into a deletion.
+ */
+export function normalizeFieldChange(
+  entry: RevisionFieldChange | undefined,
+  options: { withheld?: boolean; omitted?: boolean } = {},
+): FoldedFieldChange {
+  const raw = entry && typeof entry === 'object' ? entry : {};
+  const hasBefore = Object.prototype.hasOwnProperty.call(raw, 'before');
+  const hasAfter = Object.prototype.hasOwnProperty.call(raw, 'after');
+  return {
+    hasBefore,
+    ...(hasBefore ? { before: raw.before } : {}),
+    hasAfter,
+    ...(hasAfter ? { after: raw.after } : {}),
+    truncated: raw.truncated === true,
+    withheld: options.withheld === true,
+    omitted: options.omitted === true,
+  };
+}
+
+/** An ISO instant we can actually order by, or undefined. */
+function instant(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  return Number.isNaN(Date.parse(value)) ? undefined : value;
+}
+
+/** One revision row, read defensively into a single spelling. */
+export interface NormalizedRevision {
+  id: string;
+  version: number;
+  action: string;
+  source: string;
+  precondition: string;
+  /** ISO-8601, or `''` when the row carried no readable timestamp. */
+  createdAt: string;
+  actorSub: string;
+  actorLabel: string;
+  actorKind: ActorKind;
+  actorKindSource?: ActorKindSource;
+  changed: Record<string, FoldedFieldChange>;
+  name?: FoldedFieldChange;
+  preserved: string[];
+  regenerate: string[];
+  redacted: string[];
+  valuesOmitted: boolean;
+  /** A machine ATTEMPT: something was held back and nothing moved. */
+  isAttempt: boolean;
+}
+
+export function normalizeRevision(revision: EntityRevision): NormalizedRevision {
+  const metadata = revision.metadata && typeof revision.metadata === 'object' ? revision.metadata : {};
+  const redacted = strings(pick(revision.redacted_fields, revision.redactedFields));
+  const valuesOmitted =
+    metadata.values_omitted === true || metadata.valuesOmitted === true;
+  const rawChanged =
+    metadata.changed && typeof metadata.changed === 'object' ? metadata.changed : {};
+
+  const changed: Record<string, FoldedFieldChange> = {};
+  for (const [field, entry] of Object.entries(rawChanged)) {
+    changed[field] = normalizeFieldChange(entry, {
+      withheld: redacted.includes(field),
+      omitted: valuesOmitted,
+    });
+  }
+
+  const preserved = strings(metadata.preserved);
+  return {
+    id: String(revision.id ?? ''),
+    version: typeof revision.version === 'number' ? revision.version : 0,
+    action: String(pick(revision.action) ?? 'updated'),
+    source: String(pick(revision.source) ?? ''),
+    precondition: String(pick(revision.precondition) ?? ''),
+    createdAt: instant(pick(revision.created_at, revision.createdAt)) ?? '',
+    actorSub: String(pick(revision.actor_sub, revision.actorSub) ?? ''),
+    actorLabel: String(pick(revision.actor_label, revision.actorLabel) ?? ''),
+    actorKind: actorKindOf(revision),
+    ...(actorKindSourceOf(revision) ? { actorKindSource: actorKindSourceOf(revision)! } : {}),
+    changed,
+    ...(metadata.name
+      ? { name: normalizeFieldChange(metadata.name, { omitted: valuesOmitted }) }
+      : {}),
+    preserved,
+    regenerate: strings(metadata.regenerate),
+    redacted,
+    valuesOmitted,
+    isAttempt: preserved.length > 0 && Object.keys(changed).length === 0,
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/*  THE FOLD                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/** One sitting: who, over what span, and what moved across the whole of it. */
+export interface RevisionSitting {
+  /** Stable React key — the newest folded row's id. */
+  id: string;
+  /** The rows folded in, NEWEST FIRST, so "show each save" needs no re-sort. */
+  revisions: NormalizedRevision[];
+  actorSub: string;
+  actorLabel: string;
+  actorKind: ActorKind;
+  actorKindSource?: ActorKindSource;
+  /** Version of the OLDEST row folded in. */
+  fromVersion: number;
+  /** Version of the NEWEST row folded in. */
+  toVersion: number;
+  /** When the sitting started (oldest row). */
+  from: string;
+  /** When it last saved (newest row). */
+  at: string;
+  /** How many rows folded in. At least 1. */
+  saves: number;
+  /** `created` if the sitting contains the record's creation, else the newest
+   *  row's action. */
+  action: string;
+  /** Per field: BEFORE from the oldest row that touched it, AFTER from the
+   *  newest. */
+  changed: Record<string, FoldedFieldChange>;
+  name?: FoldedFieldChange;
+  preserved: string[];
+  regenerate: string[];
+  redacted: string[];
+  valuesOmitted: boolean;
+  isAttempt: boolean;
+}
+
+/**
+ * Whether two adjacent rows are the same sitting.
+ *
+ * FOUR REFUSALS, each of which would otherwise produce a confident lie:
+ *
+ * 1. A DIFFERENT ACTOR is a different sitting, obviously — and that includes a
+ *    different ABSENCE of one, treated as its own actor rather than matching
+ *    everybody.
+ * 2. A DIFFERENT `actorKind` OR `actorKindSource` NEVER FOLDS, even when the
+ *    sub matches. During the healing window one person's rows legitimately
+ *    carry `unknown` then `person`, and folding them would stamp the whole
+ *    sitting with whichever end won — manufacturing a claim the data does not
+ *    make. bd startsim-jkkn7.2 says fail closed on absence; refusing the fold
+ *    is the honest version of that.
+ * 3. AN ATTEMPT NEVER FOLDS INTO A CHANGE. A `preserved` row records that a
+ *    machine tried to write and was held back; merging it into a row that DID
+ *    move a field would read as the attempt having succeeded, which inverts the
+ *    one fact the actor axis exists to record.
+ * 4. A CREATE NEVER ABSORBS A LATER EDIT, so "created" keeps meaning the
+ *    record's version 1 rather than "created, and then some".
+ *
+ * And the window itself is checked on the gap between the two rows, `>= 0`
+ * guarding a clock that went backwards: an out-of-order row extends the sitting
+ * rather than opening one that appears to precede it.
+ */
+function sameSitting(
+  newer: NormalizedRevision,
+  older: NormalizedRevision,
+  windowMs: number,
+): boolean {
+  if (newer.actorSub !== older.actorSub) return false;
+  if (newer.actorKind !== older.actorKind) return false;
+  if (newer.actorKindSource !== older.actorKindSource) return false;
+  if (newer.isAttempt !== older.isAttempt) return false;
+  if (older.action === 'created' || newer.action === 'created') return false;
+  if (!newer.createdAt || !older.createdAt) return false;
+  const gap = Date.parse(newer.createdAt) - Date.parse(older.createdAt);
+  return gap >= 0 && gap <= windowMs;
+}
+
+/**
+ * Merge an OLDER row's field change into a sitting that already holds the
+ * newer one.
+ *
+ * THE DIRECTION IS THE WHOLE POINT. `before` must come from the OLDEST row that
+ * touched the field and `after` from the NEWEST, so a sitting reports what the
+ * paragraph was when she sat down and what it was when she left. A naive union
+ * takes whichever side it saw last and reports an intermediate autosave as the
+ * final text — which is exactly the kind of confidently-wrong value this trail
+ * exists to replace.
+ *
+ * Flags UNION rather than overwrite: a sitting that folded one truncated,
+ * withheld or omitted row carries that forward, because a reader who is shown
+ * a clean diff built partly from a withheld row has been told something false.
+ */
+function mergeOlder(into: FoldedFieldChange, older: FoldedFieldChange): FoldedFieldChange {
+  return {
+    // BEFORE moves back to the older row's.
+    hasBefore: older.hasBefore,
+    ...(older.hasBefore ? { before: older.before } : {}),
+    // AFTER stays with the newer row's.
+    hasAfter: into.hasAfter,
+    ...(into.hasAfter ? { after: into.after } : {}),
+    truncated: into.truncated || older.truncated,
+    withheld: into.withheld || older.withheld,
+    omitted: into.omitted || older.omitted,
+  };
+}
+
+function startSitting(revision: NormalizedRevision): RevisionSitting {
+  return {
+    id: revision.id,
+    revisions: [revision],
+    actorSub: revision.actorSub,
+    actorLabel: revision.actorLabel,
+    actorKind: revision.actorKind,
+    ...(revision.actorKindSource ? { actorKindSource: revision.actorKindSource } : {}),
+    fromVersion: revision.version,
+    toVersion: revision.version,
+    from: revision.createdAt,
+    at: revision.createdAt,
+    saves: 1,
+    action: revision.action,
+    changed: { ...revision.changed },
+    ...(revision.name ? { name: revision.name } : {}),
+    preserved: [...revision.preserved],
+    regenerate: [...revision.regenerate],
+    redacted: [...revision.redacted],
+    valuesOmitted: revision.valuesOmitted,
+    isAttempt: revision.isAttempt,
+  };
+}
+
+function absorb(sitting: RevisionSitting, older: NormalizedRevision): void {
+  sitting.revisions.push(older);
+  sitting.saves += 1;
+  sitting.fromVersion = older.version;
+  sitting.from = older.createdAt || sitting.from;
+  if (older.action === 'created') sitting.action = 'created';
+
+  for (const [field, change] of Object.entries(older.changed)) {
+    sitting.changed[field] = sitting.changed[field]
+      ? mergeOlder(sitting.changed[field]!, change)
+      : change;
+  }
+  if (older.name) {
+    sitting.name = sitting.name ? mergeOlder(sitting.name, older.name) : older.name;
+  }
+  const union = (a: string[], b: string[]) => [...new Set([...a, ...b])].sort();
+  sitting.preserved = union(sitting.preserved, older.preserved);
+  sitting.regenerate = union(sitting.regenerate, older.regenerate);
+  sitting.redacted = union(sitting.redacted, older.redacted);
+  sitting.valuesOmitted = sitting.valuesOmitted || older.valuesOmitted;
+}
+
+/**
+ * Fold a NEWEST-FIRST page of revisions into sittings, newest first.
+ *
+ * Takes the rows exactly as the endpoint ordered them (`-version`, then
+ * `-created_at`) and folds only ADJACENT rows, so the result stays in the
+ * server's order and no row is reordered on the strength of a timestamp.
+ *
+ * FOLD OVER THE ACCUMULATED PAGES, NOT PER PAGE. The panel loads pages with
+ * `useInfiniteQuery` and folds the flattened array, which is why a sitting
+ * straddling a page boundary is folded once rather than appearing as "3 saves"
+ * followed by "2 saves". Calling this per page would be wrong and silently so.
+ */
+export function foldRevisions(
+  revisions: EntityRevision[],
+  windowMs: number = COLLAPSE_WINDOW_MS,
+): RevisionSitting[] {
+  const rows = (revisions ?? []).map(normalizeRevision);
+  const out: RevisionSitting[] = [];
+  for (const row of rows) {
+    const open = out[out.length - 1];
+    // `open.revisions[open.revisions.length - 1]` is the OLDEST row folded so
+    // far, which is the one this (older still) row is adjacent to.
+    const tail = open?.revisions[open.revisions.length - 1];
+    if (open && tail && sameSitting(tail, row, windowMs)) {
+      absorb(open, row);
+    } else {
+      out.push(startSitting(row));
+    }
+  }
+  return out;
+}
+
+/**
+ * What the sitting collapsed, in words.
+ *
+ * A COLLAPSED SITTING MUST SAY IT IS A COLLAPSE. A bare timestamp over twelve
+ * folded saves quietly claims a precision it does not have — the reader should
+ * be able to see that this was a sitting, not a keystroke. Locale-free on
+ * purpose: the absolute time is rendered by the row, this is only the shape of
+ * the sitting.
+ */
+export function sittingSummary(sitting: RevisionSitting): string {
+  if (sitting.saves <= 1) return '1 save';
+  const minutes = Math.floor((Date.parse(sitting.at) - Date.parse(sitting.from)) / 60_000);
+  return minutes >= 1 ? `${sitting.saves} saves over ${minutes} min` : `${sitting.saves} saves`;
+}
+
+/** The fields a sitting touched, in a stable order, so two renders of the same
+ *  sitting never disagree about which field comes first. */
+export function sittingFields(sitting: RevisionSitting): string[] {
+  return Object.keys(sitting.changed).sort();
+}
+
+/** "a", "a and b", "a, b and c" — an Oxford-free list, because these are field
+ *  names in a sentence and not prose. */
+export function joinNames(names: string[]): string {
+  if (names.length === 0) return '';
+  if (names.length === 1) return names[0]!;
+  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+}
+
+/**
+ * The sitting's headline — one line that says what happened.
+ *
+ * AN ATTEMPT GETS ITS OWN SENTENCE, and it is the sentence nobody could produce
+ * when the 41 machine-written notes could not be cleaned up: "tried to write
+ * team_verdict — held back". It must never read as a change, because the record
+ * did not move; what happened is that a machine was stopped.
+ *
+ * Beyond about three fields the names stop helping and the count starts: a
+ * headline listing nine attribute names is not scannable, and the full list is
+ * one row down anyway.
+ */
+export function sittingHeadline(
+  sitting: RevisionSitting,
+  fieldLabel: (field: string) => string = (field) => field,
+): string {
+  if (sitting.isAttempt) {
+    const names = joinNames(sitting.preserved.map(fieldLabel));
+    return names ? `Tried to write ${names} — held back` : 'A write was held back';
+  }
+  const fields = sittingFields(sitting);
+  const renamed = sitting.name !== undefined;
+  if (sitting.action === 'created') {
+    return fields.length ? `Created the record with ${fields.length} ${fields.length === 1 ? 'field' : 'fields'}` : 'Created the record';
+  }
+  if (!fields.length) return renamed ? 'Renamed the record' : 'Saved the record';
+  const named =
+    fields.length <= 3
+      ? `Edited ${joinNames(fields.map(fieldLabel))}`
+      : `Edited ${fields.length} fields`;
+  return renamed ? `${named}, and renamed it` : named;
+}

package/src/components/history/text-diff.ts

@@ -0,0 +1,139 @@
+/**
+ * Turn two revisions of one text field into a git-style unified diff string
+ * (bd startsim-g4rwo; originally marketing-agents-web `src/lib/blog-diff.ts`,
+ * bd 768w.16.10.5).
+ *
+ * This is what makes the epic's answer to "which paragraph moved" nearly free
+ * rather than a second build: {@link DiffViewer} already renders a RAW unified
+ * diff (it splits on `diff --git` headers, colourises `@@` hunks and `+`/`-`
+ * lines) and does no diffing itself, so showing a field against its previous
+ * value only needs that string synthesised from the two values. Pure and
+ * line-based (LCS), so it unit-tests without a backend and adds no dependency.
+ *
+ * RENAMED FROM `blog-diff` / `unifiedBlogDiff` ON THE WAY IN, deliberately.
+ * The algorithm never knew what a blog was — it takes two strings and a path
+ * label — and `packages/ui` is consumed by every foundry fork, most of which
+ * have no blogs. A shared module carrying one tenant's vocabulary is how
+ * surfaces end up unable to reuse it. `path` is what names the field in the
+ * rendered header, so a caller passes the field's own name.
+ *
+ * DO NOT CALL THIS ON A TRUNCATED SIDE. A diff over a silently truncated value
+ * shows a deletion that never happened; `canDiffFieldChange` in
+ * `revision-history.ts` is the gate, and the panel says why it refused rather
+ * than rendering nothing.
+ *
+ * The algorithm: an LCS edit script over lines, grouped into hunks with a few
+ * lines of surrounding context (like `git diff -U<n>`). Identical inputs yield
+ * '' so the viewer shows its own empty state rather than an all-context block.
+ */
+
+type Op = { type: 'eq' | 'del' | 'ins'; line: string };
+
+/** Split into lines, tolerating CRLF and a trailing newline (no phantom last line). */
+function toLines(text: string): string[] {
+  if (text === '') return [];
+  return text.replace(/\r\n/g, '\n').replace(/\n$/, '').split('\n');
+}
+
+/**
+ * A minimal LCS edit script between two line arrays. O(n*m) DP — a record field is a
+ * few hundred lines at most. Returns ops in output order: equal/deleted/inserted.
+ */
+export function diffLines(oldLines: string[], newLines: string[]): Op[] {
+  const n = oldLines.length;
+  const m = newLines.length;
+  // lcs[i][j] = LCS length of oldLines[i:] and newLines[j:].
+  const lcs: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      lcs[i][j] =
+        oldLines[i] === newLines[j]
+          ? lcs[i + 1][j + 1] + 1
+          : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+
+  const ops: Op[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (oldLines[i] === newLines[j]) {
+      ops.push({ type: 'eq', line: oldLines[i] });
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      ops.push({ type: 'del', line: oldLines[i] });
+      i++;
+    } else {
+      ops.push({ type: 'ins', line: newLines[j] });
+      j++;
+    }
+  }
+  while (i < n) ops.push({ type: 'del', line: oldLines[i++] });
+  while (j < m) ops.push({ type: 'ins', line: newLines[j++] });
+  return ops;
+}
+
+/** A prefixed diff body line: ' ' context, '-' deletion, '+' insertion. */
+function prefixed(op: Op): string {
+  const mark = op.type === 'eq' ? ' ' : op.type === 'del' ? '-' : '+';
+  return `${mark}${op.line}`;
+}
+
+/**
+ * Build the unified diff of two text values as a single-file `diff --git` block the
+ * DiffViewer can render. `context` is the number of unchanged lines kept around
+ * each change (git's default 3). Returns '' when the bodies are identical.
+ */
+export function unifiedTextDiff(
+  oldText: string,
+  newText: string,
+  path = 'value.txt',
+  context = 3,
+): string {
+  if (oldText === newText) return '';
+  const ops = diffLines(toLines(oldText), toLines(newText));
+  if (!ops.some((op) => op.type !== 'eq')) return '';
+
+  // Indices of ops that are actual changes, expanded by `context` on each side and
+  // merged into contiguous hunk ranges.
+  const changed: number[] = [];
+  ops.forEach((op, idx) => {
+    if (op.type !== 'eq') changed.push(idx);
+  });
+
+  const ranges: Array<[number, number]> = [];
+  for (const idx of changed) {
+    const start = Math.max(0, idx - context);
+    const end = Math.min(ops.length - 1, idx + context);
+    const last = ranges[ranges.length - 1];
+    if (last && start <= last[1] + 1) {
+      last[1] = Math.max(last[1], end);
+    } else {
+      ranges.push([start, end]);
+    }
+  }
+
+  const lines: string[] = [`diff --git a/${path} b/${path}`];
+  for (const [start, end] of ranges) {
+    // 1-based line numbers of the hunk's first old/new line.
+    let oldStart = 1;
+    let newStart = 1;
+    for (let k = 0; k < start; k++) {
+      if (ops[k].type !== 'ins') oldStart++;
+      if (ops[k].type !== 'del') newStart++;
+    }
+    let oldCount = 0;
+    let newCount = 0;
+    const body: string[] = [];
+    for (let k = start; k <= end; k++) {
+      const op = ops[k];
+      if (op.type !== 'ins') oldCount++;
+      if (op.type !== 'del') newCount++;
+      body.push(prefixed(op));
+    }
+    lines.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+    lines.push(...body);
+  }
+  return lines.join('\n');
+}