@aseity/idocs-preview 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @aseity/idocs-preview
+
+## 0.1.0
+
+### Minor Changes
+
+- First public release of the read-only browser preview for DOCX and iDocs source
+  documents.
+
+  - `@aseity/idocs-preview/core`: a headless session that converts and lays out documents
+    with Word-calibrated metrics in a Web Worker and returns each page's display list,
+    diagnostics and conversion losses.
+  - `@aseity/idocs-preview/view`: a Canvas page view with virtualized pages, text
+    selection and copying, a find bar, zoom with fit-width support, Ctrl+wheel and
+    pinch zoom around the pointer, and page navigation with optional smooth
+    scrolling.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iDocs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# iDocs preview
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+The package ships ES modules, TypeScript declarations, the worker and the WASM
+binary. It has no framework dependency and runs only in browsers.
+
+```sh
+npm install @aseity/idocs-preview
+```
+
+## Quick start
+
+```ts
+const { createPreview } = await import("@aseity/idocs-preview/view");
+
+const preview = createPreview(container, {
+  onPageChange: (index, doc) => console.log(`page ${index + 1} of ${doc.pageCount}`),
+  onZoomChange: (zoom) => console.log(`zoomed to ${Math.round(zoom * 100)}%`),
+});
+const doc = await preview.open(bytes, { name: "report.docx" });
+preview.setZoom(preview.view?.fitWidthZoom ?? 1);
+preview.goToPage(2, { behavior: "smooth" });
+preview.destroy();
+```
+
+`container` must have a height; the view fills it and scrolls inside it. Load the
+package lazily on the client (a dynamic `import()` or a client-only component), not
+during server rendering.
+
+## Subpaths
+
+- `@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.
+- `@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.
+
+## Opening documents
+
+`open(bytes, { name?, kind?, readResource? })` takes a `Uint8Array` or
+`ArrayBuffer`. The package copies the bytes before transferring them to the worker,
+so the caller can keep using them, for example to download the original.
+
+- `kind` defaults to `docx` for ZIP or OLE bytes or a Word file name, and to `idoc`
+  otherwise.
+- `readResource(path)` resolves images referenced by an `.idoc` file, relative to
+  that file. DOCX images are read from the file itself.
+- A failed open rejects with `PreviewError`, whose `code` is one of
+  `invalid-source`, `layout-failed`, `unsupported-format`, `wasm-unavailable`,
+  `worker-unavailable`, `internal-error`, or a DOCX conversion code
+  (`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`.
+
+## View
+
+- Zoom 1 is 100% (one point is 4/3 CSS pixels), clamped to 0.1–10. `setZoom` keeps
+  the spot at the top of the viewport in place. `view.fitWidthZoom` is the zoom at
+  which the widest page fills the viewport width; the view does not refit by
+  itself.
+- Ctrl+wheel and trackpad pinch zoom around the pointer and report the new zoom
+  through `onZoomChange`. `setZoom` does not call it.
+- `goToPage(index, { behavior })` scrolls a page (0-based) to the top. Pass
+  `"smooth"` to animate, and `"instant"` when the reader prefers reduced motion.
+- Pages are virtualized: only the visible pages and one on either side keep a
+  canvas.
+- Text can be selected and copied. Ctrl+F (Cmd+F on macOS) opens the built-in
+  find bar while the preview has focus. Escape that closes the find bar is marked
+  with `preventDefault()`, so hosts that close their panel on Escape should skip
+  events whose `defaultPrevented` is set.
+
+## Bundlers and hosting
+
+The session creates its worker with `new Worker(new URL("./worker.js",
+import.meta.url), { type: "module" })`, and the WASM glue loads
+`new URL("idocs_wasm_bg.wasm", import.meta.url)`. Vite, webpack and Turbopack
+(Next.js 16) recognize both forms and emit the worker chunk and the WASM asset
+without configuration.
+
+Without a bundler, host the package files at their relative positions and pass the
+addresses: `createPreview(el, { session: { workerUrl, wasmUrl } })`, where
+`workerUrl` points to `dist/core/worker.js` and `wasmUrl` to
+`wasm/idocs_wasm_bg.wasm`.
+
+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.
+
+## License
+
+MIT

package/dist/core/display.d.ts

@@ -0,0 +1,118 @@
+export type Story = 'body' | 'header' | 'footer' | 'footnotes';
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Glyph {
+    /** Left edge from the metric profile. */
+    x: number;
+    /** Width occupied in the line, including added spacing. */
+    width: number;
+    text: string;
+    /** UTF-16 offset of the source character within its run's text. */
+    offset: number;
+    /**
+     * No metric profile, stand-in font or local font measured this character:
+     * its width is an estimate, and the painter draws a placeholder box.
+     */
+    unmeasured?: true;
+}
+export interface GlyphRun {
+    kind: 'glyphs';
+    /** `leader` for tab leader characters, which are not part of the line text. */
+    runKind: 'text' | 'leader';
+    story: Story;
+    path: string;
+    role: string;
+    family: string;
+    declaredFamily: string;
+    size: number;
+    bold: boolean;
+    italic: boolean;
+    color: string;
+    baseline: number;
+    lineTop: number;
+    lineHeight: number;
+    glyphs: Glyph[];
+}
+export type RectRole = 'areaFill' | 'border' | 'shading' | 'characterBorder' | 'underline' | 'strike' | 'footnoteSeparator' | 'mathRule';
+export interface RectItem extends Rect {
+    kind: 'rect';
+    role: RectRole;
+    color: string;
+}
+export interface LineItem {
+    kind: 'line';
+    role: 'diagonal';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    width: number;
+    color: string;
+}
+export interface ImageItem extends Rect {
+    kind: 'image';
+    /** Index into PreviewDocument.images. */
+    image: number;
+    path: string;
+}
+export interface PathItem {
+    kind: 'path';
+    role: 'mathGlyph' | 'mathPath';
+    d: string;
+    transform: [number, number, number, number, number, number];
+    color: string;
+    clip?: Rect;
+    glyph?: {
+        file: string;
+        char: string;
+        size: number;
+    };
+}
+export interface ClipItem {
+    kind: 'clip';
+    rect: Rect;
+    items: DisplayItem[];
+}
+export interface TurnItem {
+    kind: 'turn';
+    x: number;
+    y: number;
+    items: DisplayItem[];
+}
+export type DisplayItem = GlyphRun | RectItem | LineItem | ImageItem | PathItem | ClipItem | TurnItem;
+export interface LineGlyph {
+    x: number;
+    /** UTF-16 offset within the line's text. */
+    offset: number;
+}
+/** One laid-out line's glyph table, for hit testing. */
+export interface TextLine {
+    story: Story;
+    path: string;
+    index: number;
+    x: number;
+    width: number;
+    top: number;
+    height: number;
+    baseline: number;
+    /** Extent of the text above and below `baseline` (the line box less its leading). */
+    ascent: number;
+    descent: number;
+    /** UTF-16 offset of the line start in its story's text. */
+    offset: number;
+    text: string;
+    glyphs: LineGlyph[];
+    turn?: [number, number];
+}
+export interface DisplayPage {
+    number: number;
+    label?: string;
+    width: number;
+    height: number;
+    items: DisplayItem[];
+    lines: TextLine[];
+}

package/dist/core/display.js

@@ -0,0 +1,4 @@
+// Display list types (#442). The Rust definitions in
+// rust/idocs-core/src/display/mod.rs are authoritative; coordinates are points,
+// origin at the page's top-left corner, y down. Item order is drawing order.
+export {};

package/dist/core/engine.d.ts

@@ -0,0 +1,13 @@
+import { type Measure } from './fonts.js';
+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.
+     */
+    measure?: Measure | null;
+}
+export declare function serve(endpoint: Endpoint, options?: ServeOptions): void;

