web-doc 0.6.2 → 0.7.0

package/dist/edit/pptx/engine.js

@@ -0,0 +1,466 @@
+import { ViewerError } from "../../errors.js";
+import { AssetStore } from "../assets.js";
+import { invalidOperationError, parseReference } from "../operations.js";
+import { OoxmlPackage } from "../ooxml/package.js";
+import { readPlaceholders, readSlideElements, } from "./elements.js";
+import { frameContains, rectsIntersect } from "./geometry.js";
+import { DeckModel } from "./model.js";
+import { pptxHandlers } from "./handlers.js";
+import { issueCollector, } from "./operations.js";
+import { pptxOperationSchemas } from "./schemas.js";
+const SLIDE_PART = /^\/ppt\/slides\/slide(\d+)\.xml$/i;
+const SLIDE_RELS = /^\/ppt\/slides\/_rels\/slide(\d+)\.xml\.rels$/i;
+export class PptxEditEngine {
+    schemas = pptxOperationSchemas;
+    #original;
+    #limits;
+    #assets = new AssetStore();
+    #pkg;
+    #inspection;
+    #disposed = false;
+    constructor(original, pkg, limits) {
+        this.#original = original;
+        this.#pkg = pkg;
+        this.#limits = limits;
+    }
+    /** Opens the package and reads the deck index, so a broken deck fails here. */
+    static async open(bytes, limits, signal) {
+        const pkg = await OoxmlPackage.open(bytes, {
+            limits,
+            ...(signal ? { signal } : {}),
+        });
+        const engine = new PptxEditEngine(bytes, pkg, limits);
+        await engine.model(signal);
+        return engine;
+    }
+    /** The package behind the engine, for tests and the operations. */
+    get package() {
+        return this.#pkg;
+    }
+    get pageCount() {
+        return this.#modelSync?.pageCount ?? 0;
+    }
+    #modelSync;
+    /** The deck index at the current revision. */
+    async model(signal) {
+        return (await this.#inspect(signal)).model;
+    }
+    #inspect(signal) {
+        this.#assertAlive();
+        const revision = this.#pkg.revision;
+        if (!this.#inspection)
+            return this.#startInspection(revision, signal);
+        return this.#inspection.then((current) => current.revision === revision
+            ? current
+            : this.#startInspection(revision, signal));
+    }
+    /** Builds the index; a failed or aborted build is not kept. */
+    #startInspection(revision, signal) {
+        const pending = this.#buildInspection(revision, signal);
+        this.#inspection = pending;
+        pending.catch(() => {
+            if (this.#inspection === pending)
+                this.#inspection = undefined;
+        });
+        return pending;
+    }
+    /**
+     * After a commit: a change confined to slide parts keeps the deck index
+     * (the presentation, every layout and master, every slide's
+     * relationships); anything else — the presentation, parts added or
+     * removed other than media — rebuilds it on the next read.
+     */
+    async #afterCommit(parts) {
+        const current = this.#inspection
+            ? await this.#inspection.catch(() => undefined)
+            : undefined;
+        if (!parts || !current) {
+            this.#inspection = undefined;
+            return;
+        }
+        for (const name of parts.changed)
+            if (!SLIDE_PART.test(name) && !SLIDE_RELS.test(name)) {
+                this.#inspection = undefined;
+                return;
+            }
+        if (parts.added.length > 0 || parts.removed.length > 0) {
+            const structural = [...parts.added, ...parts.removed].some((name) => !/^\/ppt\/media\//i.test(name));
+            if (structural) {
+                this.#inspection = undefined;
+                return;
+            }
+        }
+        // Every cached slide was scanned at the old revision; a patch on such a
+        // scan is refused, so the slides are read again on demand while the
+        // deck index (presentation, layouts, masters) is kept.
+        current.slides.clear();
+        current.revision = this.#pkg.revision;
+    }
+    async #buildInspection(revision, signal) {
+        const model = await DeckModel.load(this.#pkg, signal);
+        this.#modelSync = model;
+        return { revision, model, placeholders: new Map(), slides: new Map() };
+    }
+    async validate(operations, signal) {
+        const issues = [];
+        const base = await this.#context(0, signal);
+        // Slide operations change the count the later operations see.
+        let pageCount = base.pageCount;
+        for (const [index, operation] of operations.entries()) {
+            const context = { ...base, pageCount, operationIndex: index };
+            switch (operation.op) {
+                case "insertSlide":
+                case "duplicateSlide":
+                    pageCount += 1;
+                    break;
+                case "deleteSlide":
+                    pageCount = Math.max(1, pageCount - 1);
+                    break;
+                default:
+                    break;
+            }
+            const handler = pptxHandlers.get(operation.op);
+            if (!handler) {
+                issues.push({
+                    operationIndex: index,
+                    path: "/op",
+                    code: "unknown-operation",
+                    message: `Unknown operation ${operation.op}`,
+                });
+                continue;
+            }
+            // A same-batch reference names an element that does not exist yet:
+            // its target is checked when the batch is applied, the rest now.
+            const target = operation.target;
+            const reference = typeof target === "string" ? parseReference(target) : undefined;
+            if (reference !== undefined && reference >= index) {
+                issues.push({
+                    operationIndex: index,
+                    path: "/target",
+                    code: "unknown-target",
+                    message: `"${target}" must refer to an earlier operation`,
+                });
+                continue;
+            }
+            const collect = issueCollector(index, issues);
+            await handler.validate(operation, context, reference === undefined
+                ? collect
+                : (path, code, message) => {
+                    if (!path.startsWith("/target") && !path.startsWith("/range"))
+                        collect(path, code, message);
+                });
+        }
+        return issues;
+    }
+    /** Plain operation arrays, as the unit tests pass them, become the next batch. */
+    async apply(input, signal) {
+        const batch = Array.isArray(input)
+            ? { stateId: this.#nextStateId(), operations: input }
+            : input;
+        this.#stateId = Math.max(this.#stateId, batch.stateId);
+        const snapshot = this.#pkg.snapshot();
+        const issuedIds = new Map(this.#issuedIds);
+        const createdIds = [];
+        const removedIds = [];
+        const changedPages = new Set();
+        const warnings = [];
+        const createdByOperation = [];
+        try {
+            for (const [index, raw] of batch.operations.entries()) {
+                throwIfAborted(signal);
+                const operation = resolveReferences(raw, createdByOperation, index);
+                const handler = pptxHandlers.get(operation.op);
+                if (!handler)
+                    throw new ViewerError("invalid-operation", `Unknown operation ${operation.op}`);
+                const context = await this.#context(batch.stateId, signal, index);
+                const issues = [];
+                await handler.validate(operation, context, issueCollector(index, issues));
+                if (issues.length > 0)
+                    throw invalidOperationError(issues);
+                const result = await handler.apply(operation, context);
+                await this.#afterCommit(result.parts);
+                createdByOperation.push([...result.createdIds]);
+                createdIds.push(...result.createdIds);
+                removedIds.push(...(result.removedIds ?? []));
+                // A removed id is never issued again on its slide.
+                for (const id of result.removedIds ?? []) {
+                    const match = /^(sld\d+):(\d+)/.exec(id);
+                    if (!match)
+                        continue;
+                    const key = match[1];
+                    this.#issuedIds.set(key, Math.max(this.#issuedIds.get(key) ?? 0, Number(match[2])));
+                }
+                for (const page of result.changedPages)
+                    changedPages.add(page);
+                warnings.push(...result.warnings);
+            }
+        }
+        catch (error) {
+            // Everything the batch did, including the ids it issued, is undone.
+            this.#pkg.restore(snapshot);
+            this.#issuedIds = issuedIds;
+            this.#inspection = undefined;
+            this.#modelSync = undefined;
+            throw error;
+        }
+        this.#pkg.release(snapshot);
+        const model = await this.model(signal);
+        return {
+            createdIds,
+            removedIds,
+            changedPages: [...changedPages].sort((a, b) => a - b),
+            pageCount: model.pageCount,
+            warnings,
+        };
+    }
+    #stateId = 0;
+    /** Highest `p:cNvPr` id issued per slide key in this session; replays rebuild it. */
+    #issuedIds = new Map();
+    #nextStateId() {
+        this.#stateId += 1;
+        return this.#stateId;
+    }
+    async #context(stateId, signal, operationIndex = 0) {
+        const model = await this.model(signal);
+        return {
+            pkg: this.#pkg,
+            model,
+            limits: this.#limits,
+            assets: this.#assets,
+            pageCount: model.pageCount,
+            stateId,
+            operationIndex,
+            elements: (pageIndex) => this.#slideElements(pageIndex, signal),
+            locate: (id) => this.#locate(id, signal),
+            allocateShapeId: (elements) => this.#allocateShapeId(elements),
+        };
+    }
+    async materialize(purposeOrSignal = "show", options = {}, signal = new AbortController().signal) {
+        return (await this.materializeDocument(purposeOrSignal, options, signal))
+            .bytes;
+    }
+    async materializeDocument(purposeOrSignal = "show", _options = {}, signal = new AbortController().signal) {
+        this.#assertAlive();
+        const own = purposeOrSignal instanceof AbortSignal ? purposeOrSignal : signal;
+        return { bytes: await this.#pkg.save({}, own), warnings: [] };
+    }
+    async restore(input, signal) {
+        const target = Array.isArray(input)
+            ? {
+                batches: input.map((operations, index) => ({ stateId: index + 1, operations })),
+            }
+            : input;
+        this.#assertAlive();
+        this.#pkg = await OoxmlPackage.open(target.base ?? this.#original, {
+            limits: this.#limits,
+            signal,
+        });
+        this.#inspection = undefined;
+        this.#modelSync = undefined;
+        this.#issuedIds = new Map();
+        await this.model(signal);
+        for (const batch of target.batches)
+            await this.apply(batch, signal);
+    }
+    async putAsset(id, data, _signal) {
+        this.#assets.set(id, data);
+    }
+    async getElements(query, signal) {
+        const model = await this.model(signal);
+        const pages = query.pageIndex === undefined
+            ? model.slides.map((_, index) => index)
+            : [query.pageIndex];
+        const out = [];
+        for (const pageIndex of pages) {
+            if (pageIndex < 0 || pageIndex >= model.pageCount)
+                continue;
+            const elements = await this.#slideElements(pageIndex, signal);
+            for (const record of elements.records) {
+                const element = record.element;
+                if (query.kinds && !query.kinds.includes(element.kind))
+                    continue;
+                if (query.intersects &&
+                    !rectsIntersect(element.bounds, query.intersects))
+                    continue;
+                out.push(element);
+            }
+        }
+        return out;
+    }
+    async getElement(id, signal) {
+        return (await this.#locate(id, signal))?.element;
+    }
+    async elementsAt(pageIndex, point, signal) {
+        const model = await this.model(signal);
+        if (pageIndex < 0 || pageIndex >= model.pageCount)
+            return [];
+        const elements = await this.#slideElements(pageIndex, signal);
+        const hits = [];
+        for (let index = elements.records.length - 1; index >= 0; index -= 1) {
+            const record = elements.records[index];
+            if (record.placed && frameContains(record.placed, point))
+                hits.push(record.element);
+        }
+        return hits;
+    }
+    async findText(query, options, signal) {
+        if (query.length === 0)
+            return [];
+        const model = await this.model(signal);
+        const [first, last] = options.pageRange ?? [0, model.pageCount - 1];
+        const fold = (value) => options.caseSensitive ? value : value.toLocaleLowerCase();
+        const needle = fold(query);
+        const targets = [];
+        const limit = options.maxResults ?? Number.POSITIVE_INFINITY;
+        for (let pageIndex = Math.max(0, first); pageIndex <= Math.min(last, model.pageCount - 1); pageIndex += 1) {
+            const elements = await this.#slideElements(pageIndex, signal);
+            for (const record of elements.records) {
+                const text = record.element.text;
+                if (!text)
+                    continue;
+                const haystack = fold(text);
+                let from = 0;
+                while (targets.length < limit) {
+                    const at = haystack.indexOf(needle, from);
+                    if (at < 0)
+                        break;
+                    const end = at + query.length;
+                    targets.push({
+                        pageIndex,
+                        text: text.slice(at, end),
+                        rects: [record.element.bounds],
+                        elementIds: [record.element.id],
+                        ranges: [
+                            {
+                                start: { elementId: record.element.id, offset: at },
+                                end: { elementId: record.element.id, offset: end },
+                            },
+                        ],
+                    });
+                    from = end;
+                }
+                if (targets.length >= limit)
+                    return targets;
+            }
+        }
+        return targets;
+    }
+    async slides(signal) {
+        const model = await this.model(signal);
+        const out = [];
+        for (const [pageIndex, slide] of model.slides.entries())
+            out.push({
+                pageIndex,
+                key: slide.key,
+                layout: slide.layout?.id ?? "",
+                hidden: await model.hidden(slide, signal),
+            });
+        return out;
+    }
+    async layouts(signal) {
+        const model = await this.model(signal);
+        return model.layouts.map((layout) => ({
+            id: layout.id,
+            name: layout.name,
+            ...(layout.type ? { type: layout.type } : {}),
+            master: layout.master.id,
+        }));
+    }
+    async dispose() {
+        this.#disposed = true;
+        this.#inspection = undefined;
+    }
+    async #slideElements(pageIndex, signal) {
+        const inspection = await this.#inspect(signal);
+        const slide = inspection.model.slideAt(pageIndex);
+        let pending = inspection.slides.get(slide.key);
+        if (!pending) {
+            const started = this.#readSlide(inspection, slide, pageIndex, signal);
+            pending = started;
+            inspection.slides.set(slide.key, started);
+            // An aborted or failed read must not stand in for the slide.
+            started.catch(() => {
+                if (inspection.slides.get(slide.key) === started)
+                    inspection.slides.delete(slide.key);
+            });
+        }
+        return pending;
+    }
+    /** One above every id on the slide and every id issued there this session. */
+    #allocateShapeId(elements) {
+        let max = 1;
+        for (const record of elements.records)
+            max = Math.max(max, record.cNvPrId);
+        const tree = elements.part.find("spTree");
+        if (tree)
+            for (const node of elements.part.findAll("cNvPr", tree)) {
+                const id = Number(elements.part.attribute(node, "id") ?? NaN);
+                if (Number.isInteger(id))
+                    max = Math.max(max, id);
+            }
+        const issued = this.#issuedIds.get(elements.slide.key) ?? 0;
+        const next = Math.max(max, issued) + 1;
+        this.#issuedIds.set(elements.slide.key, next);
+        return next;
+    }
+    async #readSlide(inspection, slide, pageIndex, signal) {
+        const table = (part) => {
+            if (!part)
+                return undefined;
+            let pending = inspection.placeholders.get(part);
+            if (!pending) {
+                const started = readPlaceholders(this.#pkg, part, signal);
+                pending = started;
+                inspection.placeholders.set(part, started);
+                started.catch(() => {
+                    if (inspection.placeholders.get(part) === started)
+                        inspection.placeholders.delete(part);
+                });
+            }
+            return pending;
+        };
+        const layout = await table(slide.layout?.part);
+        const master = await table(slide.layout?.master.part);
+        const presentation = inspection.model.presentation;
+        const defaultsNode = presentation.find("defaultTextStyle");
+        const sources = {
+            ...(layout ? { layout } : {}),
+            ...(master ? { master } : {}),
+            ...(defaultsNode
+                ? { defaults: { part: presentation, node: defaultsNode } }
+                : {}),
+        };
+        return readSlideElements(this.#pkg, inspection.model, slide, pageIndex, sources, signal);
+    }
+    async #locate(id, signal) {
+        const key = id.split(":")[0];
+        if (!key)
+            return undefined;
+        const model = await this.model(signal);
+        const pageIndex = model.slides.findIndex((slide) => slide.key === key);
+        if (pageIndex < 0)
+            return undefined;
+        return (await this.#slideElements(pageIndex, signal)).byId(id);
+    }
+    #assertAlive() {
+        if (this.#disposed)
+            throw new ViewerError("lifecycle-error", "The PPTX engine was disposed");
+    }
+}
+/** Replaces `"$<n>"` targets with the first id operation `n` created. */
+function resolveReferences(operation, created, index) {
+    const target = operation.target;
+    if (typeof target !== "string")
+        return operation;
+    const reference = parseReference(target);
+    if (reference === undefined)
+        return operation;
+    const id = reference < index ? created[reference]?.[0] : undefined;
+    if (!id)
+        throw new ViewerError("invalid-operation", `Operation ${index} refers to "${target}", which created nothing`, { details: { operationIndex: index, target } });
+    return { ...operation, target: id };
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new ViewerError("aborted", "The operation was aborted");
+}

