@aseity/idocs-preview 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @aseity/idocs-preview
 
+## 0.3.0
+
+### Minor Changes
+
+- Add `Session.exportDocx` to export iDocs source bytes and referenced images as a Word document in the browser. Invalid source, missing images and unapproved conversion losses reject instead of producing a partial file.
+
+## 0.2.0
+
+### Minor Changes
+
+- Use browser-local fonts for text measurement and Canvas drawing without downloading font files. Remove the font-file mode and the `readFont` / `readFamily` callbacks from the web API, and exclude the native shaping engine from the WASM bundle to reduce its download size. Mathematical symbols retain their embedded fonts. Different installed fonts can change line breaks and pagination.
+- Floating objects (`floats` on a paragraph) now show in the preview: pictures, shapes, text boxes
+  and groups, over or behind the text, turned and flipped about their centres. The display list
+  gains two item kinds, `shape` (SVG path data, filled and/or stroked, with dashes) and `transform`
+  (an SVG matrix around rotated or flipped objects), and the `textbox` story for a text box's glyph
+  runs, whose lines are not in the hit-testing table.
+
+### Patch Changes
+
+- Lines between bordered paragraphs (Word's "between" paragraph border, `w:pBdr/w:between`)
+  now show in the preview: a line between each two adjacent paragraphs that share it, with
+  its spacing above and below, and none above the first or below the last.
+- Numbered and bulleted lists in table cells now show in the preview as lists: their labels
+  count on with the lists outside the table in document order (row by row, cell by cell),
+  and their indents are measured from the cell's text area, as Word does. Converted Word
+  documents keep the numbering of list paragraphs in table cells instead of dropping it.
+- Emphasis marks (Word's `w:em`: dot, comma, circle, under dot) now show in the preview, one
+  per character except spaces. Path items in the display list may carry the role
+  `emphasisMark`.
+- Text set to a fixed width in Word (Fit Text, `w:fitText`) now keeps that width in the
+  preview: wider spacing when the text is shorter, glyphs compressed horizontally when it
+  is longer. Glyph runs in the display list carry `scaleX` when compressed.
+- Tables in table cells now show in the preview as tables: each sits in its cell's text area
+  the way a table sits in the page's text area, the outer row grows to hold it, and a row
+  that runs onto the next page splits the table in it between its rows, as Word does.
+  Converted Word documents keep a table in a cell as a table instead of flattening it into
+  the cell's paragraphs.
+- Character scale and baseline shift (Word's `w:w` and `w:position`) now show in the preview:
+  `scaleX` on a glyph run also carries the character scale, and `baseline` the shift.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -1,10 +1,10 @@
 # iDocs preview
 
 Read-only browser preview for Word documents (`.docx`) and iDocs source documents
-(`.idoc`). A Web Worker converts and lays out the document with Word-calibrated font
-metrics in WASM, and the view paints each page on a canvas. Pages break where the
-layout predicts Word breaks them; glyphs are drawn with the browser's local fonts,
-so their shapes can differ from Word.
+(`.idoc`). A Web Worker measures browser-local fonts with Canvas and lays out
+the document in WASM. Canvas draws text using the same font settings. No text
+font downloads or Local Font Access permissions are required. Different installed
+fonts can change line breaks and page counts.
 
 The package ships ES modules, TypeScript declarations, the worker and the WASM
 binary. It has no framework dependency and runs only in browsers.
@@ -13,6 +13,19 @@ binary. It has no framework dependency and runs only in browsers.
 npm install @aseity/idocs-preview
 ```
 
+## Local development
+
+```sh
+npm ci
+npm run dev
+```
+
+The build prepends `$CARGO_HOME/bin` (default `~/.cargo/bin`) to its own PATH
+so rustup selects `rust/rust-toolchain.toml`, even when Homebrew Rust comes
+first in your shell. The toolchain file includes the WASM target. No global
+PATH changes or `.env` file are needed. Install rustup and wasm-bindgen CLI
+0.2.128 before building.
+
 ## Quick start
 
 ```ts
@@ -37,6 +50,7 @@ during server rendering.
 - `@aseity/idocs-preview/core`: the headless session. `createSession()` starts the
   worker; `session.open(bytes, options)` resolves to a `PreviewDocument` with the
   pages' display lists, diagnostics and conversion losses.
+  `session.exportDocx(bytes, options)` exports iDocs source to DOCX bytes.
 - `@aseity/idocs-preview/view`: the reference view. `createPreview(container)`
   owns a session and a view; `mountPreview(container, doc)` shows a document you
   opened yourself. Both re-export the core types.
@@ -57,9 +71,64 @@ so the caller can keep using them, for example to download the original.
   (`docx-not-zip`, `docx-encrypted`, `docx-legacy-doc`, `docx-invalid-package`,
   `docx-strict-ooxml`).
 
-DOCX conversion is lossy: features iDocs does not model, such as text boxes,
-floating images, tracked changes and comments, are downgraded or omitted and listed
-in `conversionLosses`.
+DOCX conversion is lossy: supported floating images, shapes, text boxes and groups
+are preserved as floating objects. Tracked changes, comments and object properties
+outside the model are downgraded or omitted and listed in `conversionLosses`.
+
+### Preview transport
+
+Every open transfers glyph coordinates and text indices in binary buffers.
+Coordinates retain double precision. The painter and hit testing read those
+buffers directly. Page, line, and drawing metadata still use JSON.
+
+Opened previews expose read-only glyph arrays. Indexed glyph objects are
+snapshots; changing one does not change the drawing buffer. Array traversal,
+selection, copying, and JSON serialization remain available.
+
+By default, the view displays the document after every page is ready.
+`createPreview(container, { progressive: true })` shows a provisional first-page
+canvas while later display pages are generated. Full pagination completes before
+any page is sent. Selection and find become available when `open` resolves.
+A failure removes the provisional page.
+
+Headless sessions can receive provisional pages through `open(bytes, { onPage })`.
+Each packet contains a page, the total page count, and cumulative image and glyph
+outline resources. Resource arrays grow as later pages arrive. Resource retries
+can restart delivery from page one. The final promise resolves to the complete
+document. A callback exception rejects its open.
+
+The development page enables progressive delivery with `?progressive=1`.
+There is no `compact` option or legacy JSON-only transport.
+
+## Exporting Word documents
+
+`session.exportDocx(bytes, { name?, readResource? })` exports an iDocs source
+into DOCX bytes. It accepts the same byte types and image callback as `open`.
+The source bytes are copied before transfer. Every export owns its resources,
+so concurrent opens and exports remain independent.
+
+```ts
+const session = createSession();
+try {
+  const bytes = await session.exportDocx(source, {
+    name: "report.idoc",
+    readResource: (path) => readImage(path),
+  });
+  const file = new Blob([bytes], {
+    type: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  });
+  saveFile(file, "report.docx");
+} finally {
+  session.dispose();
+}
+```
+
+Export uses browser font measurements for layout and preserves the document's
+font declarations in DOCX. Word may paginate differently on the recipient's
+machine. Invalid source, unavailable or invalid images, layout errors and
+unapproved conversion losses reject with `PreviewError`. Export never replaces
+missing images with preview placeholders. Export failures also include the
+`export-failed` code. Disposing the session rejects pending and future exports.
 
 ## View
 
@@ -91,19 +160,78 @@ addresses: `createPreview(el, { session: { workerUrl, wasmUrl } })`, where
 `workerUrl` points to `dist/core/worker.js` and `wasmUrl` to
 `wasm/idocs_wasm_bg.wasm`.
 
+Use the same package version for the session and its worker. The successful worker
+response carries metadata JSON, a binary glyph buffer, and separate image buffers. Progressive opens send resource deltas and page packets
+before the final response. Custom workers must implement the corresponding
+message variants in `src/core/protocol.ts`.
+
 The worker is a same-origin module worker. Serve the WASM file as
 `application/wasm`. A Content Security Policy needs `script-src
 'wasm-unsafe-eval'` and `worker-src 'self'`.
 
 ## Fonts
 
-Layout uses metric profiles built into the WASM for Microsoft YaHei, SimSun,
-DengXian, SimHei, FangSong, KaiTi, PMingLiU, Microsoft JhengHei, Arial, Times New
-Roman, Consolas, Calibri and Courier New. Each glyph is drawn at the position its
-profile gives, in the closest local font. Characters outside the profiles are
-measured with the stand-in fonts the optional `session.readFont(name)` callback
-returns, or with the browser's fonts when it is absent, so their line breaks can
-differ slightly from the iDocs CLI.
+The web preview uses installed browser fonts. The Worker uses
+OffscreenCanvas `measureText()` for widths and font extents; the view uses the same
+CSS family chain, weight, style and kerning policy with `fillText()`. Missing families
+fall back through the browser's installed fonts. Source text and UTF-16 offsets
+remain available for selection, copying and search. Math continues to use embedded
+KaTeX resources and does not download fonts.
+
+Native snapshots use actual font files. Their line breaks and page counts may
+therefore differ from a browser with different installed fonts.
+
+The WASM build excludes the native font-file feature and HarfRust. There is no
+font-file mode, `readFont` or `readFamily` API. Font file registrations in a document
+do not become network requests. Native builds retain the complete font-file
+resolver, shaping and outline engine. The browser retains the embedded KaTeX
+resources and the parser needed for mathematical outlines.
+
+## Profile core document opening
+
+Build separate timing and allocation modules from the repository root. Run Cargo
+inside `rust/` so rustup selects the pinned toolchain. Use wasm-bindgen CLI
+0.2.128 for both modules.
+
+```sh
+(cd rust && cargo build --profile wasm -j 4 -p idocs-wasm --target wasm32-unknown-unknown --features perf-profile)
+wasm-bindgen rust/target/wasm32-unknown-unknown/wasm/idocs_wasm.wasm --target web --out-dir .audit/core-profile/timing --out-name idocs_wasm
+(cd rust && cargo build --profile wasm -j 4 -p idocs-wasm --target wasm32-unknown-unknown --features perf-alloc)
+wasm-bindgen rust/target/wasm32-unknown-unknown/wasm/idocs_wasm.wasm --target web --out-dir .audit/core-profile/alloc --out-name idocs_wasm
+```
+
+Start Vite in another terminal with `cd web && npx vite --host 127.0.0.1 --port
+5174 --strictPort`. Install Playwright and its Chromium browser in your tooling
+environment. If this script cannot resolve `playwright`, set `PLAYWRIGHT_MODULE`
+to its entry module path.
+
+```sh
+node web/scripts/profile-core.mjs path/to/sample.docx path/to/source.idoc
+```
+
+The script uses a blank page without Vite HMR and a fresh, isolated Worker for
+each run. Each Worker uses the real browser Canvas measurements and enables
+`configureProfile`. Runs are sequential and alternate mode order across at least
+five rounds. Stop other builds and benchmarks before measuring.
+
+Input paths and `OUT` resolve relative to the repository root. Configure
+`BASE_URL`, `ROUNDS`, `TIMEOUT_MS`, and `OUT` through environment variables.
+`PROFILE_DIRS` is a JSON object mapping mode names to module directories, such as
+`{"before":".audit/before","after":".audit/after"}`. Vite must allow access to
+these files and inputs through `/@fs`. The default output is
+`.audit/core-profile/results.json`. Each row includes the complete profile,
+elapsed milliseconds, a combined SHA-256 of metadata, glyph buffers, and images,
+page and conversion loss counts,
+diagnostic counts, output bytes, and WASM memory capacity.
+
+The elapsed timer covers `openDocument`, including Rust output serialization.
+It excludes module initialization, input fetch, profile retrieval, JavaScript
+JSON parsing, and hashing. Allocation instrumentation adds overhead. Compare
+timings with `perf-profile` builds and allocation counts with `perf-alloc` builds.
+Live allocation bytes measure requested bytes. WASM memory capacity measures
+linear memory reserved by the instance. Neither measures physical memory.
+The allocation counters require a single-threaded, isolated Worker. Normal
+builds leave both profiling features off.
 
 ## License
 

package/dist/core/display.d.ts

@@ -1,11 +1,28 @@
-export type Story = 'body' | 'header' | 'footer' | 'footnotes';
+/** `textbox`: a floating text box's text (#552), whose lines are not in the hit-testing table. */
+export type Story = 'body' | 'header' | 'footer' | 'footnotes' | 'textbox' | 'lineNumber';
 export interface Rect {
     x: number;
     y: number;
     width: number;
     height: number;
 }
+export interface GlyphOutline {
+    faceId: string;
+    family: string;
+    glyphId: number;
+    d: string;
+}
+export interface GlyphShape {
+    outline: number;
+    advance: number;
+    xOffset: number;
+    yOffset: number;
+    cluster: number;
+}
 export interface Glyph {
+    shapes?: GlyphShape[];
+    /** Display-only discretionary mark; does not consume source text. */
+    generated?: 'automatic' | 'manual';
     /** Left edge from the metric profile. */
     x: number;
     /** Width occupied in the line, including added spacing. */
@@ -31,13 +48,17 @@ export interface GlyphRun {
     size: number;
     bold: boolean;
     italic: boolean;
+    /** Horizontal scale of each glyph about its left edge: the character scale times a compressing fit-width group's; absent when 1. */
+    scaleX?: number;
     color: string;
     baseline: number;
     lineTop: number;
     lineHeight: number;
-    glyphs: Glyph[];
+    /** Read-only in opened previews; indexed glyph objects are snapshots. */
+    glyphs: readonly Glyph[];
+    syntheticSlant?: number;
 }
-export type RectRole = 'areaFill' | 'border' | 'shading' | 'characterBorder' | 'underline' | 'strike' | 'footnoteSeparator' | 'mathRule';
+export type RectRole = 'areaFill' | 'border' | 'shading' | 'characterBorder' | 'underline' | 'strike' | 'footnoteSeparator' | 'mathRule' | 'pageBorder';
 export interface RectItem extends Rect {
     kind: 'rect';
     role: RectRole;
@@ -61,7 +82,8 @@ export interface ImageItem extends Rect {
 }
 export interface PathItem {
     kind: 'path';
-    role: 'mathGlyph' | 'mathPath';
+    /** emphasisMark: an emphasis mark, `d` in em about its centre. */
+    role: 'mathGlyph' | 'mathPath' | 'emphasisMark';
     d: string;
     transform: [number, number, number, number, number, number];
     color: string;
@@ -70,6 +92,20 @@ export interface PathItem {
         file: string;
         char: string;
         size: number;
+        text?: {
+            browser?: {
+                family: string;
+                declaredFamily: string;
+                bold: boolean;
+                italic: boolean;
+            };
+            standIn: {
+                strokeEm?: number;
+            };
+            width: number;
+            height: number;
+            depth: number;
+        };
     };
 }
 export interface ClipItem {
@@ -83,7 +119,32 @@ export interface TurnItem {
     y: number;
     items: DisplayItem[];
 }
-export type DisplayItem = GlyphRun | RectItem | LineItem | ImageItem | PathItem | ClipItem | TurnItem;
+/** A floating object's geometry (#552): SVG path data in page coordinates, filled, stroked or both. */
+export interface ShapeItem {
+    kind: 'shape';
+    path: string;
+    d: string;
+    fill?: string | {
+        width: number;
+        height: number;
+        foreground: string;
+        background: string;
+        rects: [number, number, number, number][];
+    };
+    /** Centred on the path; `dash` lengths in points, absent for a solid line. */
+    stroke?: {
+        width: number;
+        color: string;
+        dash?: number[];
+    };
+}
+/** Items mapped by `matrix` [a, b, c, d, e, f] (SVG `matrix`): a floating object's rotation and flips (#552). */
+export interface TransformItem {
+    kind: 'transform';
+    matrix: [number, number, number, number, number, number];
+    items: DisplayItem[];
+}
+export type DisplayItem = GlyphRun | RectItem | LineItem | ImageItem | PathItem | ShapeItem | ClipItem | TurnItem | TransformItem;
 export interface LineGlyph {
     x: number;
     /** UTF-16 offset within the line's text. */
@@ -105,7 +166,8 @@ export interface TextLine {
     /** UTF-16 offset of the line start in its story's text. */
     offset: number;
     text: string;
-    glyphs: LineGlyph[];
+    /** Read-only in opened previews; indexed glyph objects are snapshots. */
+    glyphs: readonly LineGlyph[];
     turn?: [number, number];
 }
 export interface DisplayPage {

package/dist/core/engine.d.ts

@@ -3,11 +3,7 @@ import type { Endpoint } from './protocol.js';
 export interface ServeOptions {
     /** The wasm module bytes or address; defaults to the file next to the glue. */
     wasm?: BufferSource | URL | string;
-    /**
-     * Measures characters that no metric profile or stand-in font has. Defaults
-     * to OffscreenCanvas `measureText` along the painter's font chain; `null`
-     * (or no OffscreenCanvas) leaves them estimated and drawn as boxes.
-     */
+    /** Browser font metrics; defaults to OffscreenCanvas. null disables measurement and causes open to fail. */
     measure?: Measure | null;
 }
 export declare function serve(endpoint: Endpoint, options?: ServeOptions): void;

package/dist/core/engine.js

@@ -3,15 +3,13 @@
 // code behind a MessageChannel. Layout is synchronous inside one wasm call;
 // resources the host has not answered yet come back as `needs`, and the open
 // is retried once they arrive.
-import init, { openDocument } from '../../wasm/idocs_wasm.js';
+import init, { exportDocx, openDocument } from '../../wasm/idocs_wasm.js';
 import { canvasMeasure } from './fonts.js';
 export function serve(endpoint, options = {}) {
     let ready;
     const start = (wasm = options.wasm) => (ready ??= init(wasm === undefined ? undefined : { module_or_path: wasm }));
-    // Stand-in fonts do not depend on the document, so answers outlive an open.
-    const fonts = new Map();
-    const pending = new Map();
     const measure = options.measure === undefined ? canvasMeasure() : (options.measure ?? undefined);
+    const pending = new Map();
     const post = (message, transfer = []) => endpoint.postMessage(message, transfer);
     const attempt = (id) => {
         const job = pending.get(id);
@@ -19,7 +17,19 @@ export function serve(endpoint, options = {}) {
             return;
         let outcome;
         try {
-            outcome = openDocument(job.kind, job.bytes, job.name, job.assets, fonts, measure);
+            if (!measure)
+                throw new Error('Browser font measurement requires OffscreenCanvas 2D');
+            if (job.type === 'exportDocx') {
+                outcome = exportDocx(job.bytes, job.name, job.assets, measure);
+            }
+            else {
+                if (job.progressive)
+                    post({ type: 'pageReset', id });
+                const onPage = job.progressive ? (packet) => {
+                    post({ type: 'page', id, ...packet }, [packet.data.buffer, ...packet.images.map(bytes => bytes.buffer)]);
+                } : undefined;
+                outcome = openDocument(job.kind, job.bytes, job.name, job.assets, measure, onPage);
+            }
         }
         catch (error) {
             pending.delete(id);
@@ -35,12 +45,11 @@ export function serve(endpoint, options = {}) {
             post({ type: 'failed', id, error: JSON.parse(outcome.json) });
             return;
         }
-        const parsed = JSON.parse(outcome.json);
-        const document = {
-            ...parsed,
-            images: parsed.images.map((image, i) => ({ ...image, bytes: outcome.images[i] })),
-        };
-        post({ type: 'opened', id, document }, outcome.images.map((bytes) => bytes.buffer));
+        if (outcome.status === 'exported') {
+            post({ type: 'exported', id, bytes: outcome.bytes }, [outcome.bytes.buffer]);
+            return;
+        }
+        post({ type: 'opened', id, json: outcome.json, images: outcome.images, data: outcome.data }, [outcome.data.buffer, ...outcome.images.map((bytes) => bytes.buffer)]);
     };
     endpoint.addEventListener('message', async (event) => {
         const message = event.data;
@@ -58,9 +67,14 @@ export function serve(endpoint, options = {}) {
             post({ type: 'failed', id, error: { code: 'wasm-unavailable', message: String(error), diagnostics: [] } });
             return;
         }
-        if (message.type === 'open') {
+        if (message.type === 'exportDocx') {
+            pending.set(message.id, { type: 'exportDocx', name: message.name, bytes: message.bytes, assets: new Map() });
+        }
+        else if (message.type === 'open') {
             pending.set(message.id, {
+                type: 'open',
                 kind: message.kind,
+                progressive: message.progressive ?? false,
                 name: message.name,
                 bytes: message.bytes,
                 assets: new Map(),
@@ -71,8 +85,7 @@ export function serve(endpoint, options = {}) {
             if (!job)
                 return;
             for (const { need, bytes } of message.answers) {
-                ;
-                (need.kind === 'font' ? fonts : job.assets).set(need.name, bytes);
+                job.assets.set(need.name, bytes);
             }
         }
         attempt(message.id);

package/dist/core/fonts.d.ts

@@ -1,10 +1,11 @@
 import type { GlyphRun } from './display.js';
+export declare const CANVAS_TEXT_LANGUAGE = "und";
 export type FontChainInput = Pick<GlyphRun, 'family' | 'declaredFamily' | 'role'>;
 /**
  * The CSS font families to draw `run` with, most preferred first; the last is
  * always a generic family. When layout measured the declared family itself,
  * it leads, then the look-alikes of the Word family it names. When the
- * declared family has no metric profile, layout measured a fallback face:
+ * selected family differs from the declared family, layout measured a fallback face:
  * that face and its look-alikes lead, so glyphs are drawn as wide as they
  * were placed, and the declared family only covers characters they lack.
  */
@@ -15,14 +16,12 @@ export type CanvasFontInput = FontChainInput & Pick<GlyphRun, 'size' | 'bold' |
  * one point: the run's size in points, its weight and slant, then the chain.
  */
 export declare function canvasFont(run: CanvasFontInput): string;
-/**
- * `measure(family, declaredFamily, bold, italic, text)`: the advance of
- * `text` in em with the host's own fonts. Core asks only for characters that
- * neither the metric profile nor a stand-in font has.
- */
-export type Measure = (family: string, declaredFamily: string, bold: boolean, italic: boolean, text: string) => number;
-/**
- * A synchronous measurer on an OffscreenCanvas, with the same font chain the
- * painter draws with; undefined where there is no OffscreenCanvas (Node).
- */
+/** Measurements use the same CSS chain and kerning policy as the Canvas painter. */
+export interface FontMeasurement {
+    width: number;
+    ascent: number;
+    descent: number;
+}
+export type Measure = (family: string, declaredFamily: string, bold: boolean, italic: boolean, text: string, kern?: boolean) => number | FontMeasurement;
+/** Browser-local fonts only: this neither fetches files nor requests Local Font Access. */
 export declare function canvasMeasure(): Measure | undefined;

package/dist/core/fonts.js

@@ -1,11 +1,13 @@
+export const CANVAS_TEXT_LANGUAGE = 'und';
 const GENERIC = new Set(['serif', 'sans-serif', 'monospace']);
 /**
  * Word family → its look-alikes on Windows, macOS and Linux, ending in a
- * generic family. Covers the default theme and every calibrated family
- * (assets/font-metrics), plus the uncalibrated Word families the resolver
- * knows (rust/idocs-core/src/fonts/resolver.rs `word_family`).
+ * generic family. Covers the default theme and common Word families.
  */
 const SIMILAR = {
+    MiSans: ['MiSans', 'Microsoft YaHei', 'PingFang SC', 'Noto Sans CJK SC', 'sans-serif'],
+    'Noto Sans CJK SC': ['Noto Sans CJK SC', 'Microsoft YaHei', 'PingFang SC', 'sans-serif'],
+    'Noto Serif CJK SC': ['Noto Serif CJK SC', 'SimSun', 'Songti SC', 'serif'],
     // Simplified Chinese
     SimSun: ['SimSun', 'Songti SC', 'Noto Serif CJK SC', 'serif'],
     SimHei: ['SimHei', 'Heiti SC', 'STHeiti', 'Noto Sans CJK SC', 'sans-serif'],
@@ -17,6 +19,8 @@ const SIMILAR = {
     PMingLiU: ['PMingLiU', 'Songti TC', 'Noto Serif CJK TC', 'serif'],
     MingLiU: ['MingLiU', 'Songti TC', 'Noto Serif CJK TC', 'serif'],
     'Microsoft JhengHei': ['Microsoft JhengHei', 'PingFang TC', 'Noto Sans CJK TC', 'sans-serif'],
+    // Japanese
+    'MS Gothic': ['MS Gothic', 'Hiragino Kaku Gothic ProN', 'Noto Sans CJK JP', 'Noto Sans CJK SC', 'sans-serif'],
     // Latin
     'Times New Roman': ['Times New Roman', 'Times', 'Liberation Serif', 'Tinos', 'serif'],
     Arial: ['Arial', 'Helvetica', 'Liberation Sans', 'Arimo', 'sans-serif'],
@@ -39,6 +43,7 @@ const ALIASES = {
     新細明體: 'PMingLiU',
     微軟正黑體: 'Microsoft JhengHei',
     細明體: 'MingLiU',
+    'ＭＳ ゴシック': 'MS Gothic',
 };
 const BY_LOWER = new Map(Object.keys(SIMILAR).map((name) => [name.toLowerCase(), name]));
 /** The Word family a declared name stands for, matched as Word does (case-insensitive). */
@@ -56,7 +61,7 @@ function roleGeneric(role) {
  * The CSS font families to draw `run` with, most preferred first; the last is
  * always a generic family. When layout measured the declared family itself,
  * it leads, then the look-alikes of the Word family it names. When the
- * declared family has no metric profile, layout measured a fallback face:
+ * selected family differs from the declared family, layout measured a fallback face:
  * that face and its look-alikes lead, so glyphs are drawn as wide as they
  * were placed, and the declared family only covers characters they lack.
  */
@@ -101,21 +106,30 @@ export function canvasFont(run) {
     }
     return font;
 }
-/** Measuring size in px: large enough that rounding inside measureText does not show. */
-const MEASURE_SIZE = 100;
-/**
- * A synchronous measurer on an OffscreenCanvas, with the same font chain the
- * painter draws with; undefined where there is no OffscreenCanvas (Node).
- */
+// Canvas rounds font box extents to pixels; retain sub-point precision
+// when raised text sits near a line-grid boundary.
+const MEASURE_SIZE = 1000;
+/** Browser-local fonts only: this neither fetches files nor requests Local Font Access. */
 export function canvasMeasure() {
     if (typeof OffscreenCanvas === 'undefined')
         return undefined;
     const ctx = new OffscreenCanvas(1, 1).getContext('2d');
     if (!ctx)
         return undefined;
-    return (family, declaredFamily, bold, italic, text) => {
-        // The role is not known here; a family outside the table falls to serif.
-        ctx.font = canvasFont({ family, declaredFamily, role: '', size: MEASURE_SIZE, bold, italic });
-        return ctx.measureText(text).width / MEASURE_SIZE;
+    Object.assign(ctx, { lang: CANVAS_TEXT_LANGUAGE });
+    const cache = new Map();
+    return (family, declaredFamily, bold, italic, text, kern = false) => {
+        const role = family === 'sans-serif' ? 'sans' : family === 'monospace' ? 'mono' : 'serif';
+        const font = canvasFont({ family, declaredFamily, role, size: MEASURE_SIZE, bold, italic });
+        const key = `${font}\0${kern}\0${text}`;
+        const known = cache.get(key);
+        if (known)
+            return known;
+        ctx.font = font;
+        ctx.fontKerning = kern ? 'normal' : 'none';
+        const m = ctx.measureText(text);
+        const result = { width: m.width / MEASURE_SIZE, ascent: (m.fontBoundingBoxAscent ?? m.actualBoundingBoxAscent) / MEASURE_SIZE, descent: (m.fontBoundingBoxDescent ?? m.actualBoundingBoxDescent) / MEASURE_SIZE };
+        cache.set(key, result);
+        return result;
     };
 }

package/dist/core/index.d.ts

@@ -1,4 +1,4 @@
-import type { DocumentKind, Endpoint, PreviewDocument } from './protocol.js';
+import type { DocumentKind, Endpoint, PreviewDocument, PreviewPage } from './protocol.js';
 export type * from './display.js';
 export type * from './protocol.js';
 export interface SessionOptions {
@@ -8,17 +8,12 @@ export interface SessionOptions {
     wasmUrl?: string | URL;
     /** An already created worker (a MessagePort works too); `workerUrl` is then ignored. */
     worker?: Endpoint;
-    /**
-     * Reads a stand-in font by basename (e.g. `LiberationSerif-Regular.ttf`).
-     * Layout uses stand-in metrics for characters the embedded profiles lack;
-     * without them those characters fall back, as the CLI does with no font
-     * directory. Fonts belong to the session: each file is read at most once.
-     */
-    readFont?: Read;
 }
 type Bytes = Uint8Array | ArrayBuffer;
 export type Read = (name: string) => Bytes | null | undefined | Promise<Bytes | null | undefined>;
 export interface OpenOptions {
+    /** Receive provisional pages while the worker builds the remaining display list. */
+    onPage?: (page: PreviewPage) => void;
     /** File name used in diagnostics. */
     name?: string;
     /**
@@ -39,7 +34,9 @@ export declare class PreviewError extends Error {
         diagnostics: PreviewDocument['diagnostics'];
     });
 }
+export type ExportOptions = Pick<OpenOptions, 'name' | 'readResource'>;
 export interface Session {
+    exportDocx(bytes: Bytes, options?: ExportOptions): Promise<Uint8Array>;
     open(bytes: Bytes, options?: OpenOptions): Promise<PreviewDocument>;
     /**
      * Terminates the worker; pending opens reject. A worker that fails on its