web-doc 0.6.2 → 0.8.0

package/dist/adapters/office.js

@@ -1,5 +1,8 @@
 import { abortError, ViewerError } from "../errors.js";
-import { fitInlineImagesToPage } from "./docx-images.js";
+import { DocxSession } from "../edit/docx/session.js";
+import { PptxSession } from "../edit/pptx/session.js";
+import { createDocxParagraphIdResolver, } from "./docx-paragraphs.js";
+import { prepareDocxForDisplay } from "./docx-prepass.js";
 import { enforceContainerLimits } from "../limits.js";
 const MODERN_FORMATS = [
     "docx",
@@ -17,12 +20,38 @@ const ROW_HEADER_WIDTH = 50;
 const COLUMN_HEADER_HEIGHT = 22;
 export class OfficeDocumentAdapter {
     id = "office";
+    /**
+     * PPTX and DOCX editing on the OOXML package layer. The worker and the
+     * engine client are imported on the first `edit()`; viewing never loads
+     * them.
+     */
+    edit = {
+        formats: ["pptx", "pptm", "ppsx", "docx", "docm"],
+        load: async (original, context) => context.format === "docx"
+            ? (await import("../edit/docx/provider.js")).loadDocxEditEngine(original, context, this.#options.edit ?? {})
+            : (await import("../edit/pptx/provider.js")).loadPptxEditEngine(original, context, this.#options.edit ?? {}),
+        createSession: (core, access) => core.format === "docx"
+            ? new DocxSession(core, access)
+            : new PptxSession(core),
+    };
     formats = [...MODERN_FORMATS, ...LEGACY_FORMATS];
     #options;
     constructor(options = {}) {
         this.#options = options;
     }
     async open(input, context) {
+        return this.#open(input, context, false);
+    }
+    /**
+     * Edited bytes open as a fresh document (the engine owns no reusable
+     * state); a presentation lays its slides out progressively so the slide
+     * on screen paints without waiting for the whole deck — Firefox takes
+     * seconds for a 500-slide preflight. The viewer closes `previous`.
+     */
+    reopen(_previous, data, context) {
+        return this.#open(data, context, true);
+    }
+    async #open(input, context, reopening) {
         throwIfAborted(context.signal);
         let format = context.format;
         let data = input;
@@ -57,12 +86,16 @@ export class OfficeDocumentAdapter {
             useGoogleFonts: false,
             maxZipEntryBytes: context.limits.maxZipEntryBytes,
             mode: "main",
+            ...(reopening ? { progressiveLayout: true } : {}),
         };
-        const buffer = exactArrayBuffer(data);
         try {
             const kind = kindFor(format);
             if (kind === "document") {
-                const backend = await this.#loadDocx(buffer, engineOptions);
+                // What the renderer sees: oversized inline pictures fitted and every
+                // paragraph carrying an id; the bytes a session saves are the input.
+                const display = await prepareDocxForDisplay(data, context.limits, context.signal);
+                throwIfAborted(context.signal);
+                const backend = await this.#loadDocx(exactArrayBuffer(display.bytes), engineOptions);
                 throwIfAborted(context.signal, backend);
                 context.reportProgress({
                     phase: "parsing",
@@ -70,8 +103,15 @@ export class OfficeDocumentAdapter {
                     total: 1,
                     ratio: 1,
                 });
-                return { kind, format: context.format, backend, warnings };
+                return {
+                    kind,
+                    format: context.format,
+                    backend,
+                    warnings,
+                    paragraphIdOf: createDocxParagraphIdResolver(docxModelOf(backend)),
+                };
             }
+            const buffer = exactArrayBuffer(data);
             if (kind === "presentation") {
                 const backend = await this.#loadPptx(buffer, engineOptions);
                 throwIfAborted(context.signal, backend);
@@ -232,6 +272,7 @@ export class OfficeDocumentAdapter {
             return runs.map((run) => {
                 const logicalStart = logicalOffset;
                 logicalOffset += run.text.length;
+                const paragraphId = run.paragraphId ?? handle.paragraphIdOf(run.source);
                 return {
                     text: run.text,
                     x: run.x,
@@ -240,6 +281,7 @@ export class OfficeDocumentAdapter {
                     height: run.h,
                     font: run.font,
                     fontSize: run.fontSize,
+                    ...(paragraphId === undefined ? {} : { paragraphId }),
                     ...(run.letterSpacingPx === undefined
                         ? {}
                         : { letterSpacingPx: run.letterSpacingPx }),
@@ -326,11 +368,10 @@ export class OfficeDocumentAdapter {
         return convertInWorker(data, format, workerUrl, moduleUrl, context.signal, context.limits.maxOperationMs);
     }
     async #loadDocx(data, options) {
-        const backend = this.#options.engines?.docx
-            ? await this.#options.engines.docx(data, options)
-            : await (await import("@silurus/ooxml/docx")).DocxDocument.load(data, options);
-        fitDocxInlineImages(backend);
-        return backend;
+        if (this.#options.engines?.docx)
+            return this.#options.engines.docx(data, options);
+        const { DocxDocument } = await import("@silurus/ooxml/docx");
+        return DocxDocument.load(data, options);
     }
     async #loadXlsx(data, options) {
         if (this.#options.engines?.xlsx)
@@ -341,13 +382,22 @@ export class OfficeDocumentAdapter {
     async #loadPptx(data, options) {
         if (this.#options.engines?.pptx)
             return this.#options.engines.pptx(data, options);
-        const { PptxPresentation } = await import("@silurus/ooxml-pptx/pptx");
+        const { PptxPresentation } = await import("@silurus/ooxml/pptx");
         return PptxPresentation.load(data, options);
     }
 }
 export function createOfficeAdapter(options = {}) {
     return new OfficeDocumentAdapter(options);
 }
+/** The engine's model when it is reachable; a worker-mode getter throws. */
+function docxModelOf(backend) {
+    try {
+        return backend.document;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function sanitizeOfficeHyperlink(target) {
     if (!target)
         return undefined;
@@ -672,22 +722,3 @@ function normalizeOfficeError(error) {
 function textDirection(text) {
     return /[\u0590-\u08ff\ufb1d-\ufefc]/u.test(text) ? "rtl" : "ltr";
 }
-/**
- * Oversized inline pictures are shrunk to the section's content box before
- * the engine paginates (the layout is built lazily on first page access).
- * The model is reachable in `main` mode only; a worker-mode engine keeps
- * Word's geometry.
- */
-function fitDocxInlineImages(backend) {
-    if (backend.mode === "worker")
-        return;
-    let model;
-    try {
-        model = backend.document;
-    }
-    catch {
-        return;
-    }
-    if (model)
-        fitInlineImagesToPage(model);
-}

package/dist/adapters/pdf.d.ts

@@ -1,4 +1,6 @@
 import type { AdapterOpenContext, DocumentAdapter, DocumentInfo, PageSize, RenderViewport, TextRun } from "../contracts.js";
+import type { EditEngineProvider } from "../edit/engine.js";
+import type { PdfEditProviderOptions } from "../edit/pdf/provider.js";
 export interface PdfBackend {
     readonly pageCount: number;
     pageSize?(pageIndex: number, signal?: AbortSignal): PageSize | Promise<PageSize>;
@@ -13,6 +15,8 @@ export interface PdfAdapterOptions {
     readonly wasmUrl?: string | URL;
     readonly iccUrl?: string | URL;
     readonly open?: (data: Uint8Array, context: AdapterOpenContext) => Promise<PdfBackend>;
+    /** Where the PDF edit worker and its WebAssembly live. */
+    readonly edit?: PdfEditProviderOptions;
 }
 interface PdfHandle {
     readonly backend: PdfBackend;
@@ -21,6 +25,11 @@ export declare class PdfDocumentAdapter implements DocumentAdapter<PdfHandle> {
     #private;
     readonly id = "pdf";
     readonly formats: readonly ["pdf"];
+    /**
+     * PDFium-backed editing. The worker, its WebAssembly and the engine client
+     * are imported on the first `edit()`; viewing never loads them.
+     */
+    readonly edit: EditEngineProvider;
     constructor(options?: PdfAdapterOptions);
     open(data: Uint8Array, context: AdapterOpenContext): Promise<PdfHandle>;
     getInfo(handle: PdfHandle): Promise<DocumentInfo>;

package/dist/adapters/pdf.js

@@ -1,4 +1,5 @@
 import { abortError, ViewerError } from "../errors.js";
+import { PdfSession } from "../edit/pdf/session.js";
 // Preserve the public zoom=1 contract: one PDF point maps to one renderer CSS
 // pixel. Per-page geometry still prevents the viewport from coercing pages to
 // A4 or changing their width while virtualizing.
@@ -7,6 +8,15 @@ export class PdfDocumentAdapter {
     id = "pdf";
     formats = ["pdf"];
     #options;
+    /**
+     * PDFium-backed editing. The worker, its WebAssembly and the engine client
+     * are imported on the first `edit()`; viewing never loads them.
+     */
+    edit = {
+        formats: ["pdf"],
+        load: async (original, context) => (await import("../edit/pdf/provider.js")).loadPdfEditEngine(original, context, this.#options.edit ?? {}),
+        createSession: (core) => new PdfSession(core),
+    };
     constructor(options = {}) {
         this.#options = options;
     }

package/dist/contracts.d.ts

@@ -1,11 +1,22 @@
+import type { EditEngineProvider } from "./edit/engine.js";
+import type { EditSession } from "./edit/sessions.js";
+import type { DocumentChange, LayoutChange, EditOptions, EditStateChange, PageHit, PageRect, ViewportRect } from "./edit/types.js";
 export declare const supportedFormats: readonly ["docx", "docm", "xlsx", "xlsm", "pptx", "pptm", "ppsx", "doc", "xls", "ppt", "pdf", "csv", "tsv", "png", "jpeg", "gif", "webp", "svg", "bmp", "tiff"];
 export type DocumentFormat = (typeof supportedFormats)[number];
 export type ViewerLocale = "en" | "ru";
 export type FitMode = "none" | "page" | "width";
 export type ViewerStatus = "idle" | "loading" | "ready" | "error" | "destroyed";
 export type RenderUnit = "page" | "slide" | "sheet" | "image";
-export type ViewerErrorCode = "unsupported-format" | "fidelity-unsupported" | "invalid-file" | "encrypted-document" | "resource-limit" | "network-error" | "aborted" | "font-unavailable" | "render-failed" | "worker-crashed" | "lifecycle-error" | "internal";
-export type ViewerWarningCode = "format-hint-mismatch" | "unsupported-feature" | "font-substitution" | "font-unavailable" | "external-resource-blocked" | "fidelity-degraded";
+export type ViewerErrorCode = "unsupported-format" | "fidelity-unsupported" | "invalid-file" | "encrypted-document" | "resource-limit" | "network-error" | "aborted" | "font-unavailable" | "render-failed" | "worker-crashed" | "lifecycle-error" | "edit-unsupported" | "invalid-operation" | "edit-conflict" | "edit-failed"
+/** An OOXML package the editing layer cannot open: ZIP64, encryption, an unknown method, several disks. */
+ | "unsupported-package"
+/** An OOXML part that can be read but not patched: not UTF-8, or not byte-stable through decoding. */
+ | "unsupported-part"
+/** An XML part the scanner cannot parse. */
+ | "malformed-xml"
+/** A patch that overlaps, is stale, is not well-formed, or does not read back as expected. */
+ | "invalid-patch" | "internal";
+export type ViewerWarningCode = "format-hint-mismatch" | "unsupported-feature" | "font-substitution" | "font-unavailable" | "external-resource-blocked" | "fidelity-degraded" | "privacy-not-guaranteed";
 export interface ViewerErrorData {
     readonly name: "ViewerError";
     readonly code: ViewerErrorCode;
@@ -34,6 +45,18 @@ export interface ResourceLimits {
     readonly maxDocumentUnits: number;
     readonly maxConcurrentRenders: number;
     readonly maxOperationMs: number;
+    /** Operations in one `EditSession.apply()` call. */
+    readonly maxEditOperations: number;
+    /** Undoable edit batches kept; older ones are folded into the starting point. */
+    readonly maxEditHistory: number;
+    /** Memory for retained edit checkpoints; fewer are kept when a file is big. */
+    readonly maxEditCheckpointBytes: number;
+    /** Nodes one `EditSession.getOutline()` returns; more is cut and reported. */
+    readonly maxOutlineNodes: number;
+    /** Upper bound of `describe()`'s character budget. */
+    readonly maxDescribeChars: number;
+    /** Named edit checkpoints alive at once in a session. */
+    readonly maxEditCheckpoints: number;
 }
 export type BinaryDocumentSource = ArrayBuffer | Uint8Array | Blob;
 export type DocumentSource = BinaryDocumentSource | URL | string;
@@ -164,6 +187,14 @@ export interface TextRun {
     readonly hyperlink?: HyperlinkTarget;
     readonly row?: number;
     readonly column?: number;
+    /**
+     * DOCX: the `w:p` of the source XML this run was laid out from, as the
+     * file's `w14:paraId` or the deterministic id the viewer assigns to a
+     * paragraph without one (eight hex digits). The runs of a paragraph that
+     * continues on the next page share it. Absent when the run belongs to no
+     * source paragraph.
+     */
+    readonly paragraphId?: string;
 }
 export type HyperlinkTarget = {
     readonly kind: "external";
@@ -216,6 +247,9 @@ export interface ViewerEventMap {
     };
     readonly viewchange: ViewerState;
     readonly searchchange: SearchResult | null;
+    readonly editstatechange: EditStateChange;
+    readonly documentchange: DocumentChange;
+    readonly layoutchange: LayoutChange;
 }
 /**
  * Tuning for the fuzzy fallback that runs when the exact search finds
@@ -389,6 +423,8 @@ export interface DocumentCapabilities {
     readonly cellSelection: boolean;
     readonly search: boolean;
     readonly thumbnails: boolean;
+    /** True when `edit()` is available for this document. */
+    readonly editing: boolean;
 }
 export type DocumentMetadata = DocumentInfo;
 export interface AdapterOpenContext {
@@ -410,6 +446,13 @@ export interface DocumentAdapter<THandle = unknown> {
     getTextMap?(handle: THandle, pageIndex: number, signal?: AbortSignal): Promise<readonly TextRun[]>;
     close(handle: THandle): void | Promise<void>;
     destroy?(): void | Promise<void>;
+    /** Editing support for some of this adapter's formats. */
+    readonly edit?: EditEngineProvider;
+    /**
+     * Opens edited bytes of a document, reusing what `previous` holds (for
+     * example a worker). `previous` stays open; the viewer closes it afterwards.
+     */
+    reopen?(previous: THandle, data: Uint8Array, context: AdapterOpenContext): Promise<THandle>;
 }
 export type ViewerEventListener<K extends keyof ViewerEventMap> = (event: ViewerEventMap[K]) => void;
 export interface ViewerApi {
@@ -445,6 +488,14 @@ export interface ViewerApi {
     copySelection(): Promise<string>;
     getOriginalBytes(): Uint8Array | undefined;
     downloadOriginal(fileName?: string): Blob;
+    /** Starts editing the loaded document, or returns the session already started. */
+    edit(options?: EditOptions): Promise<EditSession>;
+    /** The active session of the loaded document, if `edit()` was called. */
+    getEditSession(): EditSession | undefined;
+    /** Client-space rectangle of a page-space rectangle; undefined if the page is not mounted. */
+    pageToClient(pageIndex: number, rect: PageRect): ViewportRect | undefined;
+    /** Page under a client-space point and the point in page space; undefined outside pages. */
+    clientToPage(clientX: number, clientY: number): PageHit | undefined;
     on<K extends keyof ViewerEventMap>(type: K, listener: ViewerEventListener<K>): () => void;
     destroy(): Promise<void>;
 }

package/dist/edit/ai/outline.d.ts

@@ -0,0 +1,47 @@
+import type { ResourceLimits } from "../../contracts.js";
+import type { EditableFormat, EditElement, EditState, ElementQuery, ReadItem, ReadOptions, ReadResult } from "../types.js";
+import type { DescribeOptions, DocumentDescription, OutlineNode, OutlineOptions, OutlineResult } from "./types.js";
+/** What the outline needs of a session: its format, its page count and its elements. */
+export interface OutlineSource {
+    readonly format: EditableFormat;
+    readonly state: EditState;
+    getElements(query?: ElementQuery, options?: ReadOptions): Promise<ReadResult<EditElement>>;
+}
+/** The outline of a session's document; one `getElements()` read, reshaped. */
+export declare function readOutline(session: OutlineSource, limits: ResourceLimits, options?: OutlineOptions): Promise<OutlineResult>;
+/** The description of a session's document: the outline rendered within a character budget. */
+export declare function readDescription(session: OutlineSource, limits: ResourceLimits, options?: DescribeOptions): Promise<ReadItem<DocumentDescription>>;
+export interface BuiltOutline {
+    readonly nodes: readonly OutlineNode[];
+    readonly nodeCount: number;
+    readonly truncated: boolean;
+}
+/**
+ * Nests elements by `parentId`, numbers them in reading order, keeps the
+ * nodes the options ask for (a container stays when a descendant is kept)
+ * and cuts the result at `maxNodes`. Ordinals are assigned before any
+ * filtering, so "3.2" names the same paragraph whatever the query.
+ */
+export declare function buildOutline(format: EditableFormat, elements: readonly EditElement[], options: Pick<OutlineOptions, "pageRange" | "kinds" | "maxTextChars">, maxNodes: number): BuiltOutline;
+/**
+ * What a person calls the element, when the format knows: a shape's name
+ * or placeholder in a deck, a paragraph's style in a Word document, a
+ * table's size everywhere.
+ */
+export declare function labelOf(format: EditableFormat, element: EditElement): string | undefined;
+/**
+ * The description's grammar, one line per node:
+ *
+ *     <format>: <n> pages|slides, <m> elements
+ *     [<id>] page <p> <kind> "<label>" (<flags>): <text>…
+ *       [<child id>] page <p> <kind>: <text>
+ *
+ * The page is left out while the node has none, the label and the flags
+ * while the node has none, the text while it is empty. Tabs in the text
+ * become ` | `, line breaks ` ⏎ `; a cut text ends in `…`. Children are
+ * indented two spaces per level. The budget cuts whole lines and the last
+ * line then says how many were left out.
+ */
+export declare function renderDescription(format: EditableFormat, pageCount: number, outline: BuiltOutline | OutlineResult, maxChars: number, maxNodes: number): DocumentDescription;
+/** One line of text: tabs as cell separators, breaks marked, other controls blanked. */
+export declare function foldText(text: string): string;