@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/runtime/layout/table-row-split.ts

@@ -0,0 +1,316 @@
+/**
+ * Table row-boundary split math.
+ *
+ * Pre-P6 the paginated-layout-engine placed every table atomically — a
+ * table taller than the remaining page space pushed to the next page as
+ * a single block, regardless of how many rows could have fit.  That was
+ * correctness-first (the `collectTableRowSlices` walk after pagination
+ * produces empty slice maps) but visually wrong for CCEP corpus tables
+ * like the SOW Milestones table that routinely exceed a page.
+ *
+ * P6.b is the **pure math** side of the real row-boundary split:
+ *
+ *   - `measureTableRowHeights(...)` computes a per-row twip height
+ *     vector via the same measurement path the existing
+ *     `measureTableHeight` walk uses.  Each row height already honors
+ *     `heightRule`, `w:gridBefore` / `w:gridAfter` padding, and real
+ *     per-cell widths via `resolveCellWidth`.
+ *
+ *   - `findTableRowSplit(...)` takes the per-row heights plus the
+ *     remaining page space and walks rows greedily until the next row
+ *     would overflow.  It honors two invariants:
+ *       1. `cantSplit` rows never straddle a page boundary.  If row K
+ *          is `cantSplit` and overflows, the split moves BEFORE row K
+ *          (row K becomes the first row of the next page).
+ *       2. The header rows (`isHeader: true`) must repeat on every
+ *          continuation page.  The caller passes a
+ *          `repeatedHeaderHeightTwips` reservation so `findTableRowSplit`
+ *          accounts for the repeat on subsequent pages.
+ *
+ * P6.c will wire these helpers into `paginateSectionBlocksWithSplits`
+ * so a table overflowing a page emits a `TableRowSlice` pair
+ * (rows-on-prev-page, rows-on-next-page) and the node view prepends
+ * the header rows on continuation pages.  The pure helpers here ship
+ * ahead of the wiring so the math is testable in isolation; the
+ * pagination engine stays byte-for-byte compatible until P6.c lands.
+ */
+
+import type { LayoutMeasurementProvider } from "./layout-measurement-provider.ts";
+import type { SurfaceBlockSnapshot } from "../../api/public-types";
+
+// Re-export the resolveCellWidth helper from paginated-layout-engine so the
+// math stays single-sourced.  The engine module exposes it via the
+// `__resolveCellWidth` test alias already.
+import { __resolveCellWidth } from "./paginated-layout-engine.ts";
+
+const MIN_ROW_HEIGHT_TWIPS = 240;
+const TABLE_ROW_PADDING_TWIPS = 120;
+
+export interface MeasureTableRowHeightsInput {
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>;
+  columnWidth: number;
+  measurementProvider?: LayoutMeasurementProvider;
+}
+
+/**
+ * Per-row twip heights matching the engine's existing
+ * `measureTableHeight` walk.  Returns an array of length
+ * `block.rows.length`; rows with `heightRule === "exact"` are reported
+ * at their explicit height, `"atLeast"` at `max(explicit, content)`,
+ * and `"auto"` at content height clamped to `MIN_ROW_HEIGHT_TWIPS`.
+ *
+ * `verticalMerge: "continue"` cells contribute 0 height (the origin
+ * cell's height covers the chain), matching pagination semantics.
+ */
+export function measureTableRowHeights(
+  input: MeasureTableRowHeightsInput,
+): number[] {
+  const { block, columnWidth, measurementProvider } = input;
+  const heights: number[] = [];
+
+  const totalGridTwips = block.gridColumns.reduce((sum, w) => sum + w, 0);
+  const gridScale =
+    totalGridTwips > 0 && columnWidth > 0 ? columnWidth / totalGridTwips : 1;
+
+  for (const row of block.rows) {
+    const explicitHeight = row.height ?? 0;
+    const heightRule = row.heightRule ?? "auto";
+    const gridBefore = row.gridBefore ?? 0;
+
+    let contentHeight = MIN_ROW_HEIGHT_TWIPS;
+    let columnCursor = gridBefore;
+
+    for (const cell of row.cells) {
+      const span = Math.max(1, cell.colspan ?? 1);
+      const cellWidth = __resolveCellWidth(
+        block.gridColumns,
+        columnCursor,
+        span,
+        columnWidth,
+        gridScale,
+      );
+      columnCursor += span;
+
+      if (cell.verticalMerge === "continue") continue;
+
+      let cellContentHeight = 0;
+      for (const child of cell.content) {
+        if (child.kind === "paragraph") {
+          cellContentHeight += measureParagraphStandaloneHeight(
+            child,
+            cellWidth,
+            measurementProvider,
+          );
+        } else {
+          cellContentHeight += MIN_ROW_HEIGHT_TWIPS;
+        }
+      }
+      contentHeight = Math.max(contentHeight, cellContentHeight + TABLE_ROW_PADDING_TWIPS);
+    }
+
+    let rowHeight: number;
+    if (heightRule === "exact" && explicitHeight > 0) {
+      rowHeight = explicitHeight;
+    } else if (heightRule === "atLeast" && explicitHeight > 0) {
+      rowHeight = Math.max(explicitHeight, contentHeight);
+    } else if (explicitHeight > 0) {
+      rowHeight = Math.max(explicitHeight, contentHeight);
+    } else {
+      rowHeight = contentHeight;
+    }
+
+    heights.push(Math.max(MIN_ROW_HEIGHT_TWIPS, rowHeight));
+  }
+
+  return heights;
+}
+
+/**
+ * Lightweight paragraph height estimate used when walking table cell
+ * content.  Matches the engine's internal measureTableHeight math
+ * (MIN_ROW_HEIGHT_TWIPS per paragraph) rather than delegating back to
+ * `measureBlockHeight`, which would require threading the
+ * per-invocation cache through.  Since cell content already re-runs
+ * through `measureBlockHeight` on the main pagination path, this
+ * helper is only used by `measureTableRowHeights` for the split-math
+ * preflight and does not affect canonical pagination.
+ */
+function measureParagraphStandaloneHeight(
+  _block: SurfaceBlockSnapshot,
+  _columnWidth: number,
+  _provider: LayoutMeasurementProvider | undefined,
+): number {
+  // P6.b scope: the engine's existing table measurement treats every
+  // cell paragraph as MIN_ROW_HEIGHT_TWIPS (see `measureTableHeight`
+  // inner loop).  P6.b preserves that exact constant so the split
+  // math agrees with pagination.  P6.c can upgrade this to call
+  // `measureBlockHeight` via the cache once the cache is threaded in.
+  return MIN_ROW_HEIGHT_TWIPS;
+}
+
+export interface FindTableRowSplitInput {
+  /** Per-row twip heights from `measureTableRowHeights`. */
+  rowHeights: readonly number[];
+  /** Parallel vector: true when row `k` has `w:cantSplit`. */
+  cantSplitFlags: readonly boolean[];
+  /** Parallel vector: true when row `k` has `w:tblHeader`. */
+  isHeaderFlags: readonly boolean[];
+  /** Twip space available on the current page before the table begins. */
+  remainingHeightTwips: number;
+  /**
+   * Twip height reserved on **continuation** pages for repeated header
+   * rows.  The engine computes this as the sum of row heights for every
+   * row flagged `isHeader` at indices 0..startRow-1.  P6.b accepts the
+   * value rather than recomputing it so the helper stays pure.
+   */
+  repeatedHeaderHeightTwips: number;
+  /**
+   * 0-based index of the first row to consider.  When a table has
+   * already been sliced onto the previous page, the caller passes the
+   * index of the first uncommitted row so split math resumes from the
+   * right place.  Defaults to 0.
+   */
+  startRow?: number;
+}
+
+export interface TableRowSplitDecision {
+  /**
+   * Number of rows from `startRow` that fit on the current page.  Zero
+   * when no row fits (caller should push the whole tail to the next
+   * page without splitting mid-table).
+   */
+  rowsOnCurrentPage: number;
+  /**
+   * Absolute index (not relative to `startRow`) of the row that begins
+   * the continuation page.  Equals `startRow + rowsOnCurrentPage`.
+   * When `rowsOnCurrentPage === 0`, equals `startRow`.
+   */
+  splitRowIndex: number;
+  /**
+   * Whether a continuation page is needed — equivalent to
+   * `splitRowIndex < rowHeights.length`.  Returned for convenience so
+   * callers can branch without recomputing.
+   */
+  continuationRequired: boolean;
+}
+
+/**
+ * Walk rows greedily from `startRow` onward, accumulating heights
+ * until the next row would exceed `remainingHeightTwips`.  Adjusts the
+ * split point backward past any `cantSplit` row that would straddle
+ * the boundary (so row K is never half on page N and half on page
+ * N+1 when K is marked cantSplit).
+ *
+ * Pure — no DOM, no state.  Deterministic.
+ */
+export function findTableRowSplit(
+  input: FindTableRowSplitInput,
+): TableRowSplitDecision {
+  const {
+    rowHeights,
+    cantSplitFlags,
+    isHeaderFlags,
+    remainingHeightTwips,
+    repeatedHeaderHeightTwips,
+  } = input;
+  const startRow = input.startRow ?? 0;
+  const totalRows = rowHeights.length;
+
+  if (startRow >= totalRows) {
+    return {
+      rowsOnCurrentPage: 0,
+      splitRowIndex: totalRows,
+      continuationRequired: false,
+    };
+  }
+  if (remainingHeightTwips <= 0) {
+    return {
+      rowsOnCurrentPage: 0,
+      splitRowIndex: startRow,
+      continuationRequired: startRow < totalRows,
+    };
+  }
+
+  // When resuming from a continuation, the header rows are repeated at
+  // the top so they consume the same space BEFORE we start fitting
+  // body rows.  `startRow === 0` means this is the first page and no
+  // headers are repeated yet.
+  const headerReservation = startRow > 0 ? repeatedHeaderHeightTwips : 0;
+
+  let consumed = headerReservation;
+  let candidate = startRow;
+  for (let k = startRow; k < totalRows; k += 1) {
+    const rowHeight = rowHeights[k] ?? MIN_ROW_HEIGHT_TWIPS;
+    if (consumed + rowHeight > remainingHeightTwips) {
+      break;
+    }
+    consumed += rowHeight;
+    candidate = k + 1;
+  }
+
+  // Honor cantSplit: if the row *before* the split boundary is marked
+  // cantSplit, the split index must move back past the entire
+  // contiguous run of cantSplit rows ending at `candidate - 1`.  The
+  // visible effect: a cantSplit row never lands as the last row of a
+  // page when the NEXT row overflows (because keeping the row together
+  // with the content it should stay with is the whole point of
+  // cantSplit).
+  //
+  // Edge case: if the FIRST row in [startRow..totalRows) is cantSplit
+  // and doesn't fit, we can't split at all — return rowsOnCurrentPage
+  // = 0 so the caller pushes a clean page break.
+  if (candidate > startRow && candidate < totalRows) {
+    while (candidate > startRow && cantSplitFlags[candidate - 1] === true) {
+      candidate -= 1;
+    }
+  }
+
+  // If candidate collapsed back to startRow due to cantSplit, check
+  // whether the first row itself fits.  If not, rowsOnCurrentPage = 0
+  // → push whole tail to next page.  If yes, include it.
+  if (candidate === startRow) {
+    return {
+      rowsOnCurrentPage: 0,
+      splitRowIndex: startRow,
+      continuationRequired: startRow < totalRows,
+    };
+  }
+
+  return {
+    rowsOnCurrentPage: candidate - startRow,
+    splitRowIndex: candidate,
+    continuationRequired: candidate < totalRows,
+  };
+}
+
+/**
+ * Convenience: compute the repeated-header-row height sum for a table
+ * given the per-row heights and the header flags.  This is the value
+ * the caller feeds into `findTableRowSplit.repeatedHeaderHeightTwips`.
+ */
+export function computeRepeatedHeaderHeight(
+  rowHeights: readonly number[],
+  isHeaderFlags: readonly boolean[],
+): number {
+  let total = 0;
+  for (let k = 0; k < isHeaderFlags.length; k += 1) {
+    if (isHeaderFlags[k] === true) {
+      total += rowHeights[k] ?? 0;
+    }
+  }
+  return total;
+}
+
+/**
+ * Extract parallel `cantSplitFlags` + `isHeaderFlags` vectors from a
+ * surface table block.  Small helper so tests + callers can feed the
+ * same representation into `findTableRowSplit` without re-walking the
+ * block.
+ */
+export function extractRowFlags(
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
+): { cantSplitFlags: boolean[]; isHeaderFlags: boolean[] } {
+  const cantSplitFlags = block.rows.map((r) => r.cantSplit === true);
+  const isHeaderFlags = block.rows.map((r) => r.isHeader === true);
+  return { cantSplitFlags, isHeaderFlags };
+}