package/dist/core/engine.js

@@ -0,0 +1,81 @@
+// The Worker side: owns the wasm instance and answers the protocol in
+// protocol.ts. `serve` takes any message endpoint, so Node tests run the same
+// 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 { 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 post = (message, transfer = []) => endpoint.postMessage(message, transfer);
+    const attempt = (id) => {
+        const job = pending.get(id);
+        if (!job)
+            return;
+        let outcome;
+        try {
+            outcome = openDocument(job.kind, job.bytes, job.name, job.assets, fonts, measure);
+        }
+        catch (error) {
+            pending.delete(id);
+            post({ type: 'failed', id, error: { code: 'internal-error', message: String(error), diagnostics: [] } });
+            return;
+        }
+        if (outcome.status === 'needs') {
+            post({ type: 'needs', id, needs: JSON.parse(outcome.json) });
+            return;
+        }
+        pending.delete(id);
+        if (outcome.status === 'failed') {
+            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));
+    };
+    endpoint.addEventListener('message', async (event) => {
+        const message = event.data;
+        if (message.type === 'init') {
+            // Start fetching early; a failure is reported to the first open.
+            start(message.wasmUrl).catch(() => { });
+            return;
+        }
+        try {
+            await start();
+        }
+        catch (error) {
+            const id = 'id' in message ? message.id : -1;
+            pending.delete(id);
+            post({ type: 'failed', id, error: { code: 'wasm-unavailable', message: String(error), diagnostics: [] } });
+            return;
+        }
+        if (message.type === 'open') {
+            pending.set(message.id, {
+                kind: message.kind,
+                name: message.name,
+                bytes: message.bytes,
+                assets: new Map(),
+            });
+        }
+        else if (message.type === 'resources') {
+            const job = pending.get(message.id);
+            if (!job)
+                return;
+            for (const { need, bytes } of message.answers) {
+                ;
+                (need.kind === 'font' ? fonts : job.assets).set(need.name, bytes);
+            }
+        }
+        attempt(message.id);
+    });
+    endpoint.start?.();
+}

