@beyondwork/docx-react-component 1.0.50 → 1.0.51

package/src/runtime/render/render-kernel.ts

@@ -36,6 +36,7 @@ import {
   type SearchMatchRange,
 } from "./decoration-resolver.ts";
 import { classifyBlockKind as classifyBlockKindFromId } from "./block-fragment-projection.ts";
+import { diffRenderFrames } from "./render-frame-diff.ts";
 import {
   EMPTY_DECORATION_INDEX,
   defaultChromeReservations,
@@ -141,6 +142,11 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
   const getActiveStory = input.getActiveStory ?? (() => MAIN_STORY_TARGET);
   let zoom: RenderZoom = input.initialZoom ?? resolveDefaultZoom();
   let cache: { revision: number; frame: RenderFrame } | null = null;
+  // P10 Phase B — retained across `invalidate()` and `cache = null` so
+  // `frame_diff` can compute a meaningful diff when the next build
+  // produces a structurally-equal frame. Distinct from `cache`, which
+  // is an optimizer for repeat reads at the same revision.
+  let lastEmittedFrame: RenderFrame | null = null;
 
   const listeners = new Set<(event: RenderKernelEvent) => void>();
   const unsubscribeFacet = facet.subscribe((event) => {
@@ -254,6 +260,20 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
       if (options === undefined) {
         cache = { revision: frame.revision, frame };
         emit({ kind: "frame_built", revision: frame.revision, reason: "full" });
+        // P10 Phase B — compute structural diff vs. the last emitted
+        // frame (retained across `invalidate()`) so page-stack consumers
+        // can skip React reconciliation on unchanged pages even after
+        // a cache invalidation. On cold start (no prior emission) the
+        // diff reports every page in `addedPages`, giving the initial
+        // mount a consistent subscription contract.
+        const diffT0 =
+          typeof performance !== "undefined" ? performance.now() : 0;
+        const diff = diffRenderFrames(lastEmittedFrame, frame);
+        if (diffT0 > 0) {
+          recordPerfSample("render.frame_diff", performance.now() - diffT0);
+        }
+        emit({ kind: "frame_diff", revision: frame.revision, diff });
+        lastEmittedFrame = frame;
       }
       return frame;
     },
@@ -688,25 +708,31 @@ function buildAnchorIndex(
     }
   }
 
-  // Pending-op deltas are read here as a seam for a future decoration-
-  // resolver-driven rect shift; today the kernel does not mutate rects
-  // during the predicted-dispatch window because the correct reconciliation
-  // belongs to R4's decoration resolver (it needs per-line width info the
-  // MVP doesn't surface yet).  The deltas are still read so consumers can
-  // rely on the accessor shape landing now.
-  void pendingDeltas;
+  // P9 Phase A2 — during the predicted-dispatch window, runtime offsets
+  // passed in by chrome surfaces reflect the visible (predicted) text but
+  // the anchor-index maps are keyed on the *pre-delta* runtime offsets
+  // emitted by the last-committed page graph. Shift the lookup offset
+  // back by the sum of deltas applied at or before it so chrome rects
+  // stay aligned with the caret while the predicted text is on screen.
+  // The rect pixel positions are correct as drawn — only the offset →
+  // rect mapping needs compensation.
+  const shiftForDeltas = (offset: number): number => {
+    if (pendingDeltas.length === 0) return offset;
+    return offset - sumDeltasBefore(pendingDeltas, offset);
+  };
 
   const resolveByRuntimeOffset = (
     offset: number,
     _story?: EditorStoryTarget,
   ): RenderFrameRect | null => {
     void _story;
-    const exact = byRuntimeOffset.get(offset);
+    const lookup = shiftForDeltas(offset);
+    const exact = byRuntimeOffset.get(lookup);
     if (exact) return exact;
     let best: RenderFrameRect | null = null;
     let bestDistance = Number.POSITIVE_INFINITY;
     for (const [key, rect] of byRuntimeOffset) {
-      const distance = Math.abs(key - offset);
+      const distance = Math.abs(key - lookup);
       if (distance < bestDistance) {
         best = rect;
         bestDistance = distance;
@@ -734,9 +760,13 @@ function buildAnchorIndex(
       if (lo === hi) {
         return resolveByRuntimeOffset(lo, story);
       }
+      // Shift range endpoints back to pre-delta space before iterating
+      // the anchor maps (see `shiftForDeltas` rationale above).
+      const loShifted = shiftForDeltas(lo);
+      const hiShifted = shiftForDeltas(hi);
       let union: RenderFrameRect | null = null;
       for (const [key, rect] of byRuntimeOffset) {
-        if (key < lo || key >= hi) continue;
+        if (key < loShifted || key >= hiShifted) continue;
         union = unionRects(union, rect);
       }
       if (union) return union;

package/src/runtime/selection/cursor-ops.ts

@@ -0,0 +1,202 @@
+/**
+ * R.1 Phase 6a — SelectionLayer cursor primitives.
+ *
+ * Pure functions over `(DocumentRootNode, CursorSelection, op) → CursorSelection`.
+ * `extend: true` keeps the anchor fixed and moves only the head — the
+ * LibreOffice `SwPaM` head/anchor split that matches Shift+arrow semantics.
+ *
+ * Positions are 0-based logical positions per the canonical story layer
+ * (`createPlainText(parseTextStory(doc))`). Scope markers are zero-width;
+ * paragraph breaks are 1 wide; text / tab / hard_break / image / opaque are 1
+ * wide. The plain-text string produced by `createPlainText` is a 1:1 mapping
+ * of those logical positions to characters, which makes position-math trivial
+ * and makes `Intl.Segmenter` (for word boundaries) a drop-in fit.
+ *
+ * What this module deliberately does NOT ship yet:
+ *   - `moveUp` / `moveDown` — genuinely layout-dependent (need column tracking
+ *     + line-wrap info). Follows Phase 6b once Lane 3a P9 exposes the per-run
+ *     layout facet needed for column-preserving movement.
+ *   - `moveLineStart` / `moveLineEnd` — same; these need soft-wrap info that
+ *     the canonical story layer does not expose.
+ */
+
+import { createPlainText, parseTextStory } from "../../core/schema/text-schema.ts";
+import type { DocumentRootNode } from "../../model/canonical-document.ts";
+
+export interface CursorSelection {
+  anchor: number;
+  head: number;
+}
+
+export interface CursorMoveOptions {
+  /**
+   * When true, the anchor stays fixed and only the head moves — matches
+   * Shift+arrow "extend selection" semantics. When false (default), both
+   * anchor and head land at the new head, collapsing any range selection.
+   */
+  extend?: boolean;
+}
+
+export function moveCharLeft(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  // Word semantics (no-extend): a range selection collapses to the LEFT edge
+  // without moving; only a collapsed caret actually decrements by one.
+  if (!options.extend && selection.anchor !== selection.head) {
+    const leftEdge = Math.min(selection.anchor, selection.head);
+    return { anchor: leftEdge, head: leftEdge };
+  }
+  const currentHead = selection.head;
+  const nextHead = Math.max(0, currentHead - 1);
+  return finalize(selection, nextHead, options);
+}
+
+export function moveCharRight(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  // Word semantics (no-extend): a range selection collapses to the RIGHT edge
+  // without moving; only a collapsed caret actually increments by one.
+  if (!options.extend && selection.anchor !== selection.head) {
+    const rightEdge = Math.max(selection.anchor, selection.head);
+    return { anchor: rightEdge, head: rightEdge };
+  }
+  const currentHead = selection.head;
+  const nextHead = Math.min(text.length, currentHead + 1);
+  return finalize(selection, nextHead, options);
+}
+
+export function moveParagraphStart(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const head = options.extend ? selection.head : selection.head;
+  // Walk backward until we find a paragraph break ('\n') or reach 0. The
+  // paragraph start is the character immediately after the break.
+  let cursor = Math.max(0, Math.min(text.length, head));
+  while (cursor > 0 && text[cursor - 1] !== "\n") {
+    cursor -= 1;
+  }
+  return finalize(selection, cursor, options);
+}
+
+export function moveParagraphEnd(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const head = options.extend ? selection.head : selection.head;
+  let cursor = Math.max(0, Math.min(text.length, head));
+  while (cursor < text.length && text[cursor] !== "\n") {
+    cursor += 1;
+  }
+  return finalize(selection, cursor, options);
+}
+
+/**
+ * `Intl.Segmenter` with `granularity: "word"` returns ICU word boundaries —
+ * the standards-backed equivalent of LibreOffice's `SwBreakIt`. We walk the
+ * boundary list (cached per-`doc` call) to find the next / previous
+ * word-start relative to the head, matching Word's Ctrl+arrow behavior.
+ *
+ * Word semantics:
+ *   - Ctrl+Right: jump to the end of the current word, OR to the end of the
+ *     next word if already at word-end. In practice we land on the next
+ *     word-boundary strictly greater than the current head.
+ *   - Ctrl+Left: jump to the start of the current word, OR to the start of
+ *     the previous word if already at word-start. We land on the previous
+ *     word-boundary strictly less than the current head.
+ */
+export function moveWordRight(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const currentHead = options.extend
+    ? selection.head
+    : Math.max(selection.anchor, selection.head);
+  const boundaries = wordBoundaries(text);
+  const nextBoundary =
+    boundaries.find((pos) => pos > currentHead) ?? text.length;
+  return finalize(selection, nextBoundary, options);
+}
+
+export function moveWordLeft(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const currentHead = options.extend
+    ? selection.head
+    : Math.min(selection.anchor, selection.head);
+  const boundaries = wordBoundaries(text);
+  let prevBoundary = 0;
+  for (const pos of boundaries) {
+    if (pos >= currentHead) break;
+    prevBoundary = pos;
+  }
+  return finalize(selection, prevBoundary, options);
+}
+
+function finalize(
+  selection: CursorSelection,
+  head: number,
+  options: CursorMoveOptions,
+): CursorSelection {
+  if (options.extend) {
+    return { anchor: selection.anchor, head };
+  }
+  return { anchor: head, head };
+}
+
+function documentPlainText(doc: DocumentRootNode): string {
+  const story = parseTextStory(doc);
+  return createPlainText(story);
+}
+
+/**
+ * `Intl.Segmenter` is available in Node 16+ and all modern browsers. We lazy-
+ * init the default-locale instance; word segmentation is stateless, so one
+ * segmenter per process is fine.
+ */
+let cachedSegmenter: Intl.Segmenter | undefined;
+function wordSegmenter(): Intl.Segmenter {
+  if (!cachedSegmenter) {
+    cachedSegmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+  }
+  return cachedSegmenter;
+}
+
+/**
+ * Produce the sorted list of word-boundary positions in `text`. A boundary is
+ * the start of any segment whose `isWordLike` is true, plus the end-of-text.
+ * Whitespace and punctuation segments are skipped so caret jumps land on
+ * word endpoints rather than stopping at every space — matching Word's
+ * Ctrl+arrow behavior.
+ */
+function wordBoundaries(text: string): number[] {
+  const segments = wordSegmenter().segment(text);
+  const boundaries: number[] = [];
+  for (const segment of segments) {
+    if (segment.isWordLike) {
+      // Add both the start and the end of each word-like segment so
+      // Ctrl+Right from "hello|world" (between two words) advances to the end
+      // of "world" rather than stopping at the start.
+      boundaries.push(segment.index);
+      boundaries.push(segment.index + segment.segment.length);
+    }
+  }
+  // Dedup + sort so callers can binary-search or linear-walk deterministically.
+  boundaries.push(text.length);
+  return Array.from(new Set(boundaries)).sort((a, b) => a - b);
+}

package/src/runtime/selection/index.ts

@@ -0,0 +1,91 @@
+/**
+ * R.1 SelectionLayer — named module for cursor movement, validation, and
+ * anchor projection. See `docs/plans/lane-1-editing-foundation.md` §R.1.
+ *
+ * This file is the layer's single entry point. Callers consume
+ * `SelectionLayer.move(doc, sel, op)` / `SelectionLayer.validate(doc, sel)`
+ * rather than reaching into individual helpers. Phase 6a ships the six
+ * layout-independent primitives (char/word/paragraph × left/right). Phase 6b
+ * adds `moveUp` / `moveDown` / `moveLineStart` / `moveLineEnd` once Lane 3a
+ * P9's layout facet exposes per-run column info.
+ */
+
+import type { DocumentRootNode } from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope, SelectionSnapshot } from "../../core/state/editor-state.ts";
+import {
+  moveCharLeft,
+  moveCharRight,
+  moveParagraphEnd,
+  moveParagraphStart,
+  moveWordLeft,
+  moveWordRight,
+  type CursorMoveOptions,
+  type CursorSelection,
+} from "./cursor-ops.ts";
+import { validateSelectionAgainstDocument } from "./post-edit-validator.ts";
+
+export type {
+  CursorMoveOptions,
+  CursorSelection,
+} from "./cursor-ops.ts";
+
+/**
+ * Cursor-move operations supported by the layer. Phase 6b will extend this
+ * with `"up" | "down" | "line-start" | "line-end"`.
+ */
+export type CursorMoveOp =
+  | "char-left"
+  | "char-right"
+  | "word-left"
+  | "word-right"
+  | "paragraph-start"
+  | "paragraph-end";
+
+export interface SelectionLayer {
+  /**
+   * Apply a cursor-move operation and return the resulting selection. Pure;
+   * does not mutate any argument.
+   */
+  move(
+    doc: DocumentRootNode,
+    selection: CursorSelection,
+    op: CursorMoveOp,
+    options?: CursorMoveOptions,
+  ): CursorSelection;
+
+  /**
+   * Run the I5 post-edit selection validator. Snaps orphaned offsets into the
+   * nearest valid position. Pure; returns the (possibly adjusted) selection.
+   */
+  validate(
+    doc: CanonicalDocumentEnvelope,
+    selection: SelectionSnapshot,
+    maxOffset: number,
+  ): SelectionSnapshot;
+}
+
+/**
+ * Default SelectionLayer instance. Stateless — the same instance is safe to
+ * share across runtimes.
+ */
+export const selectionLayer: SelectionLayer = {
+  move(doc, selection, op, options) {
+    switch (op) {
+      case "char-left":
+        return moveCharLeft(doc, selection, options);
+      case "char-right":
+        return moveCharRight(doc, selection, options);
+      case "word-left":
+        return moveWordLeft(doc, selection, options);
+      case "word-right":
+        return moveWordRight(doc, selection, options);
+      case "paragraph-start":
+        return moveParagraphStart(doc, selection, options);
+      case "paragraph-end":
+        return moveParagraphEnd(doc, selection, options);
+    }
+  },
+  validate(doc, selection, maxOffset) {
+    return validateSelectionAgainstDocument(doc, selection, maxOffset);
+  },
+};

package/src/runtime/surface-projection.ts

@@ -52,6 +52,7 @@ import {
   resolveNumberingMarkerRunFormatting,
 } from "./paragraph-style-resolver.ts";
 import { resolveHyperlinkRunFormatting } from "./hyperlink-color-resolver.ts";
+import { concretizeThemeColors } from "./theme-color-resolver.ts";
 import type { CanonicalParagraphFormatting, CanonicalRunFormatting } from "../model/canonical-document.ts";
 
 interface ParagraphAccumulator {
@@ -874,6 +875,11 @@ function appendInlineSegments(
         characterStyleId: undefined,
         direct: directRunFormatting,
       };
+      // L2.c — non-hyperlink body text also gets theme-color concretization
+      // so paragraph styles declaring `<w:color w:themeColor="accent1"/>`
+      // render with their theme slot's hex instead of falling back to
+      // default black. Hyperlink branch already resolves theme via the
+      // Hyperlink-style cascade; only the non-hyperlink path was missing.
       const resolvedRunFormatting = cullBuild
         ? {}
         : hyperlinkHref
@@ -882,7 +888,10 @@ function appendInlineSegments(
               document.styles,
               document.subParts?.resolvedTheme,
             )
-          : resolveEffectiveRunFormatting(runResolveInput, document.styles);
+          : concretizeThemeColors(
+              resolveEffectiveRunFormatting(runResolveInput, document.styles),
+              document.subParts?.resolvedTheme,
+            );
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
         kind: "text",

package/src/runtime/theme-color-resolver.ts

@@ -57,6 +57,52 @@ export function resolveThemeColorHex(
   return applyThemeTintShade(baseHex, rPr.colorThemeTint, rPr.colorThemeShade);
 }
 
+/**
+ * Post-process a cascade of run formatting to concretize any
+ * theme-color-only reference into a paintable `colorHex`.
+ *
+ * L2.c body-text call site: `surface-projection.ts` runs the standard
+ * `resolveEffectiveRunFormatting` cascade, then pipes the result through
+ * this function with the document's resolved theme. Runs that declared
+ * `<w:color w:themeColor="accent1"/>` without a concrete `w:val` end up
+ * with `colorHex` set to the theme-resolved hex so downstream
+ * `pm-state-from-snapshot` can paint them.
+ *
+ * The theme-slot fields (`colorThemeSlot` / `Tint` / `Shade`) stay on
+ * the cascade so that the export path can re-emit the original theme
+ * reference — this function never overwrites them, it only adds
+ * `colorHex` when it was absent or `"auto"`.
+ *
+ * No-ops when:
+ *   - no theme-slot is declared (nothing to resolve),
+ *   - `colorHex` is already a concrete non-`"auto"` hex (direct wins),
+ *   - theme is missing or the slot is unknown (graceful fallback),
+ *   - resolver returns `undefined` (e.g. malformed tint/shade).
+ */
+export function concretizeThemeColors(
+  cascade: CanonicalRunFormatting,
+  theme: ResolvedTheme | undefined,
+): CanonicalRunFormatting {
+  if (!cascade.colorThemeSlot) return cascade;
+  if (cascade.colorHex && cascade.colorHex !== "auto") return cascade;
+  // When colorHex is "auto" we intentionally bypass it during theme
+  // resolution: Word's cascade treats `<w:color w:val="auto"
+  // w:themeColor="accent1"/>` as "paint with the theme slot; auto is
+  // the fallback if theme is missing." Pass a stripped input to the
+  // resolver so `colorHex === "auto"` doesn't short-circuit.
+  const resolved = resolveThemeColorHex(
+    {
+      colorThemeSlot: cascade.colorThemeSlot,
+      colorThemeTint: cascade.colorThemeTint,
+      colorThemeShade: cascade.colorThemeShade,
+    },
+    theme,
+  );
+  if (!resolved || resolved === "auto") return cascade;
+  if (resolved === cascade.colorHex) return cascade;
+  return { ...cascade, colorHex: resolved };
+}
+
 /**
  * Apply `w:themeTint` (shift toward white) and/or `w:themeShade` (shift
  * toward black) to a base hex colour. Pure function.