package/src/runtime/markdown-sanitizer.ts

@@ -0,0 +1,132 @@
+export interface SanitizeResult {
+  text: string;
+  sanitized: boolean;
+}
+
+/**
+ * Minimum-viable sanitizer for the bw:commentPresentation markdown subset.
+ *
+ * Rejects:
+ *  - Raw HTML tags (`<script>`, `<img onerror=...>`, …).
+ *  - Inline-image markdown pointing at anything other than `bw:attachment:` —
+ *    external image URLs must go through the attachment table so the reader
+ *    can render them against a known relationship.
+ *  - Autolinks / link destinations using schemes other than `http:`, `https:`,
+ *    `mailto:`, `bw:user:`, `bw:attachment:`.
+ *
+ * Preserves the rest of the text verbatim so the digest remains stable after
+ * one sanitize pass. The goal is tamper-evident rendering, not a full
+ * CommonMark parser — callers MUST still run a proper renderer with the same
+ * whitelist when displaying the text.
+ */
+export function sanitizeMarkdown(raw: string): SanitizeResult {
+  let sanitized = false;
+  let text = raw;
+
+  // Autolinks (`<javascript:alert(1)>`, `<https://x>`, `<a@b.com>`) must be
+  // processed BEFORE the HTML-tag strip, otherwise the HTML regex eats the
+  // angle-bracket form as a pseudo-tag and the scheme check never runs.
+  text = text.replace(
+    /<([a-zA-Z][a-zA-Z0-9+.-]*:[^\s>]+)>/g,
+    (_match, target: string) => {
+      if (isAllowedLinkTarget(target)) {
+        return `<${target}>`;
+      }
+      sanitized = true;
+      // Wrap in backticks so downstream renderers treat it as inline code
+      // instead of a clickable link.  Keeping the literal text stabilizes
+      // the digest across sanitizer revisions.
+      return `\`${target}\``;
+    },
+  );
+  // Email autolinks (no URI scheme) — accept as-is so the HTML strip
+  // below treats the angle-bracket form as ordinary prose and we do not
+  // flag sanitized unnecessarily.
+  text = text.replace(
+    /<([A-Za-z0-9][A-Za-z0-9._%+-]*@[A-Za-z0-9.-]+\.[A-Za-z]{2,})>/g,
+    (_match, addr: string) => `<${addr}>`,
+  );
+
+  const strippedHtml = text.replace(
+    // Require a recognisable HTML tag name so we do not strip safe
+    // autolinks that survived the pass above (email autolinks, bare URIs).
+    /<\/?([A-Za-z][A-Za-z0-9-]*)(\s[^>]*)?\/?>/g,
+    (match, tagName: string) => {
+      // Skip angle-bracket content that looks like an autolink we just
+      // approved (email or scheme URI).
+      if (match.includes("://") || match.includes("@") || match.includes(":")) {
+        return match;
+      }
+      // Also skip plain URIs like `<example.com>` — rare, but preserve.
+      if (/^[a-z]+\.[a-z]/.test(tagName)) {
+        return match;
+      }
+      sanitized = true;
+      return "";
+    },
+  );
+  text = strippedHtml;
+
+  text = text.replace(
+    /!\[([^\]]*)\]\(([^)]+)\)/g,
+    (_match, alt: string, target: string) => {
+      if (target.startsWith("bw:attachment:")) {
+        return `![${alt}](${target})`;
+      }
+      sanitized = true;
+      return `[${alt}]`;
+    },
+  );
+
+  text = text.replace(
+    /\[([^\]]+)\]\(([^)]+)\)/g,
+    (_match, label: string, target: string) => {
+      if (isAllowedLinkTarget(target)) {
+        return `[${label}](${target})`;
+      }
+      sanitized = true;
+      return label;
+    },
+  );
+
+  // Reference-style link definitions: `[label]: target "optional title"`
+  // Renderers resolve `[foo][label]` against this table at render time,
+  // so a `[x]: javascript:alert(1)` bypasses the inline-link pass above.
+  // Strip definitions whose target is not in the scheme allowlist.
+  text = text.replace(
+    /^[ \t]*\[([^\]\n]+)\]:[ \t]*(\S+)(?:[ \t]+["(][^"\n)]*[")])?[ \t]*$/gm,
+    (match, _label: string, target: string) => {
+      if (isAllowedLinkTarget(target)) {
+        return match;
+      }
+      sanitized = true;
+      return "";
+    },
+  );
+
+  return { text, sanitized };
+}
+
+function isAllowedLinkTarget(target: string): boolean {
+  return (
+    target.startsWith("http://") ||
+    target.startsWith("https://") ||
+    target.startsWith("mailto:") ||
+    target.startsWith("bw:user:") ||
+    target.startsWith("bw:attachment:")
+  );
+}
+
+/**
+ * Synchronous SHA-256 hex digest used by `CommentBody.digest`. Uses the Node
+ * crypto module so the pipeline can hash during import/export without pulling
+ * in async. Callers that prefer WebCrypto can build their own.
+ */
+export async function sha256Hex(text: string): Promise<string> {
+  const { subtle } = globalThis.crypto;
+  const bytes = new TextEncoder().encode(text);
+  const digest = await subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}

package/src/runtime/participants.ts

@@ -0,0 +1,134 @@
+import * as Y from "yjs";
+
+import type {
+  Participant,
+  ParticipantRoster,
+} from "../api/participants-types.ts";
+
+const MAP_KEY = "participants";
+
+export interface ParticipantRosterStore {
+  get(userId: string): Participant | undefined;
+  /** Returns a synthetic "Unknown" row when the userId is not in the roster. */
+  resolve(userId: string): Participant;
+  upsert(entry: Participant): Participant;
+  remove(userId: string): void;
+  all(): Participant[];
+  snapshot(): ParticipantRoster;
+  subscribe(fn: (changedIds: string[]) => void): () => void;
+  ingestRemote(entry: Participant): void;
+  destroy(): void;
+}
+
+export function createParticipantRoster(ydoc: Y.Doc): ParticipantRosterStore {
+  const yMap = ydoc.getMap<Participant>(MAP_KEY);
+  const listeners = new Set<(ids: string[]) => void>();
+
+  const onChange = (event: Y.YMapEvent<Participant>): void => {
+    if (listeners.size === 0) return;
+    const ids = Array.from(event.keysChanged);
+    for (const fn of listeners) fn(ids);
+  };
+  yMap.observe(onChange);
+
+  return {
+    get: (id) => cloneMaybe(yMap.get(id)),
+    resolve: (id) => yMap.get(id)
+      ? clone(yMap.get(id)!)
+      : syntheticUnknown(id),
+    upsert: (entry) => {
+      const prev = yMap.get(entry.userId);
+      const normalized = normalize(entry);
+      const next: Participant = prev
+        ? { ...prev, ...normalized }
+        : normalized;
+      validate(next);
+      yMap.set(entry.userId, next);
+      return clone(next);
+    },
+    remove: (id) => {
+      yMap.delete(id);
+    },
+    all: () => Array.from(yMap.values()).map(clone),
+    snapshot: () => ({
+      schemaVersion: 1,
+      entries: Array.from(yMap.values()).map(clone),
+    }),
+    subscribe: (fn) => {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    },
+    ingestRemote: (entry) => {
+      validate(entry);
+      yMap.set(entry.userId, clone(normalize(entry)));
+    },
+    destroy: () => {
+      yMap.unobserve(onChange);
+      listeners.clear();
+    },
+  };
+}
+
+function normalize(p: Participant): Participant {
+  const next: Participant = {
+    userId: p.userId,
+    email: p.email.toLowerCase(),
+    displayName: p.displayName,
+    collabIdentity: p.collabIdentity,
+    authorKind: p.authorKind,
+  };
+  if (p.role !== undefined) next.role = p.role;
+  if (p.organization !== undefined) next.organization = p.organization;
+  if (p.avatarHref !== undefined) {
+    if (p.avatarHref.startsWith("https://")) {
+      next.avatarHref = p.avatarHref;
+    }
+    // silently drop non-https: schemes per schema rule
+  }
+  return next;
+}
+
+function validate(p: Participant): void {
+  if (!p.userId) {
+    throw new Error("participant.userId is required");
+  }
+  if (!p.email) {
+    throw new Error(`participant.email is required (userId=${p.userId})`);
+  }
+  if (!p.displayName) {
+    throw new Error(`participant.displayName is required (userId=${p.userId})`);
+  }
+  if (!p.collabIdentity) {
+    throw new Error(`participant.collabIdentity is required (userId=${p.userId})`);
+  }
+}
+
+function clone(p: Participant): Participant {
+  const copy: Participant = {
+    userId: p.userId,
+    email: p.email,
+    displayName: p.displayName,
+    collabIdentity: p.collabIdentity,
+    authorKind: p.authorKind,
+  };
+  if (p.role !== undefined) copy.role = p.role;
+  if (p.organization !== undefined) copy.organization = p.organization;
+  if (p.avatarHref !== undefined) copy.avatarHref = p.avatarHref;
+  return copy;
+}
+
+function cloneMaybe(p: Participant | undefined): Participant | undefined {
+  return p ? clone(p) : undefined;
+}
+
+function syntheticUnknown(userId: string): Participant {
+  return {
+    userId,
+    email: "",
+    displayName: "Unknown",
+    collabIdentity: "",
+    authorKind: "human",
+  };
+}

