@file-viewer/docx 0.3.32 → 0.3.34

package/README.md

@@ -30,7 +30,6 @@ dist/jszip.min.js
 const options = {
   useWorker: true,
   workerUrl: "dist/docx-preview.worker.js",
-  workerJsZipUrl: "dist/jszip.min.js",
   awaitLayout: true,
   strictWordCompatibility: true,
   ignoreLastRenderedPageBreak: false,
@@ -54,8 +53,7 @@ import { renderAsync } from "@file-viewer/docx";
 
 await renderAsync(fileOrArrayBuffer, container, null, {
   useWorker: true,
-  workerUrl: new URL("@file-viewer/docx/dist/docx-preview.worker.js", import.meta.url).toString(),
-  workerJsZipUrl: new URL("@file-viewer/docx/dist/jszip.min.js", import.meta.url).toString(),
+  workerUrl: new URL("@file-viewer/docx/worker", import.meta.url).toString(),
   awaitLayout: true
 });
 ```
@@ -119,6 +117,19 @@ await renderDocument(document, container, null, { reviewMode: "original" });
 Set `renderComments: false` explicitly when tracked changes are required without
 the comments surface.
 
+The default `reviewPresentation: "balloon"` keeps deleted text as anchors for a
+margin review rail. Hosts without a rail can pass `reviewPresentation: "inline"`
+to show deletions with strikethrough using the engine's own styles.
+
+Measured tabs, DrawingML/VML anchor origins, VML text viewports, merged-cell
+edges and page backgrounds are handled by the engine. Drawing text boxes use
+independent HTML stories so serialization preserves their paragraph boundaries;
+exporters do not need to replace or repair generated elements. `renderAsync()`
+updates coordinates after fonts, images, pagination and container resizing.
+Call `disposeRenderedDocument(container)` when unmounting to release document
+observers and bookmark handlers. Rendering again in the same container releases
+the previous handlers automatically.
+
 The mode values follow Word's **Display for Review** semantics: `simple` keeps
 the current text with compact change indicators, `all` exposes every supported
 revision and comment anchor, `final` is the current document with markup hidden,
@@ -209,7 +220,6 @@ collectLayoutSnapshot(
   // Worker and responsiveness
   useWorker: true,
   workerUrl: "dist/docx-preview.worker.js",
-  workerJsZipUrl: "dist/jszip.min.js",
   workerFallback: true,
   workerTimeout: 120000,
   renderPageBatchSize: 2,
@@ -242,12 +252,20 @@ collectLayoutSnapshot(
 The production path is intentionally split into stages:
 
 1. The main thread starts a Worker using `workerUrl`.
-2. The Worker loads JSZip using `workerJsZipUrl`, unzips the package, parses XML parts, resolves relationships and serializes a compact document snapshot.
+2. The self-contained Worker uses its bundled JSZip and XML parser imports to unzip the package, parse XML parts, resolve relationships and serialize a compact document snapshot. The default needs no external script, global XML shim or separately appended bootstrap.
 3. The main thread restores the snapshot into `WordDocument` and renders HTML pages in batches, yielding to `requestIdleCallback`, `requestAnimationFrame` or `setTimeout` between page batches.
 4. `awaitRenderedLayout` waits for images and fonts, runs dynamic overflow pagination and returns a `LayoutSnapshot`.
 5. `collectLayoutSnapshot` can be used in CI or telemetry to detect overflow pages, unresolved media, page count, aggregate text length, fields and floating objects.
 
-Batch rendering and browser yields avoid the former demo-page freeze caused by inserting very large DOM trees in one task. When Worker parsing is enabled, keep `workerFallback: true` unless the target Worker runtime provides every required XML API.
+An awaited layout includes font/image settlement and the resulting tab, drawing
+and pagination measurements. It rejects if that render is replaced, its mounted
+container is removed, or pagination cannot settle within
+`maxDynamicPaginationPasses`. An `AbortError` identifies an obsolete or removed
+render. With `awaitLayout: false`, rendering can return before these measurements
+finish; call `awaitRenderedLayout` before measuring or exporting the result.
+A detached `renderDocument` result may still be mounted and awaited later.
+
+Batch rendering and browser yields avoid the former demo-page freeze caused by inserting very large DOM trees in one task. The supplied Worker includes its XML APIs. `workerFallback: true` remains useful when Worker startup is blocked by the host environment. If `workerJsZipUrl` is explicitly set, the Worker loads and uses that JSZip asset. The selection must be a non-empty same-origin HTTP(S) or Blob URL without credentials. Relative URLs resolve against the Worker script URL; a Blob Worker requires an absolute URL. Cross-origin URLs and opaque origins are rejected before import, even when a global JSZip implementation is already present. Omit this option to use the bundled dependency; an explicit invalid value does not select the default. A failed load or invalid JSZip export is reported as an error; it never silently substitutes the bundled dependency. `workerFallback` continues to control main-thread fallback; set it to `false` when any Worker or selected-dependency failure must reject the call.
 
 ## Pagination, headers/footers and TOC
 
@@ -281,7 +299,16 @@ URL-bearing attributes before it reaches a maximally restricted sandboxed iframe
 
 Set `darkMode: true` to reproduce Word Online's "Switch Modes" dark appearance. Every color the renderer emits — text, backgrounds/highlights, borders, underlines, theme colors and DrawingML/VML shape fills and strokes — is converted with the same lightness-inversion algorithm Microsoft uses for this exact purpose (see `roosterjs`'s `getDarkColor`): the color is converted to CIE Lab, only the lightness (`L`) channel is inverted around a fixed base value (the `L` of `#333333`), and hue/chroma (`a`/`b`) are left untouched. That guarantees every color stays legible on a dark page — pure black becomes pure white, pure white becomes `#333333`, and an arbitrary color such as `rgb(99, 36, 35)` keeps its reddish hue while becoming light enough to read — without the hue-flipping side effects of a naive per-channel RGB invert. The toggle is purely a rendering-time CSS transform — it does not change the parsed document model — and every transformed color is wrapped in a CSS variable so that `@media print` can restore the exact original light-mode value; print output always renders with Word's normal light appearance regardless of `darkMode`.
 
-Header/footer selection follows the WordprocessingML print-layout rules: `first` header/footer references are used only when the section has `w:titlePg`, and `even` references are used only when document settings contain `w:evenAndOddHeaders`; otherwise the default/odd header is used. This prevents even-page empty headers from hiding the normal header in documents that merely contain unused even header references.
+Header/footer selection follows the WordprocessingML print-layout rules: `first` references apply to the first page of a section with `w:titlePg`, and `even` references apply only when settings contain `w:evenAndOddHeaders`. Each omitted reference inherits its own variant from the previous section. If a selected variant is absent in the first section, its header/footer is blank. Dynamic continuation pages select their own first/even/default variant instead of repeating a cloned first-page header/footer.
+
+Adjacent saved page markers do not create extra blank pages, including a saved marker immediately after an authored page break. Repeated authored `w:br w:type="page"` breaks still preserve an intentional blank page.
+
+Footnotes begin on the page containing their first visible reference. Long note
+text continues in order across pages, preserving authored text, formatting and
+embedded resources. Endnotes follow the final body content. Custom note marks
+and section/page restart settings are kept separate from generated numbering.
+An indivisible note object that cannot fit the printable page is retained and
+reported as an unresolved layout error instead of being silently clipped.
 
 Complex-script formatting is kept script-aware. `w:iCs` and `w:bCs` now affect RTL/complex-script spans, but they are not applied to East Asian TOC text; this avoids turning Chinese TOC level 3 entries italic when the DOCX only specified complex-script italics.
 
@@ -305,20 +332,33 @@ It renders `tests/regression/database-design.docx` and asserts that TOC entries
 
 ## Build
 
-This repository includes a lightweight build script that emits synchronized, minified CommonJS, ESM and Worker bundles:
+All JavaScript is generated by Rollup from the TypeScript source entry points. The build emits readable and minified UMD/CommonJS-compatible and ESM bundles, a self-contained Worker, and declarations generated by the local TypeScript compiler. Existing output is cleaned first, and `npm pack` rebuilds it automatically:
 
 ```bash
 npm run build
 ```
 
-Run the complete build and semantic regression suite with:
+Install the lockfile dependencies with `npm ci`. No global compiler or `NODE_PATH` is required. `dist/jszip.min.js` is copied unchanged from the declared JSZip dependency for standalone main-thread use; bundled dependency licenses are retained in `dist/THIRD_PARTY_NOTICES.txt`.
+
+Run the complete build, semantic regressions and package contract checks with:
 
 ```bash
 npm run verify
 ```
 
+Run `npm run test:worker` for the isolated Node VM protocol checks. This is not a browser test. Run `npm run e2e:worker` (Chromium) and `npm run e2e:worker -- webkit` to verify the generated Worker, main-thread parity, genuine selected JSZip fetch/hash, and dependency/XML failure controls in real browsers. Set `DOCX_WORKER_JSZIP_PATH` to another installed JSZip browser asset when checking a consumer-resolved version. These checks never append parser code to the Worker.
+
 Browser-focused checks remain available through `npm run e2e`, `npm run e2e:chart` and `npm run e2e:header-guard`.
 
+These commands run the existing Jasmine specs in the pinned Playwright browser,
+served only on loopback. Install Chromium and Firefox with
+`npx playwright install chromium firefox` before running them; `e2e:security`
+runs both browsers with the strict CSP and Trusted Types fixture. Pass
+`-- --browsers chromium,webkit` to select other installed engines.
+`npm run e2e-watch` reruns the same specs after changes to `tests` or `dist`.
+The runner uses native file enumeration and watching instead of the legacy
+Karma glob dependencies, which included the unpatched `braces` recursion flaw.
+
 ## Local demo
 
 Serve the repository over HTTP and open the root page:
@@ -329,6 +369,21 @@ python3 -m http.server 8000
 
 The demo is self-contained for normal DOCX files, includes sample documents, page navigation, light/dark rendering and an options panel. TIFF support is loaded only when a document actually contains TIFF media.
 
+## Optional display targets
+
+Pass `exposeDisplayTargets: true` to `renderAsync` (or to both `parseAsync`
+and `renderDocument` when used separately) to expose paragraph identities as
+`data-office-target` attributes. The value is the OOXML part path followed by
+`#p:<w14:paraId>`, or `#xpath:<structural-path>` when no paragraph ID is stored.
+Repeated headers and split paragraph fragments may share an identity.
+
+This option is disabled by default and works with the matching Worker bundle.
+It adds read-only identity metadata, not an editing or document write-back API.
+An external display adapter may use it to locate rendered text. Reloading or
+repaginating the document can replace DOM nodes; adapters must reapply their
+own cached display state. Identities are scoped to the source package and are
+not guaranteed across structural edits to the original file.
+
 ## Notes on fidelity
 
 The renderer follows OOXML semantics and uses browser-native layout. It is designed for production preview and regression testing, not for claiming byte-for-byte or pixel-perfect identity with Microsoft Word's private layout engine. Use `LayoutSnapshot` and the supplied regression fixture to monitor the remaining differences that depend on browser fonts, font fallback and shaping engines.