package/dist/core/fonts.d.ts

@@ -0,0 +1,28 @@
+import type { GlyphRun } from './display.js';
+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:
+ * 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.
+ */
+export declare function fontChain(run: FontChainInput): string[];
+export type CanvasFontInput = FontChainInput & Pick<GlyphRun, 'size' | 'bold' | 'italic'>;
+/**
+ * The `CanvasRenderingContext2D.font` for `run`, in a context whose unit is
+ * 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).
+ */
+export declare function canvasMeasure(): Measure | undefined;

package/dist/core/fonts.js

@@ -0,0 +1,121 @@
+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`).
+ */
+const SIMILAR = {
+    // Simplified Chinese
+    SimSun: ['SimSun', 'Songti SC', 'Noto Serif CJK SC', 'serif'],
+    SimHei: ['SimHei', 'Heiti SC', 'STHeiti', 'Noto Sans CJK SC', 'sans-serif'],
+    'Microsoft YaHei': ['Microsoft YaHei', 'PingFang SC', 'Noto Sans CJK SC', 'sans-serif'],
+    DengXian: ['DengXian', 'PingFang SC', 'Noto Sans CJK SC', 'sans-serif'],
+    FangSong: ['FangSong', 'STFangsong', 'FandolFang', 'Noto Serif CJK SC', 'serif'],
+    KaiTi: ['KaiTi', 'Kaiti SC', 'STKaiti', 'AR PL UKai CN', 'FandolKai', 'Noto Serif CJK SC', 'serif'],
+    // Traditional Chinese
+    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'],
+    // Latin
+    'Times New Roman': ['Times New Roman', 'Times', 'Liberation Serif', 'Tinos', 'serif'],
+    Arial: ['Arial', 'Helvetica', 'Liberation Sans', 'Arimo', 'sans-serif'],
+    Calibri: ['Calibri', 'Carlito', 'sans-serif'],
+    Consolas: ['Consolas', 'Menlo', 'Inconsolata', 'Liberation Mono', 'monospace'],
+    'Courier New': ['Courier New', 'Courier', 'Liberation Mono', 'Cousine', 'monospace'],
+    Cambria: ['Cambria', 'Caladea', 'serif'],
+    'Cambria Math': ['Cambria Math', 'STIX Two Math', 'serif'],
+    Aptos: ['Aptos', 'sans-serif'],
+    'Segoe UI': ['Segoe UI', 'Helvetica Neue', 'Noto Sans', 'sans-serif'],
+};
+/** Chinese names Word documents use for the families above. */
+const ALIASES = {
+    微软雅黑: 'Microsoft YaHei',
+    等线: 'DengXian',
+    宋体: 'SimSun',
+    黑体: 'SimHei',
+    仿宋: 'FangSong',
+    楷体: 'KaiTi',
+    新細明體: 'PMingLiU',
+    微軟正黑體: 'Microsoft JhengHei',
+    細明體: 'MingLiU',
+};
+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). */
+function wordFamily(name) {
+    return BY_LOWER.get((ALIASES[name] ?? name).toLowerCase());
+}
+function roleGeneric(role) {
+    if (role === 'mono')
+        return 'monospace';
+    if (role === 'sans')
+        return 'sans-serif';
+    return 'serif';
+}
+/**
+ * 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:
+ * 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.
+ */
+export function fontChain(run) {
+    const names = [];
+    let generic;
+    const add = (name) => {
+        if (GENERIC.has(name))
+            generic ??= name;
+        else if (!names.some((known) => known.toLowerCase() === name.toLowerCase()))
+            names.push(name);
+    };
+    const addSimilar = (family) => {
+        const word = wordFamily(family);
+        if (word)
+            for (const name of SIMILAR[word])
+                add(name);
+    };
+    const measured = (wordFamily(run.declaredFamily) ?? run.declaredFamily).toLowerCase() === run.family.toLowerCase();
+    if (!measured)
+        addSimilar(run.family);
+    add(run.declaredFamily);
+    addSimilar(run.declaredFamily);
+    if (measured)
+        addSimilar(run.family);
+    return [...names, generic ?? roleGeneric(run.role)];
+}
+const fonts = new Map();
+/**
+ * The `CanvasRenderingContext2D.font` for `run`, in a context whose unit is
+ * one point: the run's size in points, its weight and slant, then the chain.
+ */
+export function canvasFont(run) {
+    const key = `${run.italic}\0${run.bold}\0${run.size}\0${run.role}\0${run.declaredFamily}\0${run.family}`;
+    let font = fonts.get(key);
+    if (font === undefined) {
+        const chain = fontChain(run)
+            .map((name) => (GENERIC.has(name) ? name : `"${name.replaceAll('"', '')}"`))
+            .join(', ');
+        font = `${run.italic ? 'italic ' : ''}${run.bold ? 'bold ' : ''}${run.size}px ${chain}`;
+        fonts.set(key, font);
+    }
+    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).
+ */
+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;
+    };
+}