package/src/runtime/perf-counters.ts

@@ -0,0 +1,28 @@
+/**
+ * Lightweight string-keyed counters for L7 render-perf instrumentation.
+ *
+ * Used by the runtime to prove (in tests and benchmarks) that a given
+ * facet rebuild ran or did not run during a sequence of operations.
+ * Phase 0 wires `refresh.all`; Phase 1 will add `facet.<name>.build`
+ * keyed on the per-facet builder.
+ *
+ * Cost guarantee: a `Map<string, number>` increment is < 100 ns. We do
+ * not need atomic counters — JS is single-threaded — and we deliberately
+ * keep the surface tiny so this module can never become a perf footgun
+ * on its own.
+ */
+export class PerfCounters {
+  private readonly counts = new Map<string, number>();
+
+  increment(key: string, delta = 1): void {
+    this.counts.set(key, (this.counts.get(key) ?? 0) + delta);
+  }
+
+  snapshot(): Record<string, number> {
+    return Object.fromEntries(this.counts);
+  }
+
+  reset(): void {
+    this.counts.clear();
+  }
+}

package/src/runtime/render/render-frame-types.ts

@@ -56,6 +56,23 @@ export interface RenderPageRegions {
   footer?: RenderStoryRegion;
   columns?: readonly RenderStoryRegion[];
   footnoteArea?: RenderStoryRegion;
+  /**
+   * P8.3 — footnote areas reserved at the bottom of the page (above the
+   * footer band). Mirrors the page graph's `RuntimePageRegions.footnotes`
+   * — one entry per allocated region (typically one per page today, but
+   * shape allows for multiple should allocation-splitting land).
+   * Populated only when `PublicPageRegions.footnotes` is non-empty.
+   * Additive — back-compat safe; consumers that ignore this field see no
+   * change.
+   */
+  footnotes?: readonly RenderStoryRegion[];
+  /**
+   * P8.3 — endnote regions. Reserved seam; per-page endnote projection is
+   * NOT populated today (endnotes use document-end placement via
+   * `facet.getDocumentEndnoteBlocks()`). Shape exists so a future
+   * per-section endnote renderer has a stable read surface.
+   */
+  endnotes?: readonly RenderStoryRegion[];
 }
 
 export interface RenderStoryRegion {