package/dist/edit/pptx/geometry.d.ts

@@ -0,0 +1,72 @@
+import type { PageRect } from "../types.js";
+import type { ElementFrame } from "../types.js";
+import type { XmlElement, XmlPart } from "../ooxml/xml.js";
+export declare const EMU_PER_PX = 9525;
+export declare const EMU_PER_PT = 12700;
+export declare function emuToPx(emu: number): number;
+export declare function pxToEmu(px: number): number;
+/** An `a:xfrm` as the file stores it, in EMU and degrees. */
+export interface Xfrm {
+    readonly x: number;
+    readonly y: number;
+    readonly cx: number;
+    readonly cy: number;
+    /** Clockwise degrees. */
+    readonly rotation: number;
+    readonly flipH: boolean;
+    readonly flipV: boolean;
+    /** Child space of a group. */
+    readonly child?: {
+        readonly x: number;
+        readonly y: number;
+        readonly cx: number;
+        readonly cy: number;
+    };
+}
+/** Reads `a:xfrm` (or `p:xfrm` of a graphic frame); undefined without an offset and an extent. */
+export declare function readXfrm(part: XmlPart, node: XmlElement | undefined): Xfrm | undefined;
+/** A 2D affine transform: x' = a·x + c·y + e, y' = b·x + d·y + f. */
+export interface Matrix {
+    readonly a: number;
+    readonly b: number;
+    readonly c: number;
+    readonly d: number;
+    readonly e: number;
+    readonly f: number;
+}
+export declare const IDENTITY: Matrix;
+export declare function multiply(m: Matrix, n: Matrix): Matrix;
+export declare function translate(tx: number, ty: number): Matrix;
+export declare function scale(sx: number, sy: number): Matrix;
+export declare function apply(m: Matrix, point: {
+    readonly x: number;
+    readonly y: number;
+}): {
+    x: number;
+    y: number;
+};
+export declare function invert(m: Matrix): Matrix;
+/**
+ * The transform from a group's child space to its parent space: child
+ * coordinates are scaled from `chOff`/`chExt` into `off`/`ext`, then the
+ * group's rotation and flips apply about its centre.
+ */
+export declare function groupMatrix(group: Xfrm): Matrix;
+/** A frame in slide space (px) with its axis-aligned bounds. */
+export interface PlacedFrame {
+    readonly frame: ElementFrame;
+    readonly bounds: PageRect;
+}
+/**
+ * Places a frame given in its own space (EMU) through the transform of the
+ * groups above it. The reported frame keeps the element's box scaled and
+ * positioned by the groups, with the rotations and flips combined; the
+ * bounds are the axis-aligned box of its four transformed corners.
+ */
+export declare function placeFrame(frame: Xfrm, parents: Matrix): PlacedFrame;
+/** Whether a slide-space point lies inside a placed frame, rotation and flips included. */
+export declare function frameContains(placed: PlacedFrame, point: {
+    readonly x: number;
+    readonly y: number;
+}): boolean;
+export declare function rectsIntersect(a: PageRect, b: PageRect): boolean;