package/dist/core/index.d.ts

@@ -0,0 +1,52 @@
+import type { DocumentKind, Endpoint, PreviewDocument } from './protocol.js';
+export type * from './display.js';
+export type * from './protocol.js';
+export interface SessionOptions {
+    /** Worker script address; defaults to the bundled worker beside this module. */
+    workerUrl?: string | URL;
+    /** `.wasm` address; defaults to the file next to the wasm glue. */
+    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 {
+    /** File name used in diagnostics. */
+    name?: string;
+    /**
+     * Defaults to `docx` for zip or OLE compound-file bytes (an encrypted DOCX
+     * or a .doc, rejected with their own code) and for a Word file name
+     * (`.docx`, `.docm`, `.dotx`, `.dotm`, `.doc`); `idoc` otherwise.
+     */
+    kind?: DocumentKind;
+    /** Reads a path relative to the source document (images). Throw or return null when absent. */
+    readResource?: Read;
+}
+export declare class PreviewError extends Error {
+    code: string;
+    diagnostics: PreviewDocument['diagnostics'];
+    constructor(error: {
+        code: string;
+        message: string;
+        diagnostics: PreviewDocument['diagnostics'];
+    });
+}
+export interface Session {
+    open(bytes: Bytes, options?: OpenOptions): Promise<PreviewDocument>;
+    /**
+     * Terminates the worker; pending opens reject. A worker that fails on its
+     * own (script not loaded, message not deserialized) rejects pending and later
+     * opens with `worker-unavailable`; create a new session to retry.
+     */
+    dispose(): void;
+}
+export declare function createSession(options?: SessionOptions): Session;
+export type { Measure } from './fonts.js';