@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/io/export/table-properties-xml.ts

@@ -1,4 +1,5 @@
 import { twip } from "./twip.ts";
+import { escapeXmlAttribute } from "./escape-xml-attribute.ts";
 
 interface TableWidthLike {
   value: number;
@@ -233,31 +234,31 @@ function stripKnownProperties(xml: string, stripSpec: PropertyStripSpec): string
 function buildTablePropertiesInnerXml(table: TablePropertiesLike): string {
   const children: string[] = [];
   if (table.styleId) {
-    children.push(`<w:tblStyle w:val="${escapeAttribute(table.styleId)}"/>`);
+    children.push(`<w:tblStyle w:val="${escapeXmlAttribute(table.styleId)}"/>`);
   }
   if (table.width) {
     children.push(serializeWidth("tblW", table.width));
   }
   if (table.alignment) {
-    children.push(`<w:jc w:val="${escapeAttribute(table.alignment)}"/>`);
+    children.push(`<w:jc w:val="${escapeXmlAttribute(table.alignment)}"/>`);
   }
   if (table.indent) {
-    children.push(`<w:tblInd w:w="${table.indent.value}" w:type="${escapeAttribute(table.indent.type)}"/>`);
+    children.push(`<w:tblInd w:w="${table.indent.value}" w:type="${escapeXmlAttribute(table.indent.type)}"/>`);
   }
   if (table.layoutMode) {
-    children.push(`<w:tblLayout w:type="${escapeAttribute(table.layoutMode)}"/>`);
+    children.push(`<w:tblLayout w:type="${escapeXmlAttribute(table.layoutMode)}"/>`);
   }
   if (table.cellSpacing) {
-    children.push(`<w:tblCellSpacing w:w="${table.cellSpacing.value}" w:type="${escapeAttribute(table.cellSpacing.type)}"/>`);
+    children.push(`<w:tblCellSpacing w:w="${table.cellSpacing.value}" w:type="${escapeXmlAttribute(table.cellSpacing.type)}"/>`);
   }
   if (table.bidiVisual !== undefined) {
     children.push(table.bidiVisual ? `<w:bidiVisual/>` : `<w:bidiVisual w:val="0"/>`);
   }
   if (table.caption !== undefined) {
-    children.push(`<w:tblCaption w:val="${escapeAttribute(table.caption)}"/>`);
+    children.push(`<w:tblCaption w:val="${escapeXmlAttribute(table.caption)}"/>`);
   }
   if (table.description !== undefined) {
-    children.push(`<w:tblDescription w:val="${escapeAttribute(table.description)}"/>`);
+    children.push(`<w:tblDescription w:val="${escapeXmlAttribute(table.description)}"/>`);
   }
   if (table.floating) {
     const floatingXml = serializeTableFloating(table.floating);
@@ -286,11 +287,11 @@ function buildTablePropertiesInnerXml(table: TablePropertiesLike): string {
 
 function serializeTableFloating(floating: TableFloatingPropertiesLike): string {
   const attrs: string[] = [];
-  if (floating.horizontalAnchor) attrs.push(`w:horzAnchor="${escapeAttribute(floating.horizontalAnchor)}"`);
-  if (floating.verticalAnchor) attrs.push(`w:vertAnchor="${escapeAttribute(floating.verticalAnchor)}"`);
-  if (floating.horizontalAlign) attrs.push(`w:tblpXSpec="${escapeAttribute(floating.horizontalAlign)}"`);
+  if (floating.horizontalAnchor) attrs.push(`w:horzAnchor="${escapeXmlAttribute(floating.horizontalAnchor)}"`);
+  if (floating.verticalAnchor) attrs.push(`w:vertAnchor="${escapeXmlAttribute(floating.verticalAnchor)}"`);
+  if (floating.horizontalAlign) attrs.push(`w:tblpXSpec="${escapeXmlAttribute(floating.horizontalAlign)}"`);
   if (floating.horizontalOffset !== undefined) attrs.push(`w:tblpX="${floating.horizontalOffset}"`);
-  if (floating.verticalAlign) attrs.push(`w:tblpYSpec="${escapeAttribute(floating.verticalAlign)}"`);
+  if (floating.verticalAlign) attrs.push(`w:tblpYSpec="${escapeXmlAttribute(floating.verticalAlign)}"`);
   if (floating.verticalOffset !== undefined) attrs.push(`w:tblpY="${floating.verticalOffset}"`);
   if (floating.leftFromText !== undefined) attrs.push(`w:leftFromText="${floating.leftFromText}"`);
   if (floating.rightFromText !== undefined) attrs.push(`w:rightFromText="${floating.rightFromText}"`);
@@ -306,7 +307,7 @@ function serializeTableFloating(floating: TableFloatingPropertiesLike): string {
 function buildTableRowPropertiesInnerXml(row: TableRowPropertiesLike): string {
   const children: string[] = [];
   if (row.cnfStyle) {
-    children.push(`<w:cnfStyle w:val="${escapeAttribute(row.cnfStyle)}"/>`);
+    children.push(`<w:cnfStyle w:val="${escapeXmlAttribute(row.cnfStyle)}"/>`);
   }
   if (row.gridBefore !== undefined) {
     children.push(`<w:gridBefore w:val="${twip(row.gridBefore)}"/>`);
@@ -328,7 +329,7 @@ function buildTableRowPropertiesInnerXml(row: TableRowPropertiesLike): string {
     children.push(row.cantSplit ? `<w:cantSplit/>` : `<w:cantSplit w:val="0"/>`);
   }
   if (row.height !== undefined) {
-    const hRuleAttr = row.heightRule ? ` w:hRule="${escapeAttribute(row.heightRule)}"` : "";
+    const hRuleAttr = row.heightRule ? ` w:hRule="${escapeXmlAttribute(row.heightRule)}"` : "";
     children.push(`<w:trHeight w:val="${twip(row.height)}"${hRuleAttr}/>`);
   }
   // ST_OnOff element (A.3):
@@ -343,7 +344,7 @@ function buildTableRowPropertiesInnerXml(row: TableRowPropertiesLike): string {
     children.push(`<w:tblHeader w:val="false"/>`);
   }
   if (row.horizontalAlignment) {
-    children.push(`<w:jc w:val="${escapeAttribute(row.horizontalAlignment)}"/>`);
+    children.push(`<w:jc w:val="${escapeXmlAttribute(row.horizontalAlignment)}"/>`);
   }
   return children.join("");
 }
@@ -351,7 +352,7 @@ function buildTableRowPropertiesInnerXml(row: TableRowPropertiesLike): string {
 function buildTableCellPropertiesInnerXml(cell: TableCellPropertiesLike): string {
   const children: string[] = [];
   if (cell.cnfStyle) {
-    children.push(`<w:cnfStyle w:val="${escapeAttribute(cell.cnfStyle)}"/>`);
+    children.push(`<w:cnfStyle w:val="${escapeXmlAttribute(cell.cnfStyle)}"/>`);
   }
   if (cell.width) {
     children.push(serializeWidth("tcW", cell.width));
@@ -391,10 +392,10 @@ function buildTableCellPropertiesInnerXml(cell: TableCellPropertiesLike): string
     children.push(cell.fitText ? `<w:tcFitText/>` : `<w:tcFitText w:val="0"/>`);
   }
   if (cell.textDirection) {
-    children.push(`<w:textDirection w:val="${escapeAttribute(cell.textDirection)}"/>`);
+    children.push(`<w:textDirection w:val="${escapeXmlAttribute(cell.textDirection)}"/>`);
   }
   if (cell.verticalAlign) {
-    children.push(`<w:vAlign w:val="${escapeAttribute(cell.verticalAlign)}"/>`);
+    children.push(`<w:vAlign w:val="${escapeXmlAttribute(cell.verticalAlign)}"/>`);
   }
   return children.join("");
 }
@@ -402,7 +403,7 @@ function buildTableCellPropertiesInnerXml(cell: TableCellPropertiesLike): string
 function serializeWidth(elementName: "tblW" | "tcW", width: TableWidthLike): string {
   // OOXML allows w:w to be percentage (pct) or twentieths-of-a-percent too, but
   // both are integer-typed in the schema. Always round at the authoring edge.
-  return `<w:${elementName} w:w="${twip(width.value)}" w:type="${escapeAttribute(width.type)}"/>`;
+  return `<w:${elementName} w:w="${twip(width.value)}" w:type="${escapeXmlAttribute(width.type)}"/>`;
 }
 
 function serializeBorders(borders: TableBordersLike): string {
@@ -415,10 +416,10 @@ function serializeBorders(borders: TableBordersLike): string {
 
 function serializeBorderSpec(elementName: string, border: BorderSpecLike): string {
   const attrs: string[] = [];
-  if (border.value) attrs.push(`w:val="${escapeAttribute(border.value)}"`);
+  if (border.value) attrs.push(`w:val="${escapeXmlAttribute(border.value)}"`);
   if (border.size !== undefined) attrs.push(`w:sz="${twip(border.size)}"`);
   if (border.space !== undefined) attrs.push(`w:space="${twip(border.space)}"`);
-  if (border.color) attrs.push(`w:color="${escapeAttribute(border.color)}"`);
+  if (border.color) attrs.push(`w:color="${escapeXmlAttribute(border.color)}"`);
   return attrs.length > 0 ? `<w:${elementName} ${attrs.join(" ")}/>` : "";
 }
 
@@ -434,7 +435,7 @@ function serializeTableCellMargins(margins: TableCellMarginsLike): string {
 function serializeTableLook(tblLook: TableLookLike): string {
   const attrs: string[] = [];
   if (tblLook.val) {
-    attrs.push(`w:val="${escapeAttribute(tblLook.val)}"`);
+    attrs.push(`w:val="${escapeXmlAttribute(tblLook.val)}"`);
   }
   for (const [key, attr] of [
     ["firstRow", "w:firstRow"],
@@ -457,16 +458,8 @@ function serializeTableLook(tblLook: TableLookLike): string {
 
 function serializeCellShading(shading: CellShadingLike): string {
   const attrs: string[] = [];
-  if (shading.val) attrs.push(`w:val="${escapeAttribute(shading.val)}"`);
-  if (shading.color) attrs.push(`w:color="${escapeAttribute(shading.color)}"`);
-  if (shading.fill) attrs.push(`w:fill="${escapeAttribute(shading.fill)}"`);
+  if (shading.val) attrs.push(`w:val="${escapeXmlAttribute(shading.val)}"`);
+  if (shading.color) attrs.push(`w:color="${escapeXmlAttribute(shading.color)}"`);
+  if (shading.fill) attrs.push(`w:fill="${escapeXmlAttribute(shading.fill)}"`);
   return attrs.length > 0 ? `<w:shd ${attrs.join(" ")}/>` : "";
 }
-
-function escapeAttribute(value: string): string {
-  return value
-    .replace(/&/gu, "&amp;")
-    .replace(/"/gu, "&quot;")
-    .replace(/</gu, "&lt;")
-    .replace(/>/gu, "&gt;");
-}

package/src/io/import/external-reimport.ts

@@ -0,0 +1,40 @@
+import type {
+  ExternalCustody,
+  ExternalCustodyResolver,
+  ExternalCustodyRestoredContent,
+} from "../../api/external-custody-types.ts";
+
+export type ReimportResult =
+  | { outcome: "skipped" /* no custody attached */ }
+  | { outcome: "resolver_missing" /* custody present, no host resolver */ }
+  | { outcome: "tampered" /* incoming doc body hash ≠ originContentHash */ }
+  | { outcome: "deferred" /* resolver returned undefined; keep custody for retry */ }
+  | { outcome: "restored"; content: ExternalCustodyRestoredContent };
+
+export interface MaybeRestoreArgs {
+  custody: ExternalCustody | undefined;
+  resolver: ExternalCustodyResolver | undefined;
+  /** sha256:{hex} of canonicalized word/document.xml of the incoming docx. */
+  incomingDocxHash: string;
+}
+
+/**
+ * Re-import pipeline. Classifies the call into a closed outcome set so
+ * the caller can decide how to merge the restored content back into
+ * the runtime state.
+ */
+export async function maybeRestoreFromExternalCustody(
+  args: MaybeRestoreArgs,
+): Promise<ReimportResult> {
+  if (!args.custody) return { outcome: "skipped" };
+  if (!args.resolver) return { outcome: "resolver_missing" };
+  if (args.custody.originContentHash !== args.incomingDocxHash) {
+    return { outcome: "tampered" };
+  }
+  const restored = await args.resolver.restore({
+    custodyId: args.custody.custodyId,
+    originContentHash: args.custody.originContentHash,
+  });
+  if (!restored) return { outcome: "deferred" };
+  return { outcome: "restored", content: restored };
+}

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

@@ -36,6 +36,11 @@ import type {
   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 +120,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,