@startsimpli/ui 0.4.134 → 0.4.136

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

@@ -0,0 +1,59 @@
+/**
+ * Ported from marketing-agents-web `src/lib/__tests__/blog-diff.test.ts` with
+ * the module (bd startsim-g4rwo). Same assertions, jest instead of vitest, and
+ * the generic `unifiedTextDiff` name — see `text-diff.ts` on the rename.
+ */
+import { parseDiffFiles } from '../../diff'
+import { diffLines, unifiedTextDiff } from '../text-diff'
+
+describe('diffLines', () => {
+  it('marks equal / deleted / inserted lines in output order', () => {
+    expect(diffLines(['a', 'b', 'c'], ['a', 'x', 'c'])).toEqual([
+      { type: 'eq', line: 'a' },
+      { type: 'del', line: 'b' },
+      { type: 'ins', line: 'x' },
+      { type: 'eq', line: 'c' },
+    ])
+  })
+})
+
+describe('unifiedTextDiff', () => {
+  it('returns "" for identical values', () => {
+    expect(unifiedTextDiff('same\ntext', 'same\ntext')).toBe('')
+  })
+
+  it('emits a git-style block the shared DiffViewer parser can read', () => {
+    const diff = unifiedTextDiff(
+      'Line one\nLine two\nLine three',
+      'Line one\nLine 2\nLine three',
+      'blog',
+    )
+    expect(diff).toContain('diff --git a/blog b/blog')
+    expect(diff).toMatch(/^@@ -\d+,\d+ \+\d+,\d+ @@$/m)
+    expect(diff).toContain('-Line two')
+    expect(diff).toContain('+Line 2')
+    const files = parseDiffFiles(diff)
+    expect(files).toHaveLength(1)
+    expect(files[0]!.filePath).toBe('blog')
+  })
+
+  it('keeps context lines but not the whole document', () => {
+    const oldText = Array.from({ length: 20 }, (_, i) => `line ${i}`).join('\n')
+    const newText = oldText.replace('line 10', 'LINE TEN')
+    const body = unifiedTextDiff(oldText, newText)
+      .split('\n')
+      .filter((l) => /^[ +-]/.test(l) && !l.startsWith('+++') && !l.startsWith('---'))
+    expect(body).toContain('-line 10')
+    expect(body).toContain('+LINE TEN')
+    expect(body).toContain(' line 7')
+    expect(body).not.toContain(' line 0')
+  })
+
+  it('names the field in the header, so the rendered diff says what moved', () => {
+    expect(unifiedTextDiff('a', 'b', 'linkedin')).toContain('diff --git a/linkedin b/linkedin')
+  })
+
+  it('tolerates CRLF and a trailing newline without inventing a last line', () => {
+    expect(unifiedTextDiff('a\r\nb\r\n', 'a\nb\n')).toBe('')
+  })
+})

package/src/components/history/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @startsimpli/ui/history — the shared record history panel (bd startsim-g4rwo).
+ *
+ * "Who edited what piece of the text and when", over the append-only revision
+ * trail (bd startsim-o1qib). A page-level composer plus the pure helpers it
+ * folds with, so a foundry fork holds an injected client and its theme
+ * classNames rather than its own timeline, its own fold and its own idea of
+ * what `{}` means (rule #9).
+ *
+ * THE ONE THING A CONSUMER MUST NOT GET WRONG: `actorKind` is THREE-state, and
+ * `unknown` is the common case for genuine human edits for up to 14 days after
+ * rollout. Render it through this panel — or through `ActorIdentity` with
+ * `kind`/`kindSource` — rather than deciding locally, because "absent" read as
+ * "a machine did this" is the single worst failure available here.
+ */
+export { RecordHistoryPanel, REVISION_ENTRY_TYPES } from './RecordHistoryPanel';
+export type { RecordHistoryPanelProps } from './RecordHistoryPanel';
+
+export { RevisionFields } from './RevisionFields';
+export type { RevisionFieldsProps } from './RevisionFields';
+
+export {
+  RECORD_HISTORY_PANEL_DEFAULTS,
+  type RecordHistoryPanelClassNames,
+} from './record-history-panel-default-class-names';
+
+export {
+  COLLAPSE_WINDOW_MS,
+  actorKindOf,
+  actorKindSourceOf,
+  canDiffFieldChange,
+  classifyFieldChange,
+  foldRevisions,
+  joinNames,
+  normalizeFieldChange,
+  normalizeRevision,
+  sittingFields,
+  sittingHeadline,
+  sittingSummary,
+} from './revision-history';
+export type {
+  FieldChangeKind,
+  FoldedFieldChange,
+  NormalizedRevision,
+  RevisionSitting,
+} from './revision-history';
+
+export { diffLines, unifiedTextDiff } from './text-diff';
+
+export type {
+  ActorKind,
+  ActorKindSource,
+  EntityRevision,
+  RevisionAction,
+  RevisionClient,
+  RevisionFieldChange,
+  RevisionMetadata,
+  RevisionPage,
+  RevisionPrecondition,
+  RevisionQuery,
+  RevisionSource,
+} from './types';

package/src/components/history/record-history-panel-default-class-names.ts

@@ -0,0 +1,29 @@
+/** Default Tailwind classes for {@link RecordHistoryPanel}. bd startsim-g4rwo.
+ *  Semantic tokens only (startsim-1f3n) — theme-driven, dark-mode safe, and no
+ *  literal colour, so a dark tenant theme recolours this without a fork. */
+
+export interface RecordHistoryPanelClassNames {
+  root?: string;
+  header?: string;
+  heading?: string;
+  title?: string;
+  description?: string;
+  body?: string;
+  /** The panel-level sentences: the unrecorded-kind explanation, the redaction
+   *  notice and the "some write paths are not recorded" caveat. */
+  notice?: string;
+  footer?: string;
+  countLine?: string;
+}
+
+export const RECORD_HISTORY_PANEL_DEFAULTS: Required<RecordHistoryPanelClassNames> = {
+  root: 'rounded-lg border border-border bg-card',
+  header: 'flex flex-wrap items-start justify-between gap-2 border-b border-border px-5 py-3',
+  heading: 'space-y-1',
+  title: 'font-medium text-foreground',
+  description: 'text-xs text-muted-foreground',
+  body: 'max-h-[32rem] overflow-y-auto px-5 py-4',
+  notice: 'border-b border-border px-5 py-2 text-xs text-muted-foreground',
+  footer: 'border-t border-border px-5 py-3 text-sm',
+  countLine: 'border-t border-border px-5 py-2 text-xs text-muted-foreground',
+};

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