@startsimpli/ui 0.4.143 → 0.4.145

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

@@ -27,8 +27,23 @@
 export { TrackedTextEditor } from './TrackedTextEditor';
 export type { TrackMode, TrackedTextEditorHandle, TrackedTextEditorProps } from './TrackedTextEditor';
 
-export { useTrackChanges } from './useTrackChanges';
-export type { SourceState, SourceStatus, TrackChanges, UseTrackChangesOptions } from './useTrackChanges';
+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,
@@ -61,6 +76,7 @@ export {
   codePointToUtf16,
   normalizeActor,
   normalizeBlame,
+  normalizeRoster,
   normalizeSuggestions,
   normalizeThreads,
   toServerOffsets,

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

@@ -32,6 +32,9 @@ import type {
   SuggestionStatus,
   SuggestionWire,
   PositionWire,
+  RosterEntryWire,
+  RosterMember,
+  RosterPageWire,
   TrackActor,
   WireActor,
   WireAuthor,
@@ -332,6 +335,24 @@ export function normalizeSuggestions(
   });
 }
 
+/* -------------------------------------------------------------------------- */
+/*  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                                                                  */
 /* -------------------------------------------------------------------------- */
@@ -344,8 +365,14 @@ export function normalizeThreads(
   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,
@@ -358,6 +385,8 @@ export function normalizeThreads(
         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,
       })),
     };
   });

package/src/components/track-changes/read-marks.ts

@@ -0,0 +1,262 @@
+/**
+ * Marks in the rendered Read view (bd startsim-whwxd.3; design startsim-xyn25
+ * section d): a rehype transform that wraps text runs by their SOURCE position.
+ *
+ * The markdown parser keeps, on every text node, the offsets of the source it
+ * came from. Server offsets are offsets into that same source string, so a
+ * suggestion, comment or authorship span can be drawn over the rendered prose
+ * exactly where it sits in the markdown.
+ *
+ * NEVER PAINT A GUESS. A text node's value is not always its source slice:
+ * `\_` renders `_`, `&` renders `&`. When the value is a subsequence of
+ * the slice (escapes, entities that decode to a character of their own
+ * spelling) the characters are aligned one by one. When it is not (`'`
+ * renders a quote that appears nowhere in its source), the node is left
+ * alone, and anything inside it is reported UNPLACED so the host says so
+ * instead of drawing it a few characters off.
+ *
+ * Every run the transform writes carries `data-src-from`, the source offset
+ * of its first character, so a DOM selection maps back to source offsets for
+ * "comment on selection".
+ */
+
+/* Minimal hast shapes: this file is the only reader, and keeping them local
+   avoids a dependency on @types/hast for one transform. */
+export interface HastPoint {
+  offset?: number;
+}
+export interface HastText {
+  type: 'text';
+  value: string;
+  position?: { start?: HastPoint; end?: HastPoint };
+}
+export interface HastElement {
+  type: 'element';
+  tagName: string;
+  properties?: Record<string, unknown>;
+  children: HastNode[];
+  position?: { start?: HastPoint; end?: HastPoint };
+}
+export interface HastRoot {
+  type: 'root';
+  children: HastNode[];
+}
+export type HastNode = HastText | HastElement | HastRoot | { type: string; [k: string]: unknown };
+
+export type ReadMarkKind = 'blame' | 'suggestion' | 'comment';
+
+/** One thing to draw, in SOURCE offsets (UTF-16, as JavaScript strings are). */
+export interface ReadMark {
+  id: string;
+  kind: ReadMarkKind;
+  from: number;
+  to: number;
+  /** The accessible sentence; becomes the title. */
+  title: string;
+  /** Suggestion: the text it would insert, drawn after the struck range. */
+  insert?: string;
+  /** Classes for the wrapper. */
+  className?: string;
+}
+
+/** Character-level map from a text node's value to source offsets, or null
+ *  when the value cannot be aligned to its source. */
+export function alignToSource(value: string, source: string, start: number, end: number): number[] | null {
+  if (!(start >= 0) || !(end >= start) || end > source.length) return null;
+  const slice = source.slice(start, end);
+  const map: number[] = new Array(value.length);
+  if (slice === value) {
+    for (let i = 0; i < value.length; i++) map[i] = start + i;
+    return map;
+  }
+  let j = 0;
+  for (let i = 0; i < value.length; i++) {
+    while (j < slice.length && slice[j] !== value[i]) j++;
+    if (j >= slice.length) return null;
+    map[i] = start + j;
+    j++;
+  }
+  return map;
+}
+
+function isText(n: HastNode): n is HastText {
+  return n.type === 'text' && typeof (n as HastText).value === 'string';
+}
+
+function hasChildren(n: HastNode): n is HastElement | HastRoot {
+  return Array.isArray((n as HastElement).children);
+}
+
+const TAG: Record<ReadMarkKind, string> = { suggestion: 'del', comment: 'mark', blame: 'span' };
+const NEST: ReadMarkKind[] = ['blame', 'comment', 'suggestion'];
+
+function element(tagName: string, properties: Record<string, unknown>, children: HastNode[]): HastElement {
+  return { type: 'element', tagName, properties, children };
+}
+
+/**
+ * Wrap the text runs of one aligned text node. Runs break at every mark
+ * boundary and at every place the source skips characters (an escape), so
+ * each run is contiguous in both the value and the source.
+ */
+function wrapText(
+  node: HastText,
+  map: number[],
+  marks: ReadMark[],
+  placed: Set<string>,
+  insertsDone: Set<string>,
+): HastNode[] {
+  const value = node.value;
+  if (!value.length) return [node];
+  const nodeFrom = map[0];
+  const nodeTo = map[value.length - 1] + 1;
+  const here = marks.filter((m) => m.from < nodeTo && m.to > nodeFrom);
+
+  const cuts = new Set<number>([0, value.length]);
+  for (let i = 1; i < value.length; i++) if (map[i] !== map[i - 1] + 1) cuts.add(i);
+  for (const m of here) {
+    for (const edge of [m.from, m.to]) {
+      for (let i = 1; i < value.length; i++) if (map[i] === edge) cuts.add(i);
+    }
+  }
+  // Pure inserts and the insert half of a replacement are drawn at a point.
+  const points = marks.filter((m) => m.kind === 'suggestion' && m.insert && !insertsDone.has(m.id));
+  for (const p of points) {
+    for (let i = 1; i < value.length; i++) if (map[i] === p.to) cuts.add(i);
+  }
+  const bounds = [...cuts].sort((a, b) => a - b);
+
+  const out: HastNode[] = [];
+  const emitInsertsAt = (srcPos: number) => {
+    for (const p of points) {
+      if (insertsDone.has(p.id) || p.to !== srcPos) continue;
+      insertsDone.add(p.id);
+      placed.add(p.id);
+      out.push(
+        element(
+          'ins',
+          { className: ['tc-read-ins'], dataTcId: p.id, title: p.title },
+          [{ type: 'text', value: p.insert ?? '' }],
+        ),
+      );
+    }
+  };
+
+  for (let b = 0; b < bounds.length - 1; b++) {
+    const i = bounds[b];
+    const k = bounds[b + 1];
+    const srcFrom = map[i];
+    const srcTo = map[k - 1] + 1;
+    emitInsertsAt(srcFrom);
+    let piece: HastNode = element('span', { dataSrcFrom: String(srcFrom) }, [{ type: 'text', value: value.slice(i, k) }]);
+    const covering = here.filter((m) => m.from <= srcFrom && m.to >= srcTo && m.to > m.from);
+    for (const kind of NEST) {
+      for (const m of covering.filter((x) => x.kind === kind)) {
+        placed.add(m.id);
+        piece = element(
+          TAG[kind],
+          { className: ['tc-read-' + kind, ...(m.className ? m.className.split(/\s+/) : [])], dataTcId: m.id, title: m.title },
+          [piece],
+        );
+      }
+    }
+    out.push(piece);
+    if (b === bounds.length - 2) emitInsertsAt(srcTo);
+  }
+  return out;
+}
+
+export interface MarkTreeResult {
+  /** Mark ids drawn at least partly. */
+  placed: Set<string>;
+}
+
+/**
+ * Transform a hast tree in place. `source` is the string the tree was parsed
+ * from. A mark is placed when at least one of its characters (or, for a pure
+ * insert, its point) is drawn.
+ */
+export function markTree(tree: HastNode, source: string, marks: ReadMark[]): MarkTreeResult {
+  const placed = new Set<string>();
+  const insertsDone = new Set<string>();
+  const visit = (parent: HastElement | HastRoot) => {
+    // Never inside code: a fenced block is re-highlighted by its own renderer
+    // and an inline code span is literal. Marks there are reported unplaced.
+    if ((parent as HastElement).tagName === 'code' || (parent as HastElement).tagName === 'pre') return;
+    const next: HastNode[] = [];
+    for (const child of parent.children) {
+      if (isText(child)) {
+        const start = child.position?.start?.offset;
+        const end = child.position?.end?.offset;
+        const map =
+          typeof start === 'number' && typeof end === 'number' ? alignToSource(child.value, source, start, end) : null;
+        if (map) next.push(...wrapText(child, map, marks, placed, insertsDone));
+        else next.push(child);
+      } else {
+        if (hasChildren(child)) visit(child);
+        next.push(child);
+      }
+    }
+    parent.children = next;
+  };
+  if (hasChildren(tree)) visit(tree);
+  return { placed };
+}
+
+/** The rehype plugin form of {@link markTree}, for MarkdownRenderer. */
+export function rehypeTrackMarks(options: {
+  source: string;
+  marks: ReadMark[];
+  onPlaced?: (placed: Set<string>) => void;
+}) {
+  return () => (tree: HastNode) => {
+    const { placed } = markTree(tree, options.source, options.marks);
+    options.onPlaced?.(placed);
+  };
+}
+
+/** A plain-text field as a one-node tree, so plain text takes the same path. */
+export function plainTree(source: string): HastRoot {
+  return {
+    type: 'root',
+    children: [{ type: 'text', value: source, position: { start: { offset: 0 }, end: { offset: source.length } } }],
+  };
+}
+
+/** Source offset of a DOM point inside a marked tree, or null when the point
+ *  is not inside a run that carries `data-src-from`. */
+export function sourceOffsetOf(node: Node | null, offset: number): number | null {
+  if (!node) return null;
+  if (node.nodeType !== 3) {
+    // An element point: use the child it sits before, or after the last.
+    const el = node as Element;
+    const child = el.childNodes[offset] ?? null;
+    if (child) return sourceOffsetOf(firstText(child), 0);
+    const last = el.childNodes[el.childNodes.length - 1] ?? null;
+    const t = last ? lastText(last) : null;
+    return t ? sourceOffsetOf(t, t.textContent?.length ?? 0) : null;
+  }
+  const run = (node.parentElement as Element | null)?.closest('[data-src-from]');
+  if (!run || run.closest('ins')) return null;
+  const from = Number(run.getAttribute('data-src-from'));
+  return Number.isFinite(from) ? from + offset : null;
+}
+
+function firstText(n: Node): Node | null {
+  if (n.nodeType === 3) return n;
+  for (const c of Array.from(n.childNodes)) {
+    const t = firstText(c);
+    if (t) return t;
+  }
+  return null;
+}
+
+function lastText(n: Node): Node | null {
+  if (n.nodeType === 3) return n;
+  const kids = Array.from(n.childNodes);
+  for (let i = kids.length - 1; i >= 0; i--) {
+    const t = lastText(kids[i]);
+    if (t) return t;
+  }
+  return null;
+}

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

