@beyondwork/docx-react-component 1.0.53 → 1.0.55

package/src/runtime/chart/chart-snapshot.ts

@@ -0,0 +1,239 @@
+/**
+ * Public read-model for chart data. Projected from a `ChartModel` parsed during
+ * DOCX import. Agents consume this without re-parsing `rawXml`.
+ */
+
+import type {
+  ChartModel,
+  BarChartModel,
+  LineChartModel,
+  PieChartModel,
+  AreaChartModel,
+  ScatterChartModel,
+  BubbleChartModel,
+  ComboChartModel,
+} from "../../io/ooxml/chart/types.ts";
+
+export interface ChartSnapshot {
+  chartId: string;
+  kind: ChartModel["kind"];
+  title?: string;
+  seriesCount: number;
+  categoryCount: number;
+  data: ChartSnapshotData;
+}
+
+export type ChartSnapshotData =
+  | {
+      kind: "bar";
+      direction: "bar" | "column";
+      grouping: "clustered" | "stacked" | "percentStacked" | "standard";
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | {
+      kind: "line";
+      grouping: "standard" | "stacked" | "percentStacked";
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | {
+      kind: "pie";
+      doughnut: boolean;
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | {
+      kind: "area";
+      grouping: "standard" | "stacked" | "percentStacked";
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | { kind: "scatter"; series: ChartSnapshotScatterSeries[] }
+  | { kind: "bubble"; series: ChartSnapshotBubbleSeries[] }
+  | {
+      kind: "combo";
+      groups: Array<{ kind: "bar" | "line" | "area"; series: ChartSnapshotSeries[] }>;
+      categories: string[];
+    }
+  | { kind: "unsupported"; reason: string };
+
+export interface ChartSnapshotSeries {
+  name?: string;
+  values: Array<number | null>;
+}
+
+export interface ChartSnapshotScatterSeries {
+  name?: string;
+  xValues: Array<number | null>;
+  yValues: Array<number | null>;
+}
+
+export interface ChartSnapshotBubbleSeries {
+  name?: string;
+  xValues: Array<number | null>;
+  yValues: Array<number | null>;
+  sizes: Array<number | null>;
+}
+
+export function projectChartSnapshot(chartId: string, model: ChartModel): ChartSnapshot {
+  switch (model.kind) {
+    case "bar": {
+      const m = model as BarChartModel;
+      const categories = m.categoryAxis.kind === "category"
+        ? m.categoryAxis.categoryLabels
+        : (m.series[0]?.categories ?? []);
+      return {
+        chartId,
+        kind: "bar",
+        title: m.title?.text,
+        seriesCount: m.series.length,
+        categoryCount: categories.length,
+        data: {
+          kind: "bar",
+          direction: m.direction,
+          grouping: m.grouping,
+          series: m.series.map((s) => ({ name: s.name, values: s.values })),
+          categories,
+        },
+      };
+    }
+    case "line": {
+      const m = model as LineChartModel;
+      const categories = m.categoryAxis.kind === "category"
+        ? m.categoryAxis.categoryLabels
+        : (m.series[0]?.categories ?? []);
+      return {
+        chartId,
+        kind: "line",
+        title: m.title?.text,
+        seriesCount: m.series.length,
+        categoryCount: categories.length,
+        data: {
+          kind: "line",
+          grouping: m.grouping,
+          series: m.series.map((s) => ({ name: s.name, values: s.values })),
+          categories,
+        },
+      };
+    }
+    case "pie": {
+      const m = model as PieChartModel;
+      return {
+        chartId,
+        kind: "pie",
+        title: m.title?.text,
+        seriesCount: m.series.length,
+        categoryCount: m.categoryLabels.length,
+        data: {
+          kind: "pie",
+          doughnut: m.doughnut,
+          series: m.series.map((s) => ({ name: s.name, values: s.values })),
+          categories: m.categoryLabels,
+        },
+      };
+    }
+    case "area": {
+      const m = model as AreaChartModel;
+      const categories = m.categoryAxis.kind === "category"
+        ? m.categoryAxis.categoryLabels
+        : (m.series[0]?.categories ?? []);
+      return {
+        chartId,
+        kind: "area",
+        title: m.title?.text,
+        seriesCount: m.series.length,
+        categoryCount: categories.length,
+        data: {
+          kind: "area",
+          grouping: m.grouping,
+          series: m.series.map((s) => ({ name: s.name, values: s.values })),
+          categories,
+        },
+      };
+    }
+    case "scatter": {
+      const m = model as ScatterChartModel;
+      return {
+        chartId,
+        kind: "scatter",
+        seriesCount: m.series.length,
+        categoryCount: 0,
+        data: {
+          kind: "scatter",
+          series: m.series.map((s) => ({
+            name: s.name,
+            xValues: s.xValues,
+            yValues: s.yValues,
+          })),
+        },
+      };
+    }
+    case "bubble": {
+      const m = model as BubbleChartModel;
+      return {
+        chartId,
+        kind: "bubble",
+        seriesCount: m.series.length,
+        categoryCount: 0,
+        data: {
+          kind: "bubble",
+          series: m.series.map((s) => ({
+            name: s.name,
+            xValues: s.xValues,
+            yValues: s.yValues,
+            sizes: s.sizes,
+          })),
+        },
+      };
+    }
+    case "combo": {
+      const m = model as ComboChartModel;
+      const firstGroup = m.groups[0];
+      const categories =
+        firstGroup && "categoryAxis" in firstGroup &&
+        firstGroup.categoryAxis?.kind === "category"
+          ? firstGroup.categoryAxis.categoryLabels
+          : [];
+      return {
+        chartId,
+        kind: "combo",
+        title: m.title?.text,
+        seriesCount: m.groups.reduce((acc, g) => acc + g.series.length, 0),
+        categoryCount: categories.length,
+        data: {
+          kind: "combo",
+          groups: m.groups.map((g) => ({
+            kind: g.kind as "bar" | "line" | "area",
+            series: "series" in g
+              ? g.series.map((s) => ({
+                  name: s.name,
+                  values: "values" in s ? s.values : [],
+                }))
+              : [],
+          })),
+          categories,
+        },
+      };
+    }
+    case "unsupported": {
+      return {
+        chartId,
+        kind: "unsupported",
+        seriesCount: 0,
+        categoryCount: 0,
+        data: { kind: "unsupported", reason: model.detail },
+      };
+    }
+    default: {
+      const _exhaustive: never = model;
+      return {
+        chartId,
+        kind: (_exhaustive as ChartModel).kind,
+        seriesCount: 0,
+        categoryCount: 0,
+        data: { kind: "unsupported", reason: "unknown chart kind" },
+      };
+    }
+  }
+}

package/src/runtime/collab/checkpoint-store.ts

@@ -30,7 +30,7 @@ export interface Checkpoint {
   authorClientId: number;
 }
 
-const CHECKPOINTS_KEY = "checkpoints";
+export const CHECKPOINTS_KEY = "checkpoints";
 
 export interface CreateCheckpointStoreOptions {
   ydoc: Y.Doc;

package/src/runtime/collab/event-types.ts

@@ -141,6 +141,10 @@ export const BROADCAST_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new S
   "section.set-header-footer-link",
   "content.insert-page-break",
   "content.insert-table",
+  // C1: Shift+Tab list/paragraph de-indent — produces a document mutation, must broadcast
+  "text.outdent-tab",
+  // C2: host insertFragment() API — routes through executeEditorCommand same as other mutations
+  "fragment.insert",
 ]);
 
 /**

package/src/runtime/collab/runtime-collab-sync.ts

@@ -22,7 +22,7 @@ import {
   type CommandEvent,
 } from "./event-types.ts";
 import { computeBaseDocFingerprint } from "./base-doc-fingerprint.ts";
-import type { Checkpoint } from "./checkpoint-store.ts";
+import { CHECKPOINTS_KEY, type Checkpoint } from "./checkpoint-store.ts";
 import { createWorkflowShared, type WorkflowSharedHandle } from "./workflow-shared.ts";
 
 /** Shared Y.Map key — {@link SHARED_META_MAP_KEY}. */
@@ -30,7 +30,6 @@ const SHARED_META_MAP_KEY = "meta";
 const META_BASE_DOC_HASH_KEY = "baseDocHash";
 const META_SCHEMA_VERSION_KEY = "schemaVersion";
 const META_CREATED_AT_KEY = "createdAt";
-const CHECKPOINTS_KEY = "checkpoints";
 
 /**
  * Lifecycle + correctness events surfaced by a

package/src/runtime/document-runtime.ts

@@ -242,6 +242,7 @@ import type {
 import { collectEditorStateForSerialize } from "./editor-state-integration.ts";
 import type { EditorStatePayload } from "../io/ooxml/workflow-payload.ts";
 import type { SharedWorkflowState } from "./collab/workflow-shared.ts";
+import { formatPageNumber } from "./page-number-format.ts";
 
 /** Internal extension of ExportDocxOptions that threads the collected
  *  editorState payload from the runtime to the docx serializer. */
@@ -5196,8 +5197,34 @@ function refreshDocumentTableOfContents(
   protectionSelection?: import("../core/state/editor-state.ts").SelectionSnapshot;
 } {
   const navigation = createDocumentNavigationSnapshot(document, selectionHead, activeStory);
+  // Build a single O(N) map from paragraph offset → bookmark name so the
+  // per-heading lookup below is O(1) instead of O(N) per heading.
+  const bookmarkNameByOffset = new Map<number, string>();
+  {
+    let runningOffset = 0;
+    for (const block of document.content.children) {
+      if (block.type !== "paragraph") {
+        continue;
+      }
+      const paragraphStart = runningOffset;
+      for (const child of block.children) {
+        if (child.type === "text") {
+          runningOffset += child.text.length;
+        } else if (child.type === "tab" || child.type === "hard_break") {
+          runningOffset += 1;
+        }
+      }
+      const bookmarkStart = block.children.find(
+        (child): child is Extract<typeof child, { type: "bookmark_start" }> =>
+          child.type === "bookmark_start" && Boolean(child.name),
+      );
+      if (bookmarkStart?.name) {
+        bookmarkNameByOffset.set(paragraphStart, bookmarkStart.name);
+      }
+    }
+  }
   let changed = false;
-  let resultEntries: Array<{ level: number; text: string; pageIndex: number }> = [];
+  let resultEntries: Array<{ level: number; text: string; pageIndex: number; bookmarkName?: string }> = [];
   let changedFrom: number | undefined;
   let changedTo: number | undefined;
   const nextChildren = refreshBlocksWithCursor(document.content.children, (field, range) => {
@@ -5209,11 +5236,15 @@ function refreshDocumentTableOfContents(
       : parseTocLevelRange(field.instruction);
     const entries = navigation.headings
       .filter((heading) => heading.level >= levelRange.from && heading.level <= levelRange.to)
-      .map((heading) => ({
-        level: heading.level,
-        text: heading.text,
-        pageIndex: heading.pageIndex,
-      }));
+      .map((heading) => {
+        const bookmarkName = bookmarkNameByOffset.get(heading.offset);
+        return {
+          level: heading.level,
+          text: heading.text,
+          pageIndex: heading.pageIndex,
+          ...(bookmarkName ? { bookmarkName } : {}),
+        };
+      });
     if (resultEntries.length === 0) {
       resultEntries = entries;
     }
@@ -5410,12 +5441,20 @@ function buildInlineNodesFromDisplayText(text: string): InlineNode[] {
  * resolver, falls back to the raw `pageIndex + 1` (pre-P5 behavior).
  */
 function buildTocInlineNodes(
-  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number }>,
+  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number; bookmarkName?: string }>,
   resolveDisplayPageNumber?: (pageIndex: number) => number | null,
 ): InlineNode[] {
   const children: InlineNode[] = [];
   entries.forEach((entry, index) => {
-    children.push({ type: "text", text: entry.text });
+    if (entry.bookmarkName) {
+      children.push({
+        type: "hyperlink",
+        href: `#${entry.bookmarkName}`,
+        children: [{ type: "text", text: entry.text }],
+      });
+    } else {
+      children.push({ type: "text", text: entry.text });
+    }
     children.push({ type: "tab" });
     const displayed = resolveDisplayPageNumber?.(entry.pageIndex);
     children.push({
@@ -5431,7 +5470,7 @@ function buildTocInlineNodes(
 
 /** Test-only export of `buildTocInlineNodes` (P5 unit tests). */
 export function __buildTocInlineNodes(
-  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number }>,
+  entries: ReadonlyArray<{ level: number; text: string; pageIndex: number; bookmarkName?: string }>,
   resolveDisplayPageNumber?: (pageIndex: number) => number | null,
 ): InlineNode[] {
   return buildTocInlineNodes(entries, resolveDisplayPageNumber);
@@ -5471,6 +5510,38 @@ function collectFieldsFromSubParts(
   return nextIndex;
 }
 
+function resolveStyleRefFieldText(
+  styleQuery: string,
+  paragraphs: readonly ParagraphContext[],
+  styles: CanonicalDocumentEnvelope["styles"],
+): { text: string; refreshStatus: FieldRefreshStatus } {
+  const normalized = styleQuery.trim().toLowerCase();
+
+  // Look up styleId: first by direct id match, then by displayName
+  const styleId = (() => {
+    const byId = Object.keys(styles.paragraphs).find(
+      (id) => id.toLowerCase() === normalized,
+    );
+    if (byId) return byId;
+    const byName = Object.values(styles.paragraphs).find(
+      (s) => s.displayName?.toLowerCase() === normalized,
+    );
+    return byName?.styleId;
+  })();
+
+  if (!styleId) return { text: "", refreshStatus: "unresolvable" };
+
+  // Walk paragraphs top-down for the first matching styleId
+  for (const ctx of paragraphs) {
+    if (ctx.paragraph.styleId === styleId) {
+      const text = flattenInlineDisplayText(ctx.paragraph.children);
+      if (text.trim()) return { text: text.trim(), refreshStatus: "current" };
+    }
+  }
+
+  return { text: "", refreshStatus: "unresolvable" };
+}
+
 function resolveSupportedFieldDisplay(
   field: FieldNode,
   document: CanonicalDocumentEnvelope,
@@ -5485,13 +5556,30 @@ function resolveSupportedFieldDisplay(
   if (field.fieldFamily === "TOC") {
     return undefined;
   }
+  if (field.fieldFamily === "STYLEREF") {
+    if (!field.fieldTarget) return { displayText: "", refreshStatus: "unresolvable" };
+    const result = resolveStyleRefFieldText(field.fieldTarget, paragraphs, document.styles);
+    return { displayText: result.text, refreshStatus: result.refreshStatus };
+  }
+  if (field.fieldFamily === "SECTIONPAGES") {
+    const sectionIndex = "sectionIndex" in storyTarget && typeof storyTarget.sectionIndex === "number"
+      ? storyTarget.sectionIndex
+      : navigation.activeSectionIndex;
+    const sectionPages = navigation.pages.filter((p) => p.sectionIndex === sectionIndex);
+    if (sectionPages.length === 0) return { displayText: "", refreshStatus: "unresolvable" };
+    const fmt = sectionPages[0]?.layout.pageNumbering?.format;
+    return {
+      displayText: formatPageNumber(sectionPages.length, fmt),
+      refreshStatus: "current",
+    };
+  }
   if (field.fieldFamily === "PAGE") {
     const page = resolveRepresentativePageForStory(navigation, storyTarget);
     if (!page) {
       return { displayText: "", refreshStatus: "unresolvable" };
     }
     return {
-      displayText: String(resolveDisplayedPageNumber(page)),
+      displayText: resolveDisplayedPageNumber(page),
       refreshStatus: "current",
     };
   }
@@ -5522,10 +5610,23 @@ function resolveSupportedFieldDisplay(
     if (!paragraph) {
       return { displayText: "", refreshStatus: "unresolvable" };
     }
+
+    // \p switch: emit relative position text ("above" / "below" / "on this page")
+    if (field.switches?.relativePosition === true) {
+      const fieldPage = resolveRepresentativePageForStory(navigation, storyTarget);
+      const targetPageIndex = findPageForOffset(navigation.pages, paragraph.startOffset);
+      const fieldPageIndex = fieldPage
+        ? navigation.pages.indexOf(fieldPage)
+        : navigation.activePageIndex;
+      if (targetPageIndex < fieldPageIndex) return { displayText: "above", refreshStatus: "current" };
+      if (targetPageIndex > fieldPageIndex) return { displayText: "below", refreshStatus: "current" };
+      return { displayText: "on this page", refreshStatus: "current" };
+    }
+
     const pageIndex = findPageForOffset(navigation.pages, paragraph.startOffset);
     const page = navigation.pages[pageIndex] ?? navigation.pages[0];
     return page
-      ? { displayText: String(resolveDisplayedPageNumber(page)), refreshStatus: "current" }
+      ? { displayText: resolveDisplayedPageNumber(page), refreshStatus: "current" }
       : { displayText: "", refreshStatus: "unresolvable" };
   }
   if (field.fieldFamily === "NOTEREF") {
@@ -5584,8 +5685,9 @@ function isDefaultHeaderFooterPage(
 
 function resolveDisplayedPageNumber(
   page: DocumentNavigationSnapshot["pages"][number],
-): number {
-  return (page.layout.pageNumbering?.start ?? 1) + page.pageInSection;
+): string {
+  const n = (page.layout.pageNumbering?.start ?? 1) + page.pageInSection;
+  return formatPageNumber(n, page.layout.pageNumbering?.format);
 }
 
 interface ParagraphContext {

package/src/runtime/layout/inert-layout-facet.ts

@@ -59,6 +59,7 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     swapMeasurementProvider: () => undefined,
     invalidateMeasurementCache: () => undefined,
     getTableRenderPlan: () => null,
+    getTableBodyYOffsetOnPage: () => null,
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,
     setVisibleBlockRange: () => undefined,

package/src/runtime/layout/layout-engine-version.ts

@@ -113,6 +113,13 @@
  *       pages so chrome can prepend header rows visually. No
  *       pixel-geometry change; cache envelopes from v11 invalidate
  *       because the table-render-plan contract changed.
+ *  13 — Lane 6d.U2 canvas-seam pill polish: the canvas-posture page-break
+ *       widget's "N / M" badge is promoted from transparent text over the
+ *       dotted seam to a true pill with `--radius-pill` geometry, hairline
+ *       `--color-border-default` border, and `--shadow-soft`. Widget DOM
+ *       shape changed (new `data-variant="pill"` attribute; additional
+ *       inline style declarations on the badge). Cache envelopes from v12
+ *       invalidate because the decoration's cacheable DOM shape changed.
  *  13 — Lane 3a P14.c: render-kernel gains a single-slot `DecorationIndex`
  *       cache keyed on (revision, activeStory.kind, zoom.pxPerTwip, and
  *       reference equality on each decoration source). When layout
@@ -122,8 +129,58 @@
  *       rebuild path (on every keystroke that triggers a layout event).
  *       No pixel-geometry change; cache envelopes from v12 invalidate
  *       because the render-kernel source changed.
+ *  14 — Lane 3a Slice 5: `RuntimeBlockFragment` gains `resolvedStyleChainRef`
+ *       (block's styleId) and `numberingInstanceId` (block's list-instance id).
+ *       `analyzeInvalidation` for `styles-change` (when `dirtyStyleIds` is
+ *       supplied) and `numbering-change` (when `numberingInstanceId` is
+ *       supplied) now return `scope: "bounded"` starting from the first page
+ *       whose fragments reference the dirty style / instance. Fallback to
+ *       `scope: "full"` when payload is absent or no match found. No
+ *       pixel-geometry change; cache envelopes from v13 invalidate because
+ *       the fragment shape and invalidation-scope contract changed.
+ *  15 — Bug fixes: `pageNodesStructurallyEqual` now compares
+ *       `lineBoxes.length` and `noteAllocations.length` as structural
+ *       proxies to prevent stale-node reuse when line geometry changes
+ *       with stable fragment IDs (L1). `analyzeSectionChange` normalizes
+ *       `dirtySectionRange` to guarantee from ≤ to for all graph states
+ *       including empty-sections fallback (L2).
+ *  16 — Bug fixes: `diffRenderFrames` now flags pages whose physical frame
+ *       changed (but block regions are stable) with `pageFrameChanged: true`
+ *       in `changedPages` so consumers can re-project without a block-region
+ *       signal (R1). Chrome reservation changes (`railLaneTwips`,
+ *       `balloonLaneTwips`, `footnoteAreaTwips`, `pageFrameWidthPx`,
+ *       `pageFrameHeightPx`) now trigger `changedPages` so overlay
+ *       re-projection is not silently skipped (R2).
+ *  17 — Lane 3a Slice 2 + R4: `WordReviewEditorLayoutFacet` gains
+ *       `getTableBodyYOffsetOnPage(blockId, pageIndex)` which returns the
+ *       Y offset (in twips from body top) of the table's first fragment on
+ *       a given page by summing prior body-fragment heights. Used by the
+ *       new `TwTableContinuationHeader` chrome overlay to position repeated
+ *       header rows on continuation pages of multi-page tables — no DOM
+ *       measurement, layout-engine fragment heights only. No cached-geometry
+ *       change; cache envelopes from v16 invalidate because the facet
+ *       interface changed.
+ *  18 — Lane 3a Slice 6: `buildPageStackFromWithSplits` no longer discards
+ *       `resumeAt.startOffset`. When `startOffset > 0` and no block
+ *       straddles the dirty section boundary, only sections at and after
+ *       the first dirty section are paginated; the resulting page indices
+ *       are shifted by `startPageIndex` so they align with the global graph.
+ *       Full-paginate + tail-slice fallback used when a block straddles the
+ *       section boundary (safety guard). This eliminates re-paginating
+ *       settled head sections on every bounded-invalidation relayout.
+ *       No pixel-geometry change; cache envelopes from v17 invalidate
+ *       because `buildPageStackFromWithSplits` output contract changed.
+ *  19 — Slice 5 bug-fix: `analyzeNumberingChange` now honors its own
+ *       "Fallback to full rebuild when absent or no match" contract. When
+ *       `numberingInstanceId` is supplied but no materialized fragment
+ *       matches it, the analyzer returns `scope: "full"` +
+ *       `requiresFullRecompute: true` instead of the prior "bounded over
+ *       full range" shortcut, which bypassed the safety guard and could
+ *       leak stale field-family projections. No pixel-geometry change;
+ *       cache envelopes from v18 invalidate because the invalidation
+ *       classifier's contract corrected.
  */
-export const LAYOUT_ENGINE_VERSION = 13 as const;
+export const LAYOUT_ENGINE_VERSION = 19 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope