@beyondwork/docx-react-component 1.0.48 → 1.0.50

package/src/core/state/text-transaction.ts

@@ -13,7 +13,8 @@ import {
   type TextStory,
 } from "../schema/text-schema.ts";
 import { createEditorSurfaceSnapshot } from "../../runtime/surface-projection.ts";
-import type { DocumentRootNode, ParagraphNode, SdtNode, TableNode } from "../../model/canonical-document.ts";
+import type { DocumentRootNode, ParagraphNode, SdtNode, TableNode, TextMark } from "../../model/canonical-document.ts";
+import type { TextFormattingDirective } from "../../api/public-types.ts";
 
 export type TextInsertion =
   | {
@@ -38,6 +39,13 @@ export type TextTransactionIntent =
         to: number;
       };
       insertion: TextInsertion[];
+      /**
+       * I7 — optional formatting directive governing which `marks` the inserted text
+       * units carry. Resolved against `story` + `normalizedRange` inside
+       * `applyLinearTextTransaction`. `undefined` (or `{ mode: "paragraph-default" }`)
+       * preserves pre-I7 behavior (no inherited run marks).
+       */
+      formatting?: TextFormattingDirective;
     }
   | {
       type: "delete_backward";
@@ -117,7 +125,8 @@ function applyLinearTextTransaction(
 ): TextTransactionResult {
   const story = parseTextStory(document.content);
   const normalizedRange = resolveRange(selection, story.size, intent);
-  const insertionUnits = createInsertionUnits(intent, story, normalizedRange.from);
+  const resolvedMarks = resolveMarksForInsertion(intent, story, normalizedRange);
+  const insertionUnits = createInsertionUnits(intent, story, normalizedRange.from, resolvedMarks);
 
   // `normalizedRange.{from,to}` are logical positions (scope markers = 0 width,
   // matching surface-projection). Translate to unit-array indices so scope
@@ -779,6 +788,7 @@ function createInsertionUnits(
   intent: TextTransactionIntent,
   story: TextStory,
   position: number,
+  marks: TextMark[] | undefined,
 ): StoryUnit[] {
   if (intent.type !== "replace") {
     return [];
@@ -792,6 +802,7 @@ function createInsertionUnits(
         return Array.from(entry.text).map<StoryUnit>((character) => ({
           kind: "text",
           value: character,
+          ...(marks && marks.length > 0 ? { marks: marks.map((mark) => ({ ...mark })) } : {}),
         }));
       case "tab":
         return [{ kind: "tab" }];
@@ -808,6 +819,79 @@ function createInsertionUnits(
   });
 }
 
+/**
+ * I7 — given a formatting directive, produce the `marks` array that inserted text
+ * units should carry. Returns `undefined` for the paragraph-default path (no marks).
+ *
+ * - `paragraph-default` / no directive → `undefined`.
+ * - `explicit` → caller-supplied marks verbatim.
+ * - `match-replaced-range`:
+ *   - If the range is collapsed, use the marks of the text unit immediately left of
+ *     the caret (Word-matching behavior for empty-range inserts).
+ *   - Otherwise walk text units in `[from, to)`. If every text unit shares the same
+ *     marks (by type), use them. Mixed → fall back to paragraph-default (`undefined`).
+ */
+function resolveMarksForInsertion(
+  intent: TextTransactionIntent,
+  story: TextStory,
+  range: { from: number; to: number },
+): TextMark[] | undefined {
+  if (intent.type !== "replace") {
+    return undefined;
+  }
+  const directive = intent.formatting;
+  if (!directive || directive.mode === "paragraph-default") {
+    return undefined;
+  }
+  if (directive.mode === "explicit") {
+    return directive.marks.map((mark) => ({ ...mark }));
+  }
+
+  // match-replaced-range
+  const unitFrom = logicalPositionToUnitIndex(story.units, range.from, "before");
+  const unitTo = logicalPositionToUnitIndex(story.units, range.to, "after");
+
+  if (range.from === range.to) {
+    // Empty range — inherit from the text unit immediately left of the caret.
+    for (let i = unitFrom - 1; i >= 0; i -= 1) {
+      const unit = story.units[i];
+      if (unit?.kind === "text") {
+        return unit.marks ? unit.marks.map((mark) => ({ ...mark })) : undefined;
+      }
+      if (unit?.kind === "paragraph_break") {
+        break;
+      }
+    }
+    return undefined;
+  }
+
+  const textUnits: Array<{ marks?: TextMark[] }> = [];
+  for (let i = unitFrom; i < unitTo; i += 1) {
+    const unit = story.units[i];
+    if (unit?.kind === "text") {
+      textUnits.push(unit);
+    }
+  }
+  if (textUnits.length === 0) {
+    return undefined;
+  }
+  const firstMarks = textUnits[0].marks;
+  const uniform = textUnits.every((unit) => marksAreEqual(firstMarks, unit.marks));
+  if (!uniform) {
+    return undefined;
+  }
+  return firstMarks ? firstMarks.map((mark) => ({ ...mark })) : undefined;
+}
+
+function marksAreEqual(left: TextMark[] | undefined, right: TextMark[] | undefined): boolean {
+  if (!left && !right) return true;
+  if (!left || !right) return false;
+  if (left.length !== right.length) return false;
+  const sortedLeft = [...left].map((mark) => mark.type).sort();
+  const sortedRight = [...right].map((mark) => mark.type).sort();
+  return sortedLeft.every((type, index) => type === sortedRight[index]);
+}
+
 function resolveParagraphPropertiesAtPosition(
   story: TextStory,
   position: number,

package/src/internal/harness-debug-ports.ts

@@ -0,0 +1,168 @@
+/**
+ * @internal HARNESS-ONLY debug-ports token module.
+ *
+ * This module is **not listed in `package.json#exports`**, so
+ * downstream consumers of `@beyondwork/docx-react-component` cannot
+ * import it via any public entry point. The in-repo harness at
+ * `services/react-word-editor/` reaches it via a relative path
+ * (`../../../src/internal/harness-debug-ports`); that is the only
+ * supported caller.
+ *
+ * ## Why this exists
+ *
+ * It replaces the former public `showUnsupportedObjectPreviews?: boolean`
+ * prop on `WordReviewEditorProps`, which regressed to `true` three
+ * times through merges (PRs #124, #131, #160). Each regression leaked
+ * preserve-only preview chrome (charts, SmartArt, shapes, WordArt,
+ * VML, "N preserve-only features detected" banner, lock-callouts)
+ * into consumer applications.
+ *
+ * ## What the new shape buys us
+ *
+ * 1. **Type-level**: the `HarnessDebugPorts` brand uses a `unique
+ *    symbol` key that cannot be obtained outside this file, so
+ *    downstream TypeScript consumers cannot structurally construct a
+ *    valid token.
+ * 2. **Module-level**: this file is not in the package's export map.
+ *    External consumers would have to reach into the installed
+ *    package's internals via a non-guaranteed path to find it.
+ * 3. **Runtime gate**: even if a caller does manage to invoke
+ *    `__createHarnessDebugPorts`, the factory checks for a harness
+ *    environment marker (`globalThis.__DOCX_REACT_COMPONENT_HARNESS__`)
+ *    that only the harness sets via `__markHarnessEnvironment()`.
+ *    In a consumer app the flag is false; the returned token's
+ *    permissions are all `false` regardless of input.
+ * 4. **Intent assertion**: the factory input requires a literal
+ *    `confirmHarnessAuthor: "I-am-the-harness-dev-drawer"` string as
+ *    a self-documenting "I know what I'm doing" gate.
+ *
+ * Flipping any of (1)–(4) is the regression this module is designed
+ * to prevent. The invariant test at
+ * `test/ui/unsupported-previews-invariant.test.ts` locks them all.
+ */
+
+// NOT exported. The symbol's identity is what makes the brand
+// unobtainable from outside this module: `typeof` on a const symbol
+// gives TypeScript a `unique symbol` type that's only satisfiable
+// by the same `const` binding. Consumers that don't import this
+// module cannot satisfy the `[harnessDebugPortsBrand]: true` field.
+const harnessDebugPortsBrand = Symbol("harnessDebugPortsBrand");
+
+/**
+ * Opaque, brand-typed token passed through the internal
+ * `__harnessDebugPorts` editor prop. Cannot be constructed
+ * structurally — the brand key is a module-local `unique symbol`.
+ *
+ * @internal HARNESS-ONLY.
+ */
+export interface HarnessDebugPorts {
+  readonly [harnessDebugPortsBrand]: true;
+  /**
+   * Sanitized. Only `true` when the token factory confirmed
+   * harness-env + debug-mode + literal author assertion.
+   */
+  readonly unsupportedObjectPreviews: boolean;
+}
+
+const HARNESS_GLOBAL_KEY = "__DOCX_REACT_COMPONENT_HARNESS__" as const;
+
+/**
+ * Input to the harness-debug-ports token factory.
+ *
+ * @internal
+ */
+export interface HarnessDebugPortsInput {
+  /**
+   * Self-documenting author gate. Must be the literal string
+   * `"I-am-the-harness-dev-drawer"`. Any other value fails the
+   * runtime check and the token's flags are all `false`.
+   */
+  readonly confirmHarnessAuthor: "I-am-the-harness-dev-drawer";
+  /**
+   * Harness dev-drawer debug-mode toggle. Even if `true`, the factory
+   * refuses to honor the request unless the harness environment is
+   * active (`__markHarnessEnvironment()` was called).
+   */
+  readonly debugMode: boolean;
+  /**
+   * Requested preview-rendering permission. Honored only when all
+   * runtime checks pass.
+   */
+  readonly unsupportedObjectPreviews: boolean;
+}
+
+/**
+ * Build a harness-debug-ports token.
+ *
+ * Runtime gate: the returned token's `unsupportedObjectPreviews`
+ * field is `true` **only** when all of the following hold:
+ *
+ *   - `__markHarnessEnvironment()` was called previously (sets the
+ *     `__DOCX_REACT_COMPONENT_HARNESS__` global to `true`);
+ *   - `input.confirmHarnessAuthor === "I-am-the-harness-dev-drawer"`;
+ *   - `input.debugMode === true`;
+ *   - `input.unsupportedObjectPreviews === true`.
+ *
+ * Any check failure produces a fully-disabled token (same brand, all
+ * flags `false`). The editor component reads the token's flag
+ * through `readHarnessDebugPortsFlag()` so downstream rendering code
+ * sees a plain `boolean`.
+ *
+ * @internal HARNESS-ONLY.
+ */
+export function __createHarnessDebugPorts(
+  input: HarnessDebugPortsInput,
+): HarnessDebugPorts {
+  const harnessActive =
+    typeof globalThis !== "undefined" &&
+    (globalThis as Record<string, unknown>)[HARNESS_GLOBAL_KEY] === true;
+  const authorConfirmed =
+    input.confirmHarnessAuthor === "I-am-the-harness-dev-drawer";
+  const allow =
+    harnessActive && authorConfirmed && input.debugMode === true;
+  return Object.freeze({
+    [harnessDebugPortsBrand]: true as const,
+    unsupportedObjectPreviews:
+      allow && input.unsupportedObjectPreviews === true,
+  });
+}
+
+/**
+ * Mark the current JavaScript realm as a harness. MUST be called
+ * once, synchronously, before the first editor render so the token
+ * factory can confirm the environment.
+ *
+ * @internal HARNESS-ONLY.
+ */
+export function __markHarnessEnvironment(): void {
+  if (typeof globalThis !== "undefined") {
+    (globalThis as Record<string, unknown>)[HARNESS_GLOBAL_KEY] = true;
+  }
+}
+
+/**
+ * Read a sanitized flag from a token. Always returns `false` for
+ * `undefined` tokens (consumer code paths).
+ *
+ * @internal
+ */
+export function readHarnessDebugPortsFlag(
+  token: HarnessDebugPorts | undefined,
+  flag: "unsupportedObjectPreviews",
+): boolean {
+  if (!token) return false;
+  return token[flag] === true;
+}
+
+/**
+ * Test-only: reset the harness environment flag. Exported so the
+ * invariant/factory tests can assert the "consumer app" path
+ * (factory called without `__markHarnessEnvironment`).
+ *
+ * @internal TEST-ONLY.
+ */
+export function __resetHarnessEnvironmentForTests(): void {
+  if (typeof globalThis !== "undefined") {
+    delete (globalThis as Record<string, unknown>)[HARNESS_GLOBAL_KEY];
+  }
+}

package/src/io/chart-preview-resolver.ts

@@ -24,6 +24,7 @@ import type {
   InlineNode,
   MediaItem,
   ParagraphNode,
+  ResolvedTheme,
 } from "../model/canonical-document.ts";
 import type {
   ChartPreviewResolveParams,
@@ -31,11 +32,34 @@ import type {
 } from "../api/public-types.ts";
 import type { OpcPackage } from "./opc/package-reader.ts";
 import { normalizePartPath, resolveRelationshipTarget } from "./ooxml/part-manifest.ts";
+import { parseThemeXml, resolveTheme } from "./ooxml/parse-theme.ts";
+
+/**
+ * Parse and resolve the workbook theme once, tolerating malformed XML.
+ * An unparseable theme must NOT abort the import — fall back to
+ * undefined so downstream renderers use the fallback palette.
+ */
+function tryParseTheme(themeXml: string): ResolvedTheme | undefined {
+  try {
+    return resolveTheme(parseThemeXml(themeXml));
+  } catch {
+    return undefined;
+  }
+}
 
 interface ResolveContext {
   readonly package: OpcPackage;
   readonly adapter: EditorHostAdapter;
   readonly themeXml: string | undefined;
+  /**
+   * Once-per-import cache of the workbook theme. Stage 2 wiring:
+   * in-tree renderers consume `parsedTheme` via
+   * `composeSeriesColor(model, parsedTheme, seriesIdx)` to resolve a
+   * series palette entry into a concrete sRGB string without re-parsing
+   * theme XML on every render. Undefined when the document has no
+   * theme1.xml or when parseThemeXml threw.
+   */
+  readonly parsedTheme: ResolvedTheme | undefined;
   /** Monotonic counter so we can generate unique media ids across one run. */
   seq: number;
 }
@@ -63,8 +87,15 @@ export async function resolveChartPreviewsForDocument(
   if (pending.length === 0) return doc;
 
   const themeXml = extractPartTextFromPackage(pkg, "/word/theme/theme1.xml");
+  const parsedTheme = themeXml ? tryParseTheme(themeXml) : undefined;
   const renderer = adapter.renderChartPreview;
-  const ctx: ResolveContext = { package: pkg, adapter, themeXml, seq: 0 };
+  const ctx: ResolveContext = {
+    package: pkg,
+    adapter,
+    themeXml,
+    parsedTheme,
+    seq: 0,
+  };
 
   const resolutions = await Promise.all(
     pending.map(async (entry) => {

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

@@ -760,11 +760,56 @@ function walkInlineNodeForBoundaries(
       return;
     }
     case "t": {
-      const text = node.children
-        .filter((child): child is XmlTextNode => child.type === "text")
-        .map((child) => child.text)
-        .join("");
-      setCursor(getCursor() + Array.from(text).length);
+      // O8 fix: emit a boundary entry for every interior code-point position
+      // so comment anchors landing mid-run resolve to a real source byte
+      // offset instead of silently dropping into skippedCommentIds. The walk
+      // advances through the raw XML source between each text child's start
+      // and end, treating XML entities (& < > " ' &#N;
+      // &#xN;) as a single code point whose byte cursor skips the whole
+      // entity. Surrogate pairs collapse to one code point to match
+      // Array.from(text).iteration used by the existing cursor math.
+      let cursor = getCursor();
+      for (const child of node.children) {
+        if (child.type !== "text") {
+          continue;
+        }
+        let byte = child.start;
+        const end = child.end;
+        while (byte < end) {
+          if (!boundaries.has(cursor)) {
+            // Preserve the outer <w:r>-entry at runStart: it maps cursor to
+            // node.start (between runs, a valid insertion point), whereas the
+            // interior byte here would point inside <w:t> where inserting
+            // commentRangeStart/End would corrupt the text node.
+            boundaries.set(cursor, byte);
+          }
+          const ch = sourceXml.charCodeAt(byte);
+          if (ch === 0x26 /* & */) {
+            const semi = sourceXml.indexOf(";", byte + 1);
+            if (semi !== -1 && semi < end) {
+              byte = semi + 1;
+            } else {
+              byte += 1;
+            }
+          } else if (ch >= 0xd800 && ch <= 0xdbff && byte + 1 < end) {
+            // High surrogate followed by low surrogate = 1 code point / 2 units.
+            byte += 2;
+          } else {
+            byte += 1;
+          }
+          cursor += 1;
+        }
+        // Trailing boundary: map the cursor immediately after the last
+        // character to the byte just before </w:t>, so an anchor at the right
+        // edge of this text node resolves inside the run. The outer <w:r>
+        // close will overwrite nothing here because it runs after the inner
+        // walk and uses boundaries.set (last-write-wins is fine: node.end
+        // points to the same logical insertion point between runs).
+        if (!boundaries.has(cursor)) {
+          boundaries.set(cursor, end);
+        }
+      }
+      setCursor(cursor);
       return;
     }
     case "tab":

package/src/io/export/serialize-main-document.ts

@@ -26,6 +26,7 @@ import {
 } from "./table-properties-xml.ts";
 import { twip } from "./twip.ts";
 import { escapeXmlAttribute } from "./escape-xml-attribute.ts";
+import { emitPropertyGrabBag } from "../ooxml/property-grab-bag.ts";
 
 const HYPERLINK_RELATIONSHIP_TYPE =
   "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
@@ -1607,6 +1608,14 @@ export function serializeSectionPropertiesXml(props: SectionProperties): string
     }
   }
 
+  // O2 Slice 4 grab-bag: unmodelled sectPr children preserved verbatim
+  // from import. Emitted last so the modelled body stays ECMA-376 canonical
+  // and extension-namespace properties land at the tail of <w:sectPr>.
+  const grabBagXml = emitPropertyGrabBag(props.unknownPropertyChildren);
+  if (grabBagXml.length > 0) {
+    children.push(grabBagXml);
+  }
+
   if (children.length === 0) {
     return "<w:sectPr/>";
   }

package/src/io/export/serialize-paragraph-formatting.ts

@@ -12,6 +12,7 @@ import type {
   ParagraphSpacing,
   TabStop,
 } from "../../model/canonical-document.ts";
+import { emitPropertyGrabBag } from "../ooxml/property-grab-bag.ts";
 import { buildRunPropertiesXml } from "./serialize-run-formatting.ts";
 
 function escXml(value: string): string {
@@ -147,6 +148,13 @@ export function buildParagraphPropertiesXml(
     if (markXml) parts.push(markXml);
   }
 
+  // 16. Grab-bag: unmodelled pPr children preserved verbatim from import.
+  // Emitted last so the typed emit order above stays ECMA-376 canonical and
+  // any extension-namespace properties land after the modelled set. Word
+  // tolerates extra trailing children inside <w:pPr> better than it
+  // tolerates interleaving them with the typed set.
+  parts.push(emitPropertyGrabBag(pPr.unknownPropertyChildren));
+
   const body = parts.filter(Boolean).join("");
   return body.length > 0 ? `<w:pPr>${body}</w:pPr>` : "";
 }

package/src/io/export/serialize-run-formatting.ts

@@ -8,6 +8,7 @@
  */
 
 import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
+import { emitPropertyGrabBag } from "../ooxml/property-grab-bag.ts";
 
 function escXml(value: string): string {
   return value
@@ -57,10 +58,12 @@ export function buildRunPropertiesXml(rPr: CanonicalRunFormatting | undefined):
   parts.push(toggleEl("vanish", rPr.vanish));
 
   // 8. color
-  if (rPr.colorHex || rPr.colorThemeSlot) {
+  if (rPr.colorHex || rPr.colorThemeSlot || rPr.colorThemeTint || rPr.colorThemeShade) {
     const attrs: string[] = [];
     if (rPr.colorHex) attrs.push(`w:val="${escXml(rPr.colorHex)}"`);
     if (rPr.colorThemeSlot) attrs.push(`w:themeColor="${escXml(rPr.colorThemeSlot)}"`);
+    if (rPr.colorThemeTint) attrs.push(`w:themeTint="${escXml(rPr.colorThemeTint)}"`);
+    if (rPr.colorThemeShade) attrs.push(`w:themeShade="${escXml(rPr.colorThemeShade)}"`);
     parts.push(`<w:color ${attrs.join(" ")}/>`);
   }
 
@@ -85,6 +88,12 @@ export function buildRunPropertiesXml(rPr: CanonicalRunFormatting | undefined):
   if (rPr.fontSizeHalfPoints !== undefined) parts.push(`<w:sz w:val="${rPr.fontSizeHalfPoints}"/>`);
   if (rPr.fontSizeCsHalfPoints !== undefined) parts.push(`<w:szCs w:val="${rPr.fontSizeCsHalfPoints}"/>`);
 
+  // 15. Grab-bag: unmodelled rPr children preserved verbatim from import
+  // (extension-namespace properties like <w14:textOutline>, Word-internal
+  // knobs like <w:em>, <w:kern>). Emitted last so the typed body stays
+  // ECMA-376 canonical and Word tolerates extras at the tail of <w:rPr>.
+  parts.push(emitPropertyGrabBag(rPr.unknownPropertyChildren));
+
   const body = parts.filter(Boolean).join("");
   return body.length > 0 ? `<w:rPr>${body}</w:rPr>` : "";
 }