@startsimpli/ui 0.4.142 → 0.4.144

package/src/components/track-changes/final-text.ts

@@ -0,0 +1,54 @@
+/**
+ * The FINAL and ORIGINAL views (bd startsim-whwxd.3; design startsim-xyn25
+ * section d).
+ *
+ * Read literally, the design's two views are the same text: the stored string
+ * never has a suggestion applied, so "the current text" and "the base with no
+ * suggestion applied" are one string. They follow Word's meaning instead:
+ *
+ *   ORIGINAL  the stored text, with no marks.
+ *   FINAL     the stored text with every OPEN, PLACED suggestion applied,
+ *             with no marks: what the record would read if all were accepted.
+ *
+ * Two suggestions that overlap cannot both be applied, so the later one (in
+ * document order) is skipped and NAMED, never merged by guesswork. The server
+ * is the one that applies a real accept; this is a preview only.
+ */
+import type { Suggestion } from './types';
+
+export interface FinalText {
+  text: string;
+  /** Applied, in document order. */
+  applied: string[];
+  /** Open and placed, but overlapping one already applied. */
+  skipped: string[];
+}
+
+export function placedOpen(suggestions: Suggestion[]): Suggestion[] {
+  return suggestions
+    .filter((s) => s.status === 'open' && s.anchorState !== 'orphaned')
+    .slice()
+    .sort((a, b) => a.from - b.from || a.to - b.to);
+}
+
+export function applyOpenSuggestions(text: string, suggestions: Suggestion[]): FinalText {
+  const applied: string[] = [];
+  const skipped: string[] = [];
+  let out = '';
+  let last = 0;
+  let lastInsertAt = -1;
+  for (const s of placedOpen(suggestions)) {
+    const overlaps = s.from < last || (s.from === s.to && s.from === lastInsertAt);
+    // The quote must still be what the text holds there; normalize already
+    // orphans a mismatch, so this is the belt to its braces.
+    if (overlaps || s.to > text.length || text.slice(s.from, s.to) !== s.quote) {
+      skipped.push(s.id);
+      continue;
+    }
+    out += text.slice(last, s.from) + s.replacement;
+    last = s.to;
+    lastInsertAt = s.from === s.to ? s.from : -1;
+    applied.push(s.id);
+  }
+  return { text: out + text.slice(last), applied, skipped };
+}

package/src/components/track-changes/http-client.ts

@@ -0,0 +1,109 @@
+/**
+ * A {@link TrackChangesClient} over plain `fetch`, for any foundry app whose
+ * tenant API serves the track-changes routes (start-simpli-api #507/#508;
+ * bd startsim-whwxd.3).
+ *
+ * PLAIN FETCH ON PURPOSE. The shared API client camelCases response keys
+ * recursively, and these responses carry tenant-declared field names
+ * (`field: "judge_verdict"`) that must arrive as declared. The normalizers
+ * read either spelling of their own keys, so raw snake_case is what they want.
+ *
+ * The host supplies the auth header and the URL shape (an app whose proxy
+ * appends a trailing slash passes paths without one, and vice versa).
+ *
+ * A non-2xx answer throws {@link TrackChangesHttpError} carrying `status` and
+ * the parsed `body`, which is what the hook reads to say WHY (a 404 is "you
+ * may not read this", never "there is nothing here").
+ */
+import type {
+  AcceptRequest,
+  AcceptResponseWire,
+  BlameResponseWire,
+  CommentPageWire,
+  CommentRequest,
+  CommentThreadWire,
+  CommentWire,
+  ProposeRequest,
+  RosterPageWire,
+  SuggestionPageWire,
+  TrackChangesClient,
+} from './types';
+
+export class TrackChangesHttpError extends Error {
+  readonly status: number;
+  readonly body: Record<string, unknown>;
+  constructor(status: number, body: Record<string, unknown>) {
+    const d = typeof body.detail === 'string' ? body.detail : `the server answered ${status}`;
+    super(d);
+    this.name = 'TrackChangesHttpError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export interface HttpTrackChangesOptions {
+  /** Request headers, normally `{ authorization: 'Bearer …' }`. */
+  headers: () => Promise<Record<string, string>> | Record<string, string>;
+  /** Turn an API path (no leading host, no trailing slash, e.g.
+   *  `/api/v1/entities/<id>/blame`) into the URL to fetch. Default: the path
+   *  with a trailing slash, which is what Django routes. */
+  url?: (path: string) => string;
+  fetch?: typeof fetch;
+}
+
+async function parse(res: Response): Promise<Record<string, unknown>> {
+  try {
+    const j = await res.json();
+    return j && typeof j === 'object' ? (j as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function createHttpTrackChangesClient(
+  recordId: string | number,
+  { headers, url = (p) => `${p}/`, fetch: f }: HttpTrackChangesOptions,
+): TrackChangesClient {
+  const doFetch = f ?? ((...a: Parameters<typeof fetch>) => fetch(...a));
+  const base = `/api/v1/entities/${recordId}`;
+
+  async function call<T>(path: string, init?: { method?: string; body?: unknown; query?: Record<string, string | undefined> }): Promise<T> {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(init?.query ?? {})) if (v != null && v !== '') q.set(k, v);
+    const qs = q.toString();
+    const h = { ...(await headers()) };
+    if (init?.body !== undefined) h['content-type'] = 'application/json';
+    const res = await doFetch(`${url(path)}${qs ? `?${qs}` : ''}`, {
+      method: init?.method ?? 'GET',
+      headers: h,
+      ...(init?.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+    });
+    const body = await parse(res);
+    if (!res.ok) throw new TrackChangesHttpError(res.status, body);
+    return body as T;
+  }
+
+  return {
+    blame: ({ field }) => call<BlameResponseWire>(`${base}/blame`, { query: { field } }),
+    listSuggestions: ({ field, cursor }) =>
+      call<SuggestionPageWire>(`${base}/suggestions`, { query: { field, cursor } }),
+    listComments: ({ field, cursor, status }) =>
+      call<CommentPageWire>(`${base}/comments`, { query: { field, cursor, status } }),
+    propose: (body: ProposeRequest) => call(`${base}/suggestions`, { method: 'POST', body }),
+    accept: ({ ids, expectedVersion }: AcceptRequest) =>
+      call<AcceptResponseWire>(`${base}/suggestions/accept`, {
+        method: 'POST',
+        // ONE spelling of the precondition: the server refuses if either
+        // disagrees, so sending If-Match as well can only add a way to fail.
+        body: { ids, expected_version: expectedVersion },
+      }),
+    reject: ({ ids, reason }) =>
+      call(`${base}/suggestions/reject`, { method: 'POST', body: reason ? { ids, reason } : { ids } }),
+    withdraw: (id) => call(`${base}/suggestions/${id}/withdraw`, { method: 'POST', body: {} }),
+    comment: (req: CommentRequest) => call<CommentThreadWire>(`${base}/comments`, { method: 'POST', body: req }),
+    reply: (threadId, req) => call<CommentWire>(`${base}/comments/${threadId}/replies`, { method: 'POST', body: req }),
+    resolveThread: (threadId) => call(`${base}/comments/${threadId}/resolve`, { method: 'POST', body: {} }),
+    reopenThread: (threadId) => call(`${base}/comments/${threadId}/reopen`, { method: 'POST', body: {} }),
+    roster: ({ cursor }) => call<RosterPageWire>(`/api/v1/org/roster`, { query: { cursor } }),
+  };
+}

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

@@ -0,0 +1,90 @@
+/**
+ * @startsimpli/ui/track-changes — the track-changes editor surface
+ * (bd startsim-sjuai; design startsim-xyn25; epic startsim-whwxd).
+ *
+ * A SEPARATE SUBPATH ON PURPOSE, and never re-exported from the root barrel:
+ * it imports CodeMirror, which is an OPTIONAL peer dependency. An app that
+ * never mounts the editor must not need CodeMirror installed, and one that
+ * does should load it with a dynamic import on the page that edits.
+ *
+ * Install in the consuming app:
+ *   @codemirror/state @codemirror/view @codemirror/commands
+ *   @codemirror/language @codemirror/lang-markdown
+ *
+ * Wiring, in the host:
+ *
+ * ```tsx
+ * const tc = useTrackChanges({ client, field: 'blog', value, version });
+ * <TrackedTextEditor
+ *   label="Blog (markdown)" value={value} version={version}
+ *   currentActorSub={me.sub} canEdit={canEdit}
+ *   blame={tc.blame} suggestions={tc.suggestions} threads={tc.threads}
+ *   notices={tc.notices} onPropose={tc.propose}
+ *   onChange={save}            // editing mode only; never called while suggesting
+ * />
+ * ```
+ */
+export { TrackedTextEditor } from './TrackedTextEditor';
+export type { TrackMode, TrackedTextEditorHandle, TrackedTextEditorProps } from './TrackedTextEditor';
+
+export { useTrackChanges, TrackChangesActionError } from './useTrackChanges';
+export type { SourceState, SourceStatus, TrackChanges, TrackChangesActions, UseTrackChangesOptions } from './useTrackChanges';
+
+// The rail, the Read view, the views, and the composer over all of them
+// (startsim-whwxd.3).
+export { TrackedField } from './TrackedField';
+export type { TrackedFieldHandle, TrackedFieldProps, TrackedFieldSurface, TrackedFieldView } from './TrackedField';
+export { ChangesRail, mentionQuery, mentionsIn } from './ChangesRail';
+export type { ChangesRailProps } from './ChangesRail';
+export { TrackedReadView, READ_STYLE, authorTint, readMarksOf, renderHast } from './TrackedReadView';
+export type { TrackedReadViewProps } from './TrackedReadView';
+export { alignToSource, markTree, plainTree, rehypeTrackMarks, sourceOffsetOf } from './read-marks';
+export type { ReadMark, ReadMarkKind } from './read-marks';
+export { applyOpenSuggestions, placedOpen } from './final-text';
+export type { FinalText } from './final-text';
+export { createHttpTrackChangesClient, TrackChangesHttpError } from './http-client';
+export type { HttpTrackChangesOptions } from './http-client';
+
+export {
+  DEFAULT_KEYS,
+  LINE_SEPARATOR,
+  activeMarkOf,
+  computeMarks,
+  enterSuggesting,
+  focusMark,
+  isAuthorship,
+  isChangeOrComment,
+  isSuggesting,
+  leaveSuggesting,
+  marksOf,
+  moveToMark,
+  ownSuggestions,
+  proposedText,
+  rebaseOnto,
+  selectionAnchorOf,
+  setAnnotations,
+  trackChanges,
+  trackingOf,
+} from './extension';
+export type { AnnotationsInput, MarkKind, MarkVisibility, TrackKeys, TrackMark, Tracking } from './extension';
+
+export {
+  ANCHOR_CONTEXT,
+  anchorFor,
+  blameNotice,
+  BLAME_REASON_TEXT,
+  codePointToUtf16,
+  normalizeActor,
+  normalizeBlame,
+  normalizeRoster,
+  normalizeSuggestions,
+  normalizeThreads,
+  toServerOffsets,
+  utf16ToCodePoint,
+} from './normalize';
+
+export { describeBlame, describeSuggestion, describeThread } from './describe';
+export { applyTextChanges, tokenize, wordChanges } from './word-diff';
+export type { TextChange } from './word-diff';
+
+export type * from './types';

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

@@ -0,0 +1,393 @@
+/**
+ * Wire → editor shapes for the track-changes surface (bd startsim-sjuai).
+ *
+ * Three jobs, each the kind of thing that fails silently if done per caller:
+ *
+ * 1. READ BOTH SPELLINGS. The shared API client camelCases every response key,
+ *    so `actor_kind` may arrive as `actorKind` (see history/types.ts).
+ * 2. CONVERT OFFSETS. The server counts code points, the editor counts UTF-16
+ *    code units (see types.ts). Converted here, once, against the text the
+ *    offsets describe.
+ * 3. NEVER PAINT A GUESS. An anchor whose quote does not match the text at its
+ *    converted offsets is reported `orphaned`, and a span outside the text is
+ *    clipped or dropped. Painting a comment on the wrong words is worse than
+ *    listing it as orphaned, which is what the design asks for anyway.
+ */
+import type { ActorKind, ActorKindSource } from '../ActorIdentity';
+import type {
+  AnchorState,
+  AnchorWire,
+  BlameReason,
+  BlameResponseWire,
+  BlameSpan,
+  BlameSpanWire,
+  BlameVia,
+  CommentPageWire,
+  CommentThread,
+  CommentThreadWire,
+  OffsetUnit,
+  SelectionAnchor,
+  Suggestion,
+  SuggestionPageWire,
+  SuggestionStatus,
+  SuggestionWire,
+  PositionWire,
+  RosterEntryWire,
+  RosterMember,
+  RosterPageWire,
+  TrackActor,
+  WireActor,
+  WireAuthor,
+} from './types';
+
+/* -------------------------------------------------------------------------- */
+/*  Offsets                                                                   */
+/* -------------------------------------------------------------------------- */
+
+const ASTRAL = /[\uD800-\uDBFF][\uDC00-\uDFFF]/;
+
+/** UTF-16 offset of the `cp`-th code point of `text`. Clamped to the text. */
+export function codePointToUtf16(text: string, cp: number): number {
+  if (!(cp > 0)) return 0;
+  if (!ASTRAL.test(text)) return Math.min(cp, text.length);
+  let units = 0;
+  let points = 0;
+  while (units < text.length && points < cp) {
+    const c = text.charCodeAt(units);
+    units += c >= 0xd800 && c <= 0xdbff && units + 1 < text.length ? 2 : 1;
+    points++;
+  }
+  return units;
+}
+
+/** Code-point offset of UTF-16 offset `u` in `text`. */
+export function utf16ToCodePoint(text: string, u: number): number {
+  if (!(u > 0)) return 0;
+  const end = Math.min(u, text.length);
+  if (!ASTRAL.test(text)) return end;
+  return Array.from(text.slice(0, end)).length;
+}
+
+/** An editor range in the server's unit, for posting an anchor. */
+export function toServerOffsets(
+  text: string,
+  range: { from: number; to: number },
+  unit: OffsetUnit = 'code_point',
+): { from: number; to: number } {
+  if (unit === 'utf16') return { from: range.from, to: range.to };
+  return { from: utf16ToCodePoint(text, range.from), to: utf16ToCodePoint(text, range.to) };
+}
+
+/** The design's anchor (section c): the range, its text, and 32 characters of
+ *  context each side for the server's quote fallback. UTF-16 offsets. */
+export const ANCHOR_CONTEXT = 32;
+
+export function anchorFor(text: string, a: number, b: number): SelectionAnchor {
+  const from = Math.max(0, Math.min(a, b, text.length));
+  const to = Math.min(text.length, Math.max(a, b, 0));
+  return {
+    from,
+    to,
+    quote: text.slice(from, to),
+    prefix: text.slice(Math.max(0, from - ANCHOR_CONTEXT), from),
+    suffix: text.slice(to, to + ANCHOR_CONTEXT),
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Actors                                                                    */
+/* -------------------------------------------------------------------------- */
+
+const str = (v: unknown): string => (typeof v === 'string' ? v : '');
+
+function kindOf(v: unknown): ActorKind {
+  return v === 'person' || v === 'machine' ? v : 'unknown';
+}
+
+function kindSourceOf(v: unknown): ActorKindSource | undefined {
+  return v === 'claim' || v === 'inferred' ? v : undefined;
+}
+
+function isNested(w: object): w is WireAuthor {
+  return 'sub' in w || 'label' in w || 'kind' in w;
+}
+
+/** Reads flat actor columns (`actor_label`), a nested author object
+ *  (`{sub, label, kind, kind_source}`), or a bare label. */
+export function normalizeActor(w: WireActor | WireAuthor | string | null | undefined): TrackActor {
+  if (typeof w === 'string') return { sub: '', label: w, kind: 'unknown' };
+  if (w && isNested(w)) {
+    return {
+      sub: str(w.sub),
+      label: str(w.label).trim(),
+      kind: kindOf(w.kind),
+      kindSource: kindSourceOf(w.kind_source ?? w.kindSource),
+    };
+  }
+  w = w as WireActor | null | undefined;
+  return {
+    sub: str(w?.actor_sub ?? w?.actorSub),
+    label: str(w?.actor_label ?? w?.actorLabel).trim(),
+    kind: kindOf(w?.actor_kind ?? w?.actorKind),
+    kindSource: kindSourceOf(w?.actor_kind_source ?? w?.actorKindSource),
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Ranges                                                                    */
+/* -------------------------------------------------------------------------- */
+
+function unitOf(w: { offset_unit?: OffsetUnit | null; offsetUnit?: OffsetUnit | null } | null | undefined): OffsetUnit {
+  return (w?.offset_unit ?? w?.offsetUnit) === 'utf16' ? 'utf16' : 'code_point';
+}
+
+function convert(text: string, n: number, unit: OffsetUnit): number {
+  if (unit === 'utf16') return Math.max(0, Math.min(Math.trunc(n), text.length));
+  return codePointToUtf16(text, Math.trunc(n));
+}
+
+function isNum(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+const ANCHOR_STATES: AnchorState[] = ['mapped', 'reanchored', 'orphaned'];
+
+function anchorStateOf(v: unknown): AnchorState {
+  return ANCHOR_STATES.includes(v as AnchorState) ? (v as AnchorState) : 'mapped';
+}
+
+/** Resolve an anchor to UTF-16 offsets in `text`, or report it orphaned. */
+function resolveAnchor(
+  text: string,
+  anchor: AnchorWire | null | undefined,
+  declared: AnchorState,
+  unit: OffsetUnit,
+): { from: number | null; to: number | null; quote: string; state: AnchorState } {
+  const quote = str(anchor?.quote);
+  if (!anchor || declared === 'orphaned' || !isNum(anchor.from) || !isNum(anchor.to)) {
+    return { from: null, to: null, quote, state: anchor ? 'orphaned' : declared };
+  }
+  const from = convert(text, anchor.from, unit);
+  const to = convert(text, anchor.to, unit);
+  // An anchor is never clamped: past the end means it describes other text.
+  const max = unit === 'utf16' ? text.length : utf16ToCodePoint(text, text.length);
+  if (anchor.from < 0 || anchor.to < anchor.from || anchor.to > max) {
+    return { from: null, to: null, quote, state: 'orphaned' };
+  }
+  // A quote that does not match is a disagreement about the text, so the
+  // offsets mean nothing. `quote` absent (null) is not checked: a server that
+  // withheld it under the field gate still placed the range.
+  if (anchor.quote != null && text.slice(from, to) !== quote) {
+    return { from: null, to: null, quote, state: 'orphaned' };
+  }
+  // A pure insert has no quote, so the check above passes for ANY offset. Its
+  // neighbours are checked instead: the nearest INSERT_CONTEXT characters of
+  // prefix and suffix. Only when BOTH sides disagree is it orphaned, because
+  // an edit a few words away legitimately changes one side's wider context
+  // while the server still (correctly) reports the insert point as mapped.
+  if (from === to && !contextFits(text, from, anchor.prefix, anchor.suffix)) {
+    return { from: null, to: null, quote, state: 'orphaned' };
+  }
+  return { from, to, quote: anchor.quote != null ? quote : text.slice(from, to), state: declared };
+}
+
+const INSERT_CONTEXT = 8;
+
+function contextFits(text: string, at: number, prefix?: string | null, suffix?: string | null): boolean {
+  const before = prefix ? prefix.slice(-INSERT_CONTEXT) : '';
+  const after = suffix ? suffix.slice(0, INSERT_CONTEXT) : '';
+  if (!before && !after) return true; // nothing to check against (start of an empty field)
+  const beforeOk = !!before && text.slice(Math.max(0, at - before.length), at) === before;
+  const afterOk = !!after && text.slice(at, at + after.length) === after;
+  return beforeOk || afterOk;
+}
+
+/** The anchor to place and its declared state: `position` (the contract)
+ *  first, then the older spellings. A position's quote is the anchor's. */
+function placement(
+  w: {
+    position?: PositionWire | null;
+    mapped_anchor?: AnchorWire | null;
+    mappedAnchor?: AnchorWire | null;
+    current?: AnchorWire | null;
+    anchor?: AnchorWire | null;
+    anchor_status?: string | null;
+    anchorStatus?: string | null;
+  },
+): { anchor: AnchorWire | null | undefined; state: AnchorState } {
+  const pos = w.position;
+  // An explicit null: the server placed nothing (a suggestion that is no
+  // longer open, or a record/field comment). Not placed, and not orphaned.
+  if (pos === null) return { anchor: null, state: 'mapped' };
+  if (pos) {
+    const state = anchorStateOf(pos.state);
+    if (!isNum(pos.from) || !isNum(pos.to)) {
+      return { anchor: { from: NaN, to: NaN, quote: w.anchor?.quote ?? null }, state: 'orphaned' };
+    }
+    return {
+      anchor: { from: pos.from, to: pos.to, quote: w.anchor?.quote ?? null, prefix: w.anchor?.prefix, suffix: w.anchor?.suffix },
+      state,
+    };
+  }
+  return {
+    anchor: w.mapped_anchor ?? w.mappedAnchor ?? w.current ?? w.anchor,
+    state: anchorStateOf(w.anchor_status ?? w.anchorStatus),
+  };
+}
+
+function results<T>(w: { results?: T[] | null } | T[] | null | undefined): T[] {
+  if (Array.isArray(w)) return w;
+  return w?.results ?? [];
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Blame                                                                     */
+/* -------------------------------------------------------------------------- */
+
+const VIAS: BlameVia[] = ['edit', 'accepted_suggestion', 'restore', 'unknown'];
+
+/** What each reason code means, for when the server sends no `detail`. */
+export const BLAME_REASON_TEXT: Record<BlameReason, string> = {
+  before_history: 'written before the history began',
+  truncated: 'a revision was too large to store in full',
+  values_omitted: 'a revision was too large to store its values',
+  chain_break: 'the history has a gap here',
+  unrecorded_change: 'changed without a recorded revision',
+};
+
+function reasonOf(v: unknown): BlameReason | null {
+  return typeof v === 'string' && v in BLAME_REASON_TEXT ? (v as BlameReason) : null;
+}
+
+export function normalizeBlame(w: BlameResponseWire | null | undefined, text: string): BlameSpan[] {
+  const unit = unitOf(w);
+  const out: BlameSpan[] = [];
+  for (const s of w?.spans ?? []) {
+    if (!isNum(s.from) || !isNum(s.to)) continue;
+    const from = convert(text, s.from, unit);
+    const to = convert(text, s.to, unit);
+    if (to <= from) continue;
+    const via = VIAS.includes(s.via as BlameVia) ? (s.via as BlameVia) : null;
+    const rawReason = str(s.reason).trim();
+    const actor = normalizeActor(s);
+    // Unknown when the server says so (via or a reason), or when there is no
+    // one to credit. Never an author invented from a partial row.
+    const unknown = via === 'unknown' || !!rawReason || !(actor.label || actor.sub);
+    const reason = reasonOf(rawReason);
+    const said =
+      str(s.detail).trim() ||
+      (reason ? BLAME_REASON_TEXT[reason] : rawReason) ||
+      'author not recorded';
+    const acceptedRaw = s.accepted_by ?? s.acceptedBy;
+    const restored = s.restored_from ?? s.restoredFrom;
+    out.push({
+      id: `blame:${from}`,
+      from,
+      to,
+      author: unknown ? null : actor,
+      unknownReason: unknown ? said : null,
+      reason: unknown ? reason : null,
+      version: isNum(s.version) ? s.version : null,
+      at: s.at ?? null,
+      via: unknown ? 'unknown' : via,
+      acceptedBy: !unknown && acceptedRaw ? normalizeActor(acceptedRaw) : null,
+      restoredFrom: isNum(restored) ? restored : null,
+    });
+  }
+  return out.sort((a, b) => a.from - b.from);
+}
+
+/** A sentence when the field's authorship is not recorded at all (history
+ *  off on the type: `recorded: false`, `spans: null`), else null. */
+export function blameNotice(w: BlameResponseWire | null | undefined): string | null {
+  if (!w || (w.recorded !== false && w.spans !== null)) return null;
+  const why = str(w.detail).trim();
+  return `Who wrote each passage is not recorded${why ? `: ${why}` : '.'}`;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Suggestions                                                               */
+/* -------------------------------------------------------------------------- */
+
+const STATUSES: SuggestionStatus[] = ['open', 'accepted', 'rejected', 'withdrawn', 'superseded'];
+
+export function normalizeSuggestions(
+  w: SuggestionPageWire | SuggestionWire[] | null | undefined,
+  text: string,
+): Suggestion[] {
+  const unit = Array.isArray(w) ? 'code_point' : unitOf(w);
+  return results(w).map((s) => {
+    const { anchor, state } = placement(s);
+    const r = resolveAnchor(text, anchor, state, unit);
+    const status = STATUSES.includes(s.status as SuggestionStatus) ? (s.status as SuggestionStatus) : 'open';
+    return {
+      id: String(s.id),
+      setId: (s.set_id ?? s.setId ?? null) as string | null,
+      from: r.from ?? 0,
+      to: r.to ?? 0,
+      quote: r.quote,
+      replacement: str(s.replacement),
+      status,
+      anchorState: r.state,
+      author: normalizeActor(s.author ?? s),
+      createdAt: s.created_at ?? s.createdAt ?? null,
+    };
+  });
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Roster                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/** Colleagues by `sub`, deduped (central's roster pages can repeat a member:
+ *  startsim-whwxd.7), blank subs dropped, sorted by label. */
+export function normalizeRoster(pages: Array<RosterPageWire | RosterEntryWire[] | null | undefined>): RosterMember[] {
+  const bySub = new Map<string, RosterMember>();
+  for (const page of pages) {
+    for (const r of results(page)) {
+      const sub = str(r?.sub).trim();
+      if (!sub || bySub.has(sub)) continue;
+      bySub.set(sub, { sub, label: str(r?.label).trim() });
+    }
+  }
+  return [...bySub.values()].sort((a, b) => (a.label || a.sub).localeCompare(b.label || b.sub));
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Comments                                                                  */
+/* -------------------------------------------------------------------------- */
+
+export function normalizeThreads(
+  w: CommentPageWire | CommentThreadWire[] | null | undefined,
+  text: string,
+): CommentThread[] {
+  const unit = Array.isArray(w) ? 'code_point' : unitOf(w);
+  return results(w).map((t) => {
+    const { anchor, state } = placement(t);
+    const r = resolveAnchor(text, anchor, state, unit);
+    const res = t.resolution;
+    return {
+      id: String(t.thread_id ?? t.threadId ?? t.id ?? ''),
+      field: typeof t.field === 'string' && t.field ? t.field : null,
+      resolution:
+        res && typeof res === 'object' && res.action
+          ? { action: String(res.action), by: normalizeActor(res.by), at: res.at ?? null }
+          : null,
+      from: r.from,
+      to: r.to,
+      quote: r.quote,
+      anchorState: r.state,
+      resolved: t.status === 'resolved' || Boolean(t.resolved),
+      redacted: Boolean(t.redacted),
+      comments: (t.comments ?? []).map((c) => ({
+        id: String(c.id),
+        body: c.deleted ? null : (c.body ?? null),
+        deleted: Boolean(c.deleted),
+        author: normalizeActor(c.author ?? c),
+        createdAt: c.created_at ?? c.createdAt ?? null,
+        mentions: Array.isArray(c.mentions) ? c.mentions.filter((m): m is string => typeof m === 'string' && !!m) : [],
+        editedAt: c.edited_at ?? c.editedAt ?? null,
+      })),
+    };
+  });
+}