@beyondwork/docx-react-component 1.0.42 → 1.0.45

package/src/io/export/build-app-properties-xml.ts

@@ -7,7 +7,7 @@
  * content type.
  *
  * Required by:
- *   docs/plans/close-render-fidelity.md §2 A.5
+ *   docs/plans/lane-3-layout-engine-ooxml-fidelity.md §2 A.5
  *
  * Schema shape (ECMA-376 Part 1, Office Extended properties):
  *   <Properties xmlns="…/extended-properties" xmlns:vt="…/docPropsVTypes">

package/src/io/export/serialize-comments.ts

@@ -267,19 +267,16 @@ export function serializeCommentAnchorsIntoDocumentXml(
       continue;
     }
 
-    const paragraph = paragraphs.find(
-      (candidate) =>
-        anchor.range.from >= candidate.start &&
-        anchor.range.to <= candidate.end,
-    );
+    const startParagraph = findParagraphForEndpoint(paragraphs, anchor.range.from, "start");
+    const endParagraph = findParagraphForEndpoint(paragraphs, anchor.range.to, "end");
 
-    if (!paragraph) {
+    if (!startParagraph || !endParagraph) {
       skippedCommentIds.push(thread.commentId);
       continue;
     }
 
-    const startIndex = paragraph.boundaries.get(anchor.range.from);
-    const endIndex = paragraph.boundaries.get(anchor.range.to);
+    const startIndex = startParagraph.boundaries.get(anchor.range.from);
+    const endIndex = endParagraph.boundaries.get(anchor.range.to);
 
     if (startIndex === undefined || endIndex === undefined) {
       skippedCommentIds.push(thread.commentId);
@@ -324,6 +321,25 @@ export function serializeCommentAnchorsIntoDocumentXml(
   };
 }
 
+function findParagraphForEndpoint(
+  paragraphs: readonly Pick<
+    RevisionParagraphBoundary,
+    "paragraphIndex" | "start" | "end" | "boundaries"
+  >[],
+  offset: number,
+  kind: "start" | "end",
+): Pick<RevisionParagraphBoundary, "paragraphIndex" | "start" | "end" | "boundaries"> | undefined {
+  const matches = paragraphs.filter(
+    (p) => offset >= p.start && offset <= p.end,
+  );
+  if (matches.length === 0) return undefined;
+  if (matches.length === 1) return matches[0];
+  if (kind === "start") {
+    return matches.reduce((a, b) => (b.start >= a.start ? b : a));
+  }
+  return matches.reduce((a, b) => (b.end <= a.end ? b : a));
+}
+
 export function createCommentExportIdMap(
   threads: readonly CommentThread[],
   preservedDefinitions: readonly ImportedCommentDefinition[] = [],
@@ -729,6 +745,8 @@ function walkInlineNodeForBoundaries(
   }
 
   switch (localName(node.name)) {
+    case "pPr":
+      return;
     case "r": {
       if (!boundaries.has(getCursor())) {
         boundaries.set(getCursor(), node.start);
@@ -750,7 +768,18 @@ function walkInlineNodeForBoundaries(
       return;
     }
     case "tab":
-    case "br": {
+    case "br":
+    case "footnoteReference":
+    case "endnoteReference":
+    case "drawing":
+    case "pict":
+    case "object":
+    case "sym":
+    case "ptab":
+    case "separator":
+    case "continuationSeparator":
+    case "noBreakHyphen":
+    case "softHyphen": {
       const startCursor = getCursor();
       boundaries.set(startCursor, node.start);
       const nextCursor = startCursor + 1;

package/src/io/export/twip.ts

@@ -18,7 +18,7 @@
  *   requireTwip(value)  — mandatory numeric: throws on non-finite input.
  *
  * Source:
- *   docs/plans/close-render-fidelity.md §2 A.2
+ *   docs/plans/lane-3-layout-engine-ooxml-fidelity.md §2 A.2
  */
 
 /**

package/src/io/load-scheduler.ts

@@ -0,0 +1,230 @@
+/**
+ * Load scheduler — main-thread time-slicing primitive for the staged
+ * document-load pipeline.
+ *
+ * The loader calls `scheduler.yield()` between parse stages so the browser
+ * can paint, service input, and run React commits. `scheduleIdle(task)`
+ * queues low-priority work (e.g., sub-part hydration, compatibility report)
+ * for post-skeleton execution.
+ *
+ * Backend cascade (first available wins):
+ *   1. `globalThis.scheduler.yield()` — native browser API (Chrome 129+, Edge).
+ *   2. `MessageChannel.postMessage` — universal DOM fallback, ~0.1ms per yield.
+ *   3. `setTimeout(0)` — last-resort fallback.
+ *   4. `sync` — SSR / Node test harness. `yield()` resolves immediately;
+ *      `scheduleIdle` runs inline.
+ *
+ * The `sync` backend is selected when `typeof document === "undefined"` so
+ * existing Node-side tests drive the staged pipeline with byte-identical
+ * behavior to the eager pipeline (no real yielding, no idle deferral).
+ */
+
+export type LoadSchedulerBackend =
+  | "scheduler-api"
+  | "message-channel"
+  | "timeout"
+  | "sync";
+
+export interface LoadScheduler {
+  readonly backend: LoadSchedulerBackend;
+  /** Yield to the browser. Resolves on next scheduled task / microtask. */
+  yield(): Promise<void>;
+  /** Schedule low-priority work for post-skeleton execution. */
+  scheduleIdle(task: () => void): void;
+  /** Cancel pending idle tasks. Must be called on unmount / dispose. */
+  dispose(): void;
+}
+
+export interface CreateLoadSchedulerOptions {
+  /** Frame deadline in ms. Default 4ms (keeps browser at 60fps). */
+  frameDeadlineMs?: number;
+  /**
+   * Force a specific backend (test-only). When omitted, the scheduler
+   * detects the best available backend at construction time.
+   */
+  backendOverride?: LoadSchedulerBackend;
+}
+
+const DEFAULT_FRAME_DEADLINE_MS = 4;
+
+/**
+ * Returns true when the elapsed time since `lastYieldAt` exceeds the
+ * scheduler's frame deadline. Callers use this inside tight loops to decide
+ * when to `await scheduler.yield()`.
+ */
+export function shouldYield(
+  scheduler: LoadScheduler & { readonly frameDeadlineMs?: number },
+  lastYieldAt: number,
+): boolean {
+  const now = typeof performance !== "undefined" ? performance.now() : Date.now();
+  const deadline = scheduler.frameDeadlineMs ?? DEFAULT_FRAME_DEADLINE_MS;
+  return now - lastYieldAt >= deadline;
+}
+
+/**
+ * Returns a monotonic timestamp suitable for `shouldYield` comparisons.
+ */
+export function nowMs(): number {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+
+interface InternalScheduler extends LoadScheduler {
+  readonly frameDeadlineMs: number;
+}
+
+export function createLoadScheduler(
+  options: CreateLoadSchedulerOptions = {},
+): LoadScheduler {
+  const frameDeadlineMs = options.frameDeadlineMs ?? DEFAULT_FRAME_DEADLINE_MS;
+  const backend = options.backendOverride ?? detectBackend();
+
+  switch (backend) {
+    case "scheduler-api":
+      return createSchedulerApiBackend(frameDeadlineMs);
+    case "message-channel":
+      return createMessageChannelBackend(frameDeadlineMs);
+    case "timeout":
+      return createTimeoutBackend(frameDeadlineMs);
+    case "sync":
+      return createSyncBackend(frameDeadlineMs);
+  }
+}
+
+function detectBackend(): LoadSchedulerBackend {
+  if (typeof document === "undefined") {
+    return "sync";
+  }
+  const g = globalThis as unknown as {
+    scheduler?: { yield?: () => Promise<void> };
+  };
+  if (typeof g.scheduler?.yield === "function") {
+    return "scheduler-api";
+  }
+  if (typeof MessageChannel !== "undefined") {
+    return "message-channel";
+  }
+  return "timeout";
+}
+
+function createSchedulerApiBackend(frameDeadlineMs: number): InternalScheduler {
+  const g = globalThis as unknown as {
+    scheduler: { yield: () => Promise<void> };
+  };
+  const pendingIdleHandles = new Set<number>();
+  return {
+    backend: "scheduler-api",
+    frameDeadlineMs,
+    yield: () => g.scheduler.yield(),
+    scheduleIdle(task) {
+      const handle = scheduleIdleCallback(task, pendingIdleHandles);
+      pendingIdleHandles.add(handle);
+    },
+    dispose() {
+      disposeIdleHandles(pendingIdleHandles);
+    },
+  };
+}
+
+function createMessageChannelBackend(frameDeadlineMs: number): InternalScheduler {
+  const pendingIdleHandles = new Set<number>();
+  return {
+    backend: "message-channel",
+    frameDeadlineMs,
+    yield() {
+      return new Promise<void>((resolve) => {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => {
+          channel.port1.close();
+          channel.port2.close();
+          resolve();
+        };
+        channel.port2.postMessage(null);
+      });
+    },
+    scheduleIdle(task) {
+      const handle = scheduleIdleCallback(task, pendingIdleHandles);
+      pendingIdleHandles.add(handle);
+    },
+    dispose() {
+      disposeIdleHandles(pendingIdleHandles);
+    },
+  };
+}
+
+function createTimeoutBackend(frameDeadlineMs: number): InternalScheduler {
+  const pendingIdleHandles = new Set<number>();
+  return {
+    backend: "timeout",
+    frameDeadlineMs,
+    yield() {
+      return new Promise<void>((resolve) => {
+        setTimeout(resolve, 0);
+      });
+    },
+    scheduleIdle(task) {
+      const handle = setTimeout(task, 0) as unknown as number;
+      pendingIdleHandles.add(handle);
+    },
+    dispose() {
+      for (const handle of pendingIdleHandles) {
+        clearTimeout(handle as unknown as ReturnType<typeof setTimeout>);
+      }
+      pendingIdleHandles.clear();
+    },
+  };
+}
+
+function createSyncBackend(frameDeadlineMs: number): InternalScheduler {
+  return {
+    backend: "sync",
+    frameDeadlineMs,
+    yield: () => Promise.resolve(),
+    scheduleIdle(task) {
+      task();
+    },
+    dispose() {
+      /* no-op */
+    },
+  };
+}
+
+type IdleHandle = number;
+
+function scheduleIdleCallback(
+  task: () => void,
+  store: Set<IdleHandle>,
+): IdleHandle {
+  const g = globalThis as unknown as {
+    requestIdleCallback?: (cb: () => void, options?: { timeout: number }) => number;
+    cancelIdleCallback?: (handle: number) => void;
+  };
+  if (typeof g.requestIdleCallback === "function") {
+    const handle = g.requestIdleCallback(
+      () => {
+        store.delete(handle);
+        task();
+      },
+      { timeout: 50 },
+    );
+    return handle;
+  }
+  const handle = setTimeout(() => {
+    store.delete(handle as unknown as number);
+    task();
+  }, 0) as unknown as number;
+  return handle;
+}
+
+function disposeIdleHandles(store: Set<IdleHandle>): void {
+  const g = globalThis as unknown as {
+    cancelIdleCallback?: (handle: number) => void;
+  };
+  for (const handle of store) {
+    if (typeof g.cancelIdleCallback === "function") {
+      g.cancelIdleCallback(handle);
+    } else {
+      clearTimeout(handle as unknown as ReturnType<typeof setTimeout>);
+    }
+  }
+  store.clear();
+}

package/src/io/normalize/normalize-text.ts

@@ -23,6 +23,7 @@ import type {
 import type {
   ParsedAltChunkNode,
   ParsedBlockNode,
+  ParsedChartPreviewNode,
   ParsedCustomXmlNode,
   ParsedHyperlinkNode,
   ParsedInlineNode,
@@ -31,11 +32,17 @@ import type {
   ParsedParagraphNode,
   ParsedSectionBreakNode,
   ParsedSdtNode,
+  ParsedSmartArtPreviewNode,
   ParsedTableBlockNode,
   ParsedTableCellNode,
   ParsedTableRowNode,
 } from "../ooxml/parse-main-document.ts";
 import { classifyFieldInstruction, buildFieldRegistry } from "../ooxml/parse-fields.ts";
+import {
+  type LoadScheduler,
+  nowMs,
+  shouldYield,
+} from "../load-scheduler.ts";
 
 export interface NormalizedTextDocument {
   content: DocumentRootNode;
@@ -115,6 +122,84 @@ export function normalizeParsedTextDocument(
   };
 }
 
+/**
+ * Fastload P6: async sibling of `normalizeParsedTextDocument` that yields to
+ * the browser every {@link NORMALIZE_YIELD_STRIDE} top-level blocks when
+ * {@link shouldYield} fires against the scheduler's frame deadline. Shares
+ * the private normalizeBlocks / normalizeParagraph / normalizeInlineChildren
+ * helpers with the sync export — only the outermost block walk is duplicated.
+ *
+ * Byte-equivalent to the sync export on any corpus (fixture parity is asserted
+ * in `test/io/normalize-text-async.test.ts` across every F*.docx fixture).
+ */
+const NORMALIZE_YIELD_STRIDE = 256;
+
+export async function normalizeParsedTextDocumentAsync(
+  document: ParsedMainDocument,
+  packagePartName = "/word/document.xml",
+  scheduler: LoadScheduler,
+  options?: { styles?: import("../../model/canonical-document.ts").StylesCatalog },
+): Promise<NormalizedTextDocument> {
+  const state: NormalizationState = {
+    nextFragmentIndex: 1,
+    nextWarningIndex: 1,
+    nextDiagnosticIndex: 1,
+    cursor: 0,
+    media: {
+      items: {},
+    },
+    preservation: {
+      opaqueFragments: {},
+      packageParts: {},
+    },
+    diagnostics: {
+      warnings: [],
+      errors: [],
+    },
+  };
+
+  const children: BlockNode[] = [];
+  let previousParagraph = false;
+  let lastYieldAt = nowMs();
+
+  for (let i = 0; i < document.blocks.length; i += 1) {
+    const block = document.blocks[i];
+    const normalizedBlocks = normalizeBlocks(block, state, packagePartName);
+    for (const normalizedBlock of normalizedBlocks) {
+      if (previousParagraph && normalizedBlock.type === "paragraph") {
+        state.cursor += 1;
+      }
+      children.push(normalizedBlock);
+      previousParagraph = normalizedBlock.type === "paragraph";
+    }
+    if (
+      i > 0 &&
+      i % NORMALIZE_YIELD_STRIDE === 0 &&
+      shouldYield(scheduler, lastYieldAt)
+    ) {
+      await scheduler.yield();
+      lastYieldAt = nowMs();
+    }
+  }
+
+  const content: DocumentRootNode = { type: "doc", children };
+
+  const styles = options?.styles ?? { paragraphs: {}, characters: {}, tables: {} };
+  const fieldRegistry = buildFieldRegistry({ content, styles });
+  const hasFields = fieldRegistry.supported.length > 0 || fieldRegistry.preserveOnly.length > 0;
+
+  return {
+    content,
+    media: state.media,
+    preservation: state.preservation,
+    diagnostics: state.diagnostics,
+    ...(document.finalSectionProperties !== undefined
+      ? { finalSectionProperties: document.finalSectionProperties }
+      : {}),
+    ...(hasFields ? { fieldRegistry } : {}),
+  };
+}
+
 function normalizeBlocks(
   block: ParsedBlockNode,
   state: NormalizationState,
@@ -393,6 +478,7 @@ function normalizeInlineChildren(
         state.cursor += 1;
         break;
       case "chart_preview":
+        registerComplexPreviewMedia(state, node);
         normalized.push({
           type: "chart_preview",
           ...(node.previewMediaId ? { previewMediaId: node.previewMediaId } : {}),
@@ -401,6 +487,7 @@ function normalizeInlineChildren(
         state.cursor += 1;
         break;
       case "smartart_preview":
+        registerComplexPreviewMedia(state, node);
         normalized.push({
           type: "smartart_preview",
           ...(node.previewMediaId ? { previewMediaId: node.previewMediaId } : {}),
@@ -528,6 +615,35 @@ function normalizeImageNode(
   };
 }
 
+/**
+ * Register a chart/SmartArt preview bitmap in the media catalog so the
+ * surface renderer can resolve `previewMediaId` → `previewSrc` the same
+ * way it does for inline images. Chart/SmartArt nodes weren't previously
+ * registered because only image nodes walked through `normalizeImageNode`.
+ * Needed by docs/plans/lane-5-charts.md Stage 0 (real mc:Fallback bitmaps) and
+ * Stage 0B (synthesized previews from the demo harness decorator) —
+ * without this, previewMediaId sits in the canonical model but
+ * `canonicalDocument.media.items` has no corresponding MediaItem and
+ * the editor's mediaPreview resolver skips the bitmap.
+ */
+function registerComplexPreviewMedia(
+  state: NormalizationState,
+  node: ParsedChartPreviewNode | ParsedSmartArtPreviewNode,
+): void {
+  if (!node.previewMediaId) return;
+  if (state.media.items[node.previewMediaId]) return; // already registered (e.g. via another reference)
+  const packagePartName =
+    node.previewPackagePartName ?? `/${node.previewMediaId.slice("media:".length)}`;
+  const filename =
+    packagePartName.slice(packagePartName.lastIndexOf("/") + 1) || "chart-preview.bin";
+  state.media.items[node.previewMediaId] = {
+    mediaId: node.previewMediaId,
+    contentType: node.previewContentType ?? "application/octet-stream",
+    filename,
+    packagePartName,
+  };
+}
+
 function normalizeHyperlink(node: ParsedHyperlinkNode): {
   type: "hyperlink";
   href: string;

package/src/io/ooxml/parse-comments.ts

@@ -173,39 +173,6 @@ export function parseCommentsFromOoxml(
       continue;
     }
 
-    if (startParagraphIndex !== endParagraphIndex) {
-      diagnostics.push({
-        commentId: rootCommentId,
-        code: "multi_paragraph_anchor_preserve_only",
-        message:
-          "Comment anchor spans multiple paragraphs. Thread is visible but detached; cross-paragraph anchoring is not yet supported for live editing.",
-        featureClass: "preserve-only",
-        detachedReason: "multi-paragraph",
-        actionabilityNote: "The comment thread and body are preserved. Operators see the thread in the sidebar but cannot navigate to an inline highlight.",
-      });
-      threads.push(
-        createImportedCommentThread({
-          commentId: rootCommentId,
-          body: rootDefinition.body,
-          createdBy,
-          createdAt,
-          range: detachedRange,
-          entries,
-          status: "detached",
-          resolution,
-          metadata: {
-            source: "import",
-            rootOoxmlCommentId: rootDefinition.commentId,
-            rootParaId: rootDefinition.paraId,
-            detachedReason: "multi-paragraph",
-            actionabilityNote:
-              "The comment thread and body are preserved. Operators see the thread in the sidebar but cannot navigate to an inline highlight.",
-          },
-        }),
-      );
-      continue;
-    }
-
     threads.push(
       createImportedCommentThread({
         commentId: rootCommentId,

package/src/io/ooxml/parse-complex-content.ts

@@ -21,6 +21,10 @@ export interface ParsedChartContent {
   type: "chart_preview";
   /** Media ID of the fallback preview image, if one is present in mc:Fallback. */
   previewMediaId?: string;
+  /** Absolute package path of the preview media (e.g. `/word/media/chartN.png`); required by the media catalog when the preview media needs an entry. */
+  previewPackagePartName?: string;
+  /** MIME type of the preview media (e.g. `image/png`, `image/svg+xml`). */
+  previewContentType?: string;
   /** Original drawing XML slice for lossless round-trip export. */
   rawXml: string;
 }
@@ -29,6 +33,10 @@ export interface ParsedSmartArtContent {
   type: "smartart_preview";
   /** Media ID of the fallback preview image, if one is present in mc:Fallback. */
   previewMediaId?: string;
+  /** Absolute package path of the preview media. */
+  previewPackagePartName?: string;
+  /** MIME type of the preview media. */
+  previewContentType?: string;
   /** Original drawing XML slice for lossless round-trip export. */
   rawXml: string;
 }
@@ -116,6 +124,8 @@ function parseAlternateContent(
 
   // Extract fallback preview image if present
   let previewMediaId: string | undefined;
+  let previewPackagePartName: string | undefined;
+  let previewContentType: string | undefined;
   if (fallback) {
     const fallbackBlip = findFirstDescendant(fallback, "blip");
     if (fallbackBlip) {
@@ -132,6 +142,8 @@ function parseAlternateContent(
           const mediaPart = mediaParts.get(packagePartName);
           if (mediaPart) {
             previewMediaId = `media:${packagePartName.slice(1)}`;
+            previewPackagePartName = packagePartName;
+            previewContentType = mediaPart.contentType;
           }
         }
       }
@@ -141,6 +153,8 @@ function parseAlternateContent(
   return {
     type: contentType,
     ...(previewMediaId ? { previewMediaId } : {}),
+    ...(previewPackagePartName ? { previewPackagePartName } : {}),
+    ...(previewContentType ? { previewContentType } : {}),
     rawXml: fullDrawingXml,
   };
 }

package/src/io/ooxml/parse-main-document.ts

@@ -211,12 +211,16 @@ export interface ParsedOpaqueInlineNode {
 export interface ParsedChartPreviewNode {
   type: "chart_preview";
   previewMediaId?: string;
+  previewPackagePartName?: string;
+  previewContentType?: string;
   rawXml: string;
 }
 
 export interface ParsedSmartArtPreviewNode {
   type: "smartart_preview";
   previewMediaId?: string;
+  previewPackagePartName?: string;
+  previewContentType?: string;
   rawXml: string;
 }