@startsimpli/ui 0.4.142 → 0.4.143

package/src/components/track-changes/types.ts

@@ -0,0 +1,373 @@
+/**
+ * @startsimpli/ui/track-changes — the shapes the track-changes editor surface
+ * reads and the one call it writes (bd startsim-sjuai; design startsim-xyn25).
+ *
+ * THE FIELD STAYS A PLAIN STRING. Suggestions and comments are separate server
+ * rows anchored to character offsets of that string at a known version, and
+ * blame is derived server-side from the revision chain. The editor renders all
+ * three as DECORATIONS over the stored string and never writes a mark into it.
+ *
+ * STRUCTURAL ON PURPOSE, like `history/types.ts`: packages/ui imports no API
+ * client. The consuming app injects its own authed client
+ * ({@link TrackChangesClient}). Both spellings of every key are declared
+ * because the shared API client camelCases responses recursively; the
+ * normalizers in `normalize.ts` read either.
+ *
+ * ── OFFSET UNITS ────────────────────────────────────────────────────────────
+ * The server is Python, so its string offsets count CODE POINTS. The editor is
+ * JavaScript, so its offsets count UTF-16 CODE UNITS. They differ by one for
+ * every character outside the Basic Multilingual Plane before the offset, and
+ * LinkedIn posts are full of emoji. `offset_unit` on a response says which unit
+ * it uses; absent means `code_point`. The normalizers convert at the boundary,
+ * so everything past them is UTF-16.
+ *
+ * ── STATUS OF THESE SHAPES ──────────────────────────────────────────────────
+ * All three follow the FINAL contracts: blame start-simpli-api #507
+ * (startsim-gulrr), suggestions and comments #508 (startsim-txfrl,
+ * startsim-a76zp). Every response declares `offset_unit: "utf16"` and the
+ * `version` its positions were mapped to; suggestions and comments carry a
+ * nested `author` and a `position {state, from, to, version}` (null when not
+ * placed); blame spans carry flat actor columns, and an unknown span carries
+ * `via: "unknown"`, a `reason` code and a `detail` sentence. Older spellings
+ * the normalizer still reads are kept only so a camelising client works.
+ */
+import type { ActorKind, ActorKindSource } from '../ActorIdentity';
+
+export type { ActorKind, ActorKindSource };
+
+/** Which unit a response's offsets count. */
+export type OffsetUnit = 'code_point' | 'utf16';
+
+/** The actor columns every annotation and blame span carries, both spellings. */
+export interface WireActor {
+  actor_sub?: string | null;
+  actorSub?: string | null;
+  actor_label?: string | null;
+  actorLabel?: string | null;
+  actor_kind?: ActorKind | string | null;
+  actorKind?: ActorKind | string | null;
+  actor_kind_source?: ActorKindSource | string | null;
+  actorKindSource?: ActorKindSource | string | null;
+}
+
+/** The nested actor object the suggestion and comment routes answer with
+ *  (start-simpli-api RED branch feat/tc-suggestions-comments): `author`,
+ *  `resolution.by`. */
+export interface WireAuthor {
+  sub?: string | null;
+  label?: string | null;
+  kind?: ActorKind | string | null;
+  kind_source?: ActorKindSource | string | null;
+  kindSource?: ActorKindSource | string | null;
+}
+
+/** Where the server mapped an anchor to on read: current-version offsets and
+ *  the mapping's outcome. `from`/`to` are `null` when orphaned. */
+export interface PositionWire {
+  from?: number | null;
+  to?: number | null;
+  state?: AnchorState | string | null;
+  /** The record version the position was mapped to. */
+  version?: number | null;
+}
+
+/** An actor after normalization. `label` may be `''` (a service token can carry
+ *  no email); `kind` is three-state and `unknown` is calm, not a defect. */
+export interface TrackActor {
+  sub: string;
+  label: string;
+  kind: ActorKind;
+  kindSource?: ActorKindSource;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  BLAME  GET /api/v1/entities/<id>/blame/?field=<f>   (startsim-gulrr)      */
+/* -------------------------------------------------------------------------- */
+
+/** How a span's text got there. `restore` credits the restorer; an accepted
+ *  suggestion credits its AUTHOR, with `accepted_by` the acceptor; `unknown`
+ *  spans carry a `reason` and no actor at all. */
+export type BlameVia = 'edit' | 'accepted_suggestion' | 'restore' | 'unknown';
+
+/** Why nobody can be credited with a span. */
+export type BlameReason = 'before_history' | 'truncated' | 'values_omitted' | 'chain_break' | 'unrecorded_change';
+
+/**
+ * One span of GET /api/v1/entities/<id>/blame/?field=<f> (start-simpli-api
+ * #507, final contract in startsim-gulrr). Spans are contiguous, non-empty,
+ * in order and cover the whole text. Author columns are FLAT on a known span;
+ * an unknown span has none of them.
+ */
+export interface BlameSpanWire extends WireActor {
+  from: number;
+  to: number;
+  via?: BlameVia | string | null;
+  /** `null` on an unknown span that no revision touched. */
+  version?: number | null;
+  at?: string | null;
+  /** accepted_suggestion only: the ACCEPTOR, with actor_* keys. */
+  accepted_by?: WireActor | null;
+  acceptedBy?: WireActor | null;
+  suggestion_id?: string | null;
+  set_id?: string | null;
+  /** restore only. */
+  restored_from?: number | null;
+  restoredFrom?: number | null;
+  /** unknown only. */
+  reason?: BlameReason | string | null;
+  /** unknown only: a readable sentence. */
+  detail?: string | null;
+}
+
+export interface BlameResponseWire {
+  entity_id?: string;
+  field?: string;
+  /** The record's current version; the spans describe its text. */
+  version?: number | null;
+  /** Always "utf16" on this route. */
+  offset_unit?: OffsetUnit | null;
+  offsetUnit?: OffsetUnit | null;
+  /** UTF-16 length of the current text. */
+  length?: number | null;
+  /** False when the type's history is off: then `spans` is null and
+   *  `detail` says why. */
+  recorded?: boolean | null;
+  history?: { enabled?: boolean; declared_by?: string } | null;
+  trail_starts?: { version?: number; at?: string; from_creation?: boolean } | null;
+  spans?: BlameSpanWire[] | null;
+  detail?: string | null;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  SUGGESTIONS  GET/POST /api/v1/entities/<id>/suggestions/  (startsim-txfrl) */
+/* -------------------------------------------------------------------------- */
+
+export type SuggestionStatus = 'open' | 'accepted' | 'rejected' | 'withdrawn' | 'superseded';
+
+/** Where an anchor landed after the server mapped it to the current version
+ *  (design section c). An orphaned anchor is NEVER painted at a guessed place. */
+export type AnchorState = 'mapped' | 'reanchored' | 'orphaned';
+
+export interface AnchorWire {
+  from: number;
+  to: number;
+  quote?: string | null;
+  prefix?: string | null;
+  suffix?: string | null;
+}
+
+export interface SuggestionWire extends WireActor {
+  id: string;
+  /** The author, as the RED contract nests it. Flat actor columns are read
+   *  as a fallback. */
+  author?: WireAuthor | null;
+  /** The anchor mapped to the CURRENT version, with its state. Preferred
+   *  over every other spelling below. */
+  position?: PositionWire | null;
+  set_id?: string | null;
+  setId?: string | null;
+  field?: string | null;
+  base_version?: number | null;
+  baseVersion?: number | null;
+  /** The anchor as PROPOSED, against `base_version`. */
+  anchor?: AnchorWire | null;
+  /** ASSUMED: the anchor mapped to the CURRENT version on read. Also read:
+   *  `current`, `mappedAnchor`. When absent, `anchor` is taken to already be
+   *  in current-version offsets. */
+  mapped_anchor?: AnchorWire | null;
+  mappedAnchor?: AnchorWire | null;
+  current?: AnchorWire | null;
+  replacement?: string | null;
+  /** The fold of the suggestion's events. Absent means `open`. */
+  status?: SuggestionStatus | string | null;
+  /** ASSUMED name. Also read: `anchorStatus`, `anchor_state`, `mapping`. */
+  anchor_status?: AnchorState | string | null;
+  anchorStatus?: AnchorState | string | null;
+  created_at?: string | null;
+  createdAt?: string | null;
+  /** How a closed suggestion was closed: who, when, and (accepted) the
+   *  revision it produced. Null while open. */
+  resolution?: ResolutionWire | null;
+}
+
+export interface ResolutionWire {
+  action?: string | null;
+  by?: WireAuthor | null;
+  at?: string | null;
+  reason?: string | null;
+  revision?: number | null;
+}
+
+export interface SuggestionPageWire {
+  version?: number | null;
+  next?: string | null;
+  next_cursor?: string | null;
+  nextCursor?: string | null;
+  results?: SuggestionWire[] | null;
+  offset_unit?: OffsetUnit | null;
+  offsetUnit?: OffsetUnit | null;
+}
+
+/** The suggesting-mode post (design section d): the WHOLE proposed text; the
+ *  server hunks it with the shared word diff and supersedes this author's own
+ *  still-open set. */
+export interface ProposeRequest {
+  field: string;
+  base_version: number;
+  proposed: string;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  COMMENTS  GET /api/v1/entities/<id>/comments/?field=<f>  (startsim-a76zp) */
+/* -------------------------------------------------------------------------- */
+
+export interface CommentWire extends WireActor {
+  id: string;
+  thread_id?: string | null;
+  author?: WireAuthor | null;
+  edited_at?: string | null;
+  editedAt?: string | null;
+  /** Mentioned subs. Shown in-app only; nothing is emailed (Quinn). */
+  mentions?: string[] | null;
+  body?: string | null;
+  created_at?: string | null;
+  createdAt?: string | null;
+  /** Tombstoned: the fact of the comment stays, the body is gone. */
+  deleted?: boolean | null;
+}
+
+export interface CommentThreadWire extends WireActor {
+  /** Also read: `id`. */
+  thread_id?: string | null;
+  threadId?: string | null;
+  id?: string | null;
+  field?: string | null;
+  anchor?: AnchorWire | null;
+  mapped_anchor?: AnchorWire | null;
+  mappedAnchor?: AnchorWire | null;
+  current?: AnchorWire | null;
+  anchor_status?: AnchorState | string | null;
+  anchorStatus?: AnchorState | string | null;
+  position?: PositionWire | null;
+  author?: WireAuthor | null;
+  /** `open` | `resolved`. `resolved: true` also read. */
+  status?: string | null;
+  resolution?: ResolutionWire | null;
+  base_version?: number | null;
+  created_at?: string | null;
+  resolved?: boolean | null;
+  comments?: CommentWire[] | null;
+  /** The body withheld by the per-field read gate. */
+  redacted?: boolean | null;
+}
+
+export interface CommentPageWire {
+  version?: number | null;
+  next?: string | null;
+  next_cursor?: string | null;
+  nextCursor?: string | null;
+  results?: CommentThreadWire[] | null;
+  offset_unit?: OffsetUnit | null;
+  offsetUnit?: OffsetUnit | null;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  THE INJECTED CLIENT                                                       */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * What the editor surface needs from the server, and nothing it does not.
+ * The consuming app binds the record id:
+ *
+ * ```ts
+ * const client: TrackChangesClient = {
+ *   blame: (q) => api.entities.blame(id, q),
+ *   listSuggestions: (q) => api.entities.suggestions(id, q),
+ *   listComments: (q) => api.entities.comments(id, q),
+ *   propose: (body) => api.entities.propose(id, body),
+ * };
+ * ```
+ *
+ * Every read is optional so a host can mount the editor before a route ships.
+ * Accept, reject, reply and resolve are the rail's (startsim-whwxd.3), which
+ * extends this interface rather than declaring a second one.
+ *
+ * A 404 from any read means the caller may not read the record or the field.
+ * The editor says so; it never treats it as "no annotations".
+ */
+export interface TrackChangesClient {
+  blame?: (query: { field: string }) => Promise<BlameResponseWire>;
+  /** Keyset-paginated: the hook passes `cursor` (the previous page's
+   *  `next_cursor`) until there is none, because a proposal supersedes ALL of
+   *  the author's open suggestions and the editor must know every one. */
+  listSuggestions?: (query: { field: string; cursor?: string }) => Promise<SuggestionPageWire | SuggestionWire[]>;
+  listComments?: (query: { field: string; cursor?: string }) => Promise<CommentPageWire | CommentThreadWire[]>;
+  propose?: (body: ProposeRequest) => Promise<unknown>;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  NORMALIZED SHAPES (UTF-16 offsets into the stored string)                 */
+/* -------------------------------------------------------------------------- */
+
+export interface BlameSpan {
+  /** Stable within one response: `blame:<from>`. */
+  id: string;
+  from: number;
+  to: number;
+  /** `null` for an unknown span. */
+  author: TrackActor | null;
+  /** Set when nobody can be credited: the sentence a reader is shown. */
+  unknownReason: string | null;
+  /** The machine-readable reason code of an unknown span. */
+  reason: BlameReason | null;
+  version: number | null;
+  at: string | null;
+  via: BlameVia | null;
+  acceptedBy: TrackActor | null;
+  restoredFrom: number | null;
+}
+
+export interface Suggestion {
+  id: string;
+  setId: string | null;
+  from: number;
+  to: number;
+  /** The text the suggestion replaces (empty for a pure insert). */
+  quote: string;
+  /** The text it proposes (empty for a pure delete). */
+  replacement: string;
+  status: SuggestionStatus;
+  anchorState: AnchorState;
+  author: TrackActor;
+  createdAt: string | null;
+}
+
+export interface TrackComment {
+  id: string;
+  body: string | null;
+  deleted: boolean;
+  author: TrackActor;
+  createdAt: string | null;
+}
+
+export interface CommentThread {
+  id: string;
+  /** `null` for a whole-record or whole-field comment. */
+  from: number | null;
+  to: number | null;
+  quote: string;
+  anchorState: AnchorState;
+  resolved: boolean;
+  redacted: boolean;
+  comments: TrackComment[];
+}
+
+/** What a selection becomes when a host anchors a comment to it. UTF-16
+ *  offsets; convert with `toServerOffsets` before posting. */
+export interface SelectionAnchor {
+  from: number;
+  to: number;
+  quote: string;
+  prefix: string;
+  suffix: string;
+}

package/src/components/track-changes/useTrackChanges.ts

@@ -0,0 +1,214 @@
+'use client';
+
+/**
+ * useTrackChanges — the ONE owner of the injected client for a tracked field
+ * (bd startsim-sjuai).
+ *
+ * It reads blame, suggestions and comments for one field at one version,
+ * normalizes them against the stored text (UTF-16 offsets, both spellings),
+ * and posts suggesting-mode proposals. The editor is presentational over its
+ * result, and the changes rail (startsim-whwxd.3) reads the SAME result, so
+ * the rail and the editor can never show two different sets of suggestions or
+ * fetch them twice.
+ *
+ * HONEST STATES. A read that fails is not an empty list: it lands in `notices`
+ * as a sentence the host shows. A 404 means the reader may not see this
+ * record or field (the routes are nested under the record's gate). A response
+ * for a version other than the one loaded is held back rather than painted,
+ * because its offsets describe different text.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { blameNotice, normalizeBlame, normalizeSuggestions, normalizeThreads } from './normalize';
+import type {
+  BlameResponseWire,
+  BlameSpan,
+  CommentPageWire,
+  CommentThread,
+  CommentThreadWire,
+  Suggestion,
+  SuggestionPageWire,
+  SuggestionWire,
+  TrackChangesClient,
+} from './types';
+
+export type SourceState = 'off' | 'loading' | 'ready' | 'error';
+
+export interface SourceStatus {
+  state: SourceState;
+  /** A sentence for the reader when `state` is `error`. */
+  message?: string;
+}
+
+export interface UseTrackChangesOptions {
+  client: TrackChangesClient;
+  /** The record's field, as declared (`blog`, `linkedin`). */
+  field: string;
+  /** The stored value at `version`: the text every offset refers to. */
+  value: string;
+  /** The record version `value` was read at; `null` before the record has
+   *  one (then nothing is read and nothing can be proposed). */
+  version: number | null;
+  /** Off: read nothing (e.g. while the record is loading). Default on. */
+  enabled?: boolean;
+}
+
+export interface TrackChanges {
+  blame: BlameSpan[];
+  suggestions: Suggestion[];
+  threads: CommentThread[];
+  status: { blame: SourceStatus; suggestions: SourceStatus; comments: SourceStatus };
+  /** One sentence per source that could not be read. Never empty-by-failure. */
+  notices: string[];
+  /** Re-read all three (after an accept, a reply, a resolve). */
+  reload: () => void;
+  /** Post the whole proposed text against `version`. Rejects on failure, so
+   *  the editor keeps the proposal and says it was not sent. */
+  propose: (proposed: string, baseVersion: number) => Promise<void>;
+}
+
+interface Loaded<T> {
+  status: SourceStatus;
+  data: T | null;
+}
+
+const OFF: Loaded<never> = { status: { state: 'off' }, data: null };
+
+function statusCode(err: unknown): number | undefined {
+  const e = err as { status?: unknown; response?: { status?: unknown } } | null;
+  const s = e?.status ?? e?.response?.status;
+  return typeof s === 'number' ? s : undefined;
+}
+
+function detail(err: unknown): string {
+  const e = err as { body?: { detail?: unknown }; data?: { detail?: unknown }; message?: unknown } | null;
+  const d = e?.body?.detail ?? e?.data?.detail ?? e?.message;
+  return typeof d === 'string' && d.trim() ? d.trim() : 'the server did not say why';
+}
+
+function failure(what: string, err: unknown): SourceStatus {
+  // 404: the record is unreadable. 403: the field is withheld from this
+  // reader (the contract refuses narrowing to a withheld field).
+  const code = statusCode(err);
+  if (code === 404 || code === 403) {
+    return { state: 'error', message: `You cannot see ${what} for this field.` };
+  }
+  return { state: 'error', message: `Could not load ${what}: ${detail(err)}.` };
+}
+
+function versionOf(w: unknown): number | null {
+  if (!w || Array.isArray(w) || typeof w !== 'object') return null;
+  const v = (w as { version?: unknown }).version;
+  return typeof v === 'number' ? v : null;
+}
+
+/** A response is used only if it describes the loaded version (or says
+ *  nothing about versions at all). */
+function matches(w: unknown, version: number | null): boolean {
+  const v = versionOf(w);
+  return v == null || v === version;
+}
+
+type Paged<T> = { results?: T[] | null; next_cursor?: string | null; nextCursor?: string | null } | T[];
+
+/** Read every page, following `next_cursor`, into one page. Stops if the
+ *  server hands back a cursor it already gave (a loop, not more data). */
+function allPages<T, P extends Paged<T>>(
+  fn: (q: { field: string; cursor?: string }) => Promise<P>,
+): (q: { field: string }) => Promise<P> {
+  return async ({ field }) => {
+    const first = await fn({ field });
+    if (Array.isArray(first)) return first;
+    const all: T[] = [...(first.results ?? [])];
+    const seen = new Set<string>();
+    let cursor = first.next_cursor ?? first.nextCursor ?? null;
+    while (cursor && !seen.has(cursor)) {
+      seen.add(cursor);
+      const page = await fn({ field, cursor });
+      if (Array.isArray(page)) {
+        all.push(...(page as T[]));
+        break;
+      }
+      all.push(...(page.results ?? []));
+      cursor = page.next_cursor ?? page.nextCursor ?? null;
+    }
+    return { ...first, results: all, next_cursor: null, nextCursor: null };
+  };
+}
+
+export function useTrackChanges({
+  client,
+  field,
+  value,
+  version,
+  enabled = true,
+}: UseTrackChangesOptions): TrackChanges {
+  const [blame, setBlame] = useState<Loaded<BlameResponseWire>>(OFF);
+  const [sugg, setSugg] = useState<Loaded<SuggestionPageWire | SuggestionWire[]>>(OFF);
+  const [comm, setComm] = useState<Loaded<CommentPageWire | CommentThreadWire[]>>(OFF);
+  const [tick, setTick] = useState(0);
+  const clientRef = useRef(client);
+  clientRef.current = client;
+
+  useEffect(() => {
+    if (!enabled || version == null) {
+      setBlame(OFF);
+      setSugg(OFF);
+      setComm(OFF);
+      return;
+    }
+    let live = true;
+    const c = clientRef.current;
+    function load<T>(
+      fn: ((q: { field: string }) => Promise<T>) | undefined,
+      set: (l: Loaded<T>) => void,
+      what: string,
+    ) {
+      if (!fn) {
+        set(OFF);
+        return;
+      }
+      set({ status: { state: 'loading' }, data: null });
+      fn({ field }).then(
+        (data) => live && set({ status: { state: 'ready' }, data }),
+        (err) => live && set({ status: failure(what, err), data: null }),
+      );
+    }
+    load(c.blame, setBlame, 'who wrote each passage');
+    load(c.listSuggestions && allPages(c.listSuggestions), setSugg, 'suggestions');
+    load(c.listComments && allPages(c.listComments), setComm, 'comments');
+    return () => {
+      live = false;
+    };
+  }, [enabled, field, version, tick]);
+
+  const reload = useCallback(() => setTick((t) => t + 1), []);
+
+  const propose = useCallback(
+    async (proposed: string, baseVersion: number) => {
+      const fn = clientRef.current.propose;
+      if (!fn) throw new Error('This host cannot post suggestions.');
+      await fn({ field, base_version: baseVersion, proposed });
+      setTick((t) => t + 1);
+    },
+    [field],
+  );
+
+  const normalized = useMemo(
+    () => ({
+      blame: blame.data && matches(blame.data, version) ? normalizeBlame(blame.data, value) : [],
+      suggestions: sugg.data && matches(sugg.data, version) ? normalizeSuggestions(sugg.data, value) : [],
+      threads: comm.data && matches(comm.data, version) ? normalizeThreads(comm.data, value) : [],
+    }),
+    [blame.data, sugg.data, comm.data, value, version],
+  );
+
+  const status = { blame: blame.status, suggestions: sugg.status, comments: comm.status };
+  const notices = [status.blame, status.suggestions, status.comments].flatMap((s) =>
+    s.state === 'error' && s.message ? [s.message] : [],
+  );
+  const unrecorded = blame.data ? blameNotice(blame.data) : null;
+  if (unrecorded) notices.unshift(unrecorded);
+
+  return { ...normalized, status, notices, reload, propose };
+}

package/src/components/track-changes/word-diff.ts

@@ -0,0 +1,97 @@
+/**
+ * The smallest word-sized change from one value of a field to another, as
+ * editor change specs (bd startsim-sjuai).
+ *
+ * WHAT THIS IS FOR, AND WHAT IT IS NOT. The editor uses it in exactly one
+ * place: when the stored value changes underneath it (an accept, another
+ * reviewer's save), it applies the difference as a CHANGE rather than
+ * replacing the document, so every decoration and the cursor map through it
+ * instead of collapsing to the start. It is NOT the diff that decides span
+ * boundaries for blame, anchors or suggestion hunks: that is the shared
+ * server module (startsim-whwxd.1), and the editor always paints the server's
+ * offsets. A disagreement here can only make a mapped mark land a few
+ * characters differently until the next read, never paint wrong authorship.
+ *
+ * REUSES `diffLines` from history/text-diff (rule #1): that LCS takes any
+ * `string[]`, so handing it word tokens instead of lines makes it word-level.
+ * The text the live drafts carry (design startsim-xyn25 section 0) is one
+ * ~500-character line per paragraph, which is why a line diff is not enough.
+ */
+import { diffLines } from '../history/text-diff';
+
+export interface TextChange {
+  from: number;
+  to: number;
+  insert: string;
+}
+
+/** Han, Hiragana and Katakana have no spaces between words, so each character
+ *  is its own token; otherwise a whole CJK sentence would be one "word". */
+const TOKEN =
+  /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]|[\p{L}\p{N}\p{M}_]+|\s+|[^\s\p{L}\p{N}\p{M}_]/gu;
+
+export function tokenize(text: string): string[] {
+  return text.match(TOKEN) ?? [];
+}
+
+/** Above this many DP cells (tokens x tokens) the middle is replaced whole.
+ *  A 4 KB blog is ~1,300 tokens, so a whole-text rewrite is ~1.7M cells. */
+const MAX_CELLS = 4_000_000;
+
+const isHigh = (c: number) => c >= 0xd800 && c <= 0xdbff;
+const isLow = (c: number) => c >= 0xdc00 && c <= 0xdfff;
+
+/** Changes in `a`'s coordinates, sorted and non-overlapping, that turn `a`
+ *  into `b`. Empty when they are equal. */
+export function wordChanges(a: string, b: string): TextChange[] {
+  if (a === b) return [];
+  const max = Math.min(a.length, b.length);
+  let p = 0;
+  while (p < max && a.charCodeAt(p) === b.charCodeAt(p)) p++;
+  // Never split a surrogate pair.
+  if (p > 0 && isHigh(a.charCodeAt(p - 1))) p--;
+  let s = 0;
+  while (s < max - p && a.charCodeAt(a.length - 1 - s) === b.charCodeAt(b.length - 1 - s)) s++;
+  if (s > 0 && isLow(a.charCodeAt(a.length - s))) s--;
+
+  const midA = a.slice(p, a.length - s);
+  const midB = b.slice(p, b.length - s);
+  const tA = tokenize(midA);
+  const tB = tokenize(midB);
+  // tokenize covers every character (the last class matches anything that is
+  // not whitespace, a letter, a number or a mark), so tokens re-join exactly.
+  if (tA.join('') !== midA || tB.join('') !== midB || tA.length * tB.length > MAX_CELLS) {
+    return [{ from: p, to: a.length - s, insert: midB }];
+  }
+
+  const out: TextChange[] = [];
+  let pos = p;
+  let pending: TextChange | null = null;
+  for (const op of diffLines(tA, tB)) {
+    if (op.type === 'eq') {
+      if (pending) out.push(pending);
+      pending = null;
+      pos += op.line.length;
+    } else if (op.type === 'del') {
+      pending = pending ?? { from: pos, to: pos, insert: '' };
+      pending.to += op.line.length;
+      pos += op.line.length;
+    } else {
+      pending = pending ?? { from: pos, to: pos, insert: '' };
+      pending.insert += op.line;
+    }
+  }
+  if (pending) out.push(pending);
+  return out;
+}
+
+/** Apply sorted, non-overlapping changes expressed in `text`'s coordinates. */
+export function applyTextChanges(text: string, changes: TextChange[]): string {
+  let out = '';
+  let last = 0;
+  for (const c of changes) {
+    out += text.slice(last, c.from) + c.insert;
+    last = c.to;
+  }
+  return out + text.slice(last);
+}