@@ -301,8 +301,79 @@ export interface TrackChangesClient {
    *  `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[]>;
+  /** `status: 'all'` is what the rail asks for, so resolved threads stay
+   *  readable (and reopenable) in its resolved list. */
+  listComments?: (query: { field: string; cursor?: string; status?: 'open' | 'resolved' | 'all' }) => Promise<CommentPageWire | CommentThreadWire[]>;
   propose?: (body: ProposeRequest) => Promise<unknown>;
+
+  /* ---- the rail's writes (startsim-whwxd.3). Each is optional, like the reads:
+   * a host that has not bound one simply does not get that control. ---- */
+
+  /** POST suggestions/accept/ {ids, expected_version}. One revision per
+   *  suggestion, document order, all or nothing. Resolves the RECORD (the
+   *  record serializer's body) plus `accepted`; the host must adopt its
+   *  `version`, or its own next save 412s against this accept. */
+  accept?: (req: AcceptRequest) => Promise<AcceptResponseWire>;
+  /** POST suggestions/reject/ {ids, reason?}. The record does not move. */
+  reject?: (req: { ids: string[]; reason?: string }) => Promise<unknown>;
+  /** POST suggestions/<id>/withdraw/. Author only. */
+  withdraw?: (id: string) => Promise<unknown>;
+  /** POST comments/ — a span, field or record comment. */
+  comment?: (req: CommentRequest) => Promise<CommentThreadWire>;
+  /** POST comments/<thread_id>/replies/. */
+  reply?: (threadId: string, req: { body: string; mentions?: string[] }) => Promise<CommentWire>;
+  /** POST comments/<thread_id>/resolve/ */
+  resolveThread?: (threadId: string) => Promise<unknown>;
+  /** POST comments/<thread_id>/reopen/ */
+  reopenThread?: (threadId: string) => Promise<unknown>;
+  /** GET /api/v1/org/roster/ — the colleagues a comment may @mention. In-app
+   *  only: the server sends nothing to anyone mentioned (Quinn, 2026-10-07). */
+  roster?: (query: { cursor?: string }) => Promise<RosterPageWire>;
+}
+
+export interface AcceptRequest {
+  ids: string[];
+  /** The version the reviewer is looking at. REQUIRED by the route (428
+   *  without it, 412 when stale). */
+  expectedVersion: number;
+}
+
+/** The accept answer: the record body, plus what was accepted. */
+export interface AcceptResponseWire {
+  id?: string | number;
+  version?: number | null;
+  data?: Record<string, unknown>;
+  accepted?: { suggestions?: string[]; revisions?: number[] } | null;
+  [key: string]: unknown;
+}
+
+export interface CommentRequest {
+  body: string;
+  /** Omitted: a whole-record comment. */
+  field?: string;
+  /** A span comment: both offsets, UTF-16 at `base_version`. */
+  from?: number;
+  to?: number;
+  base_version?: number;
+  mentions?: string[];
+}
+
+export interface RosterEntryWire {
+  sub?: string | null;
+  label?: string | null;
+}
+
+export interface RosterPageWire {
+  next?: string | null;
+  next_cursor?: string | null;
+  nextCursor?: string | null;
+  results?: RosterEntryWire[] | null;
+}
+
+/** A colleague who can be @mentioned. */
+export interface RosterMember {
+  sub: string;
+  label: string;
 }
 
 /* -------------------------------------------------------------------------- */
@@ -348,10 +419,17 @@ export interface TrackComment {
   deleted: boolean;
   author: TrackActor;
   createdAt: string | null;
+  /** Mentioned subs; shown in-app only. */
+  mentions: string[];
+  editedAt: string | null;
 }
 
 export interface CommentThread {
   id: string;
+  /** The field the thread is on; `null` for a whole-record comment. */
+  field: string | null;
+  /** Who resolved or reopened it last, and when. */
+  resolution: { action: string; by: TrackActor; at: string | null } | null;
   /** `null` for a whole-record or whole-field comment. */
   from: number | null;
   to: number | null;