@laminapdf/sdk 0.0.0-stage → 0.2.0-alpha.3

package/dist/errors.d.ts

@@ -0,0 +1,102 @@
+import { type ErrorCode, type ErrorKind, RAISED_BY_PACKAGE, type WarningCode } from "./generated/codes.js";
+export type { ErrorKind };
+/** Where a problem is (ADR 0026 §1.1); each field has one meaning, all lamina-made values. */
+export interface Location {
+    /** Byte offset in the input file. */
+    readonly offset?: number;
+    /** Object number of the indirect object the problem is in or at. */
+    readonly object?: number;
+    /** Byte offset in the decoded data of `object`. */
+    readonly streamOffset?: number;
+    /** 0-based page index (ADR 0027 §6). */
+    readonly pageIndex?: number;
+    /** A LaminaPdfId (`p12.0`). */
+    readonly id?: string;
+}
+/** The ADR 0026 §1 object: what `LaminaPdfError.toJSON()` returns and the WASM throws. */
+export interface Diagnostic<C extends string = ErrorCode> {
+    readonly code: C;
+    readonly kind: ErrorKind;
+    readonly message: string;
+    readonly hint?: string;
+    readonly didYouMean?: readonly string[];
+    readonly location?: Location;
+    readonly data?: Readonly<Record<string, unknown>>;
+    readonly docsUrl: string;
+}
+/**
+ * A warning: something Lamina PDF repaired or skipped (ADR 0003, ADR 0026 §1). The §1 object without
+ * `didYouMean`; document text appears only in `data`.
+ */
+export type LaminaPdfWarning = Omit<Diagnostic<WarningCode>, "didYouMean">;
+/**
+ * The one error class of `@laminapdf/sdk` (ADR 0026 §7). `message`, `hint` and `didYouMean` never
+ * hold document text (ADR 0026 §4); that goes in `data`, marked untrusted on the code's page at
+ * `docsUrl`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   Document.open(bytes, { password: "secret" });
+ * } catch (e) {
+ *   if (isLaminaPdfError(e, "wrong-password")) askAgain();
+ *   else throw e;
+ * }
+ * ```
+ */
+export declare class LaminaPdfError<C extends ErrorCode = ErrorCode> extends Error {
+    readonly name = "LaminaPdfError";
+    /** The stable code (`fixtures/codes.json`). */
+    readonly code: C;
+    /** What the caller can do about it. */
+    readonly kind: ErrorKind;
+    /** One actionable sentence for this code. */
+    readonly hint?: string;
+    /** For `usage` errors: the closest known names (Lamina PDF's own vocabulary). */
+    readonly didYouMean?: readonly string[];
+    /** Where in the input or the document. */
+    readonly location?: Location;
+    /** Code-specific fields, documented on the code's page (the only place document text appears). */
+    readonly data?: Readonly<Record<string, unknown>>;
+    /** The code's page. */
+    readonly docsUrl: string;
+    /**
+     * @param diagnostic - the ADR 0026 §1 object.
+     * @param options - `cause`, when wrapping another error.
+     */
+    constructor(diagnostic: Diagnostic<C>, options?: {
+        readonly cause?: unknown;
+    });
+    /**
+     * For `data-pending`: the byte ranges a range document needs fetched before the call can
+     * succeed (`data.ranges`); `undefined` for other codes. {@link Document.ensure} fetches them.
+     */
+    get ranges(): readonly {
+        readonly offset: number;
+        readonly length: number;
+    }[] | undefined;
+    /** The ADR 0026 §1 object (for logs, workers and `--json` output); optional fields omitted. */
+    toJSON(): Diagnostic<C>;
+}
+/**
+ * Whether `e` is a {@link LaminaPdfError}, with `code` when given.
+ *
+ * @param e - anything caught.
+ * @param code - the code to match.
+ * @returns true for a LaminaPdfError (with that code).
+ */
+export declare function isLaminaPdfError<C extends ErrorCode>(e: unknown, code?: C): e is LaminaPdfError<C>;
+/** Whether `value` is the §1 object the WASM throws. */
+export declare function isDiagnostic(value: unknown): value is Diagnostic<ErrorCode>;
+/** A LaminaPdfError for a code `@laminapdf/sdk` raises itself (kind and hint from codes.json). */
+export declare function packageError<C extends keyof typeof RAISED_BY_PACKAGE>(code: C, message: string, extra?: Pick<Diagnostic<C>, "didYouMean" | "data"> & {
+    readonly cause?: unknown;
+}): LaminaPdfError<C>;
+/**
+ * The names in `known` within two edits of `given`, closest first; names at the same distance in
+ * code-point order. Edits count code points, after lowercasing ASCII letters only.
+ * laminapdf-wasm follows the same rule, and fixtures/did-you-mean.json pins both. `<` compares
+ * UTF-16 code units, which is code-point order for the library's names (all ASCII).
+ */
+export declare function didYouMean(given: string, known: readonly string[]): string[];
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -0,0 +1,131 @@
+// LaminaPdfError and LaminaPdfWarning (ADR 0026 §1, §7): every error @laminapdf/sdk throws is a
+// LaminaPdfError built from the §1 object the WASM throws, or raised here with the kind and hint
+// codes.json gives the code.
+import { docsUrl, RAISED_BY_PACKAGE } from "./generated/codes.js";
+/**
+ * The one error class of `@laminapdf/sdk` (ADR 0026 §7). `message`, `hint` and `didYouMean` never
+ * hold document text (ADR 0026 §4); that goes in `data`, marked untrusted on the code's page at
+ * `docsUrl`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   Document.open(bytes, { password: "secret" });
+ * } catch (e) {
+ *   if (isLaminaPdfError(e, "wrong-password")) askAgain();
+ *   else throw e;
+ * }
+ * ```
+ */
+export class LaminaPdfError extends Error {
+    name = "LaminaPdfError";
+    /** The stable code (`fixtures/codes.json`). */
+    code;
+    /** What the caller can do about it. */
+    kind;
+    /** One actionable sentence for this code. */
+    hint;
+    /** For `usage` errors: the closest known names (Lamina PDF's own vocabulary). */
+    didYouMean;
+    /** Where in the input or the document. */
+    location;
+    /** Code-specific fields, documented on the code's page (the only place document text appears). */
+    data;
+    /** The code's page. */
+    docsUrl;
+    /**
+     * @param diagnostic - the ADR 0026 §1 object.
+     * @param options - `cause`, when wrapping another error.
+     */
+    constructor(diagnostic, options) {
+        super(diagnostic.message, options);
+        this.code = diagnostic.code;
+        this.kind = diagnostic.kind;
+        this.docsUrl = diagnostic.docsUrl;
+        if (diagnostic.hint !== undefined)
+            this.hint = diagnostic.hint;
+        // ADR 0026 §1: optional keys are omitted, and an empty list is no candidates at all.
+        if (diagnostic.didYouMean !== undefined && diagnostic.didYouMean.length > 0)
+            this.didYouMean = diagnostic.didYouMean;
+        if (diagnostic.location !== undefined)
+            this.location = diagnostic.location;
+        if (diagnostic.data !== undefined)
+            this.data = diagnostic.data;
+    }
+    /**
+     * For `data-pending`: the byte ranges a range document needs fetched before the call can
+     * succeed (`data.ranges`); `undefined` for other codes. {@link Document.ensure} fetches them.
+     */
+    get ranges() {
+        if (this.code !== "data-pending")
+            return undefined;
+        const raw = this.data?.ranges;
+        if (!Array.isArray(raw))
+            return [];
+        return raw.flatMap((r) => Array.isArray(r) && typeof r[0] === "number" && typeof r[1] === "number" ? [{ offset: r[0], length: r[1] }] : []);
+    }
+    /** The ADR 0026 §1 object (for logs, workers and `--json` output); optional fields omitted. */
+    toJSON() {
+        return {
+            code: this.code,
+            kind: this.kind,
+            message: this.message,
+            ...(this.hint === undefined ? {} : { hint: this.hint }),
+            ...(this.didYouMean === undefined ? {} : { didYouMean: this.didYouMean }),
+            ...(this.location === undefined ? {} : { location: this.location }),
+            ...(this.data === undefined ? {} : { data: this.data }),
+            docsUrl: this.docsUrl,
+        };
+    }
+}
+/**
+ * Whether `e` is a {@link LaminaPdfError}, with `code` when given.
+ *
+ * @param e - anything caught.
+ * @param code - the code to match.
+ * @returns true for a LaminaPdfError (with that code).
+ */
+export function isLaminaPdfError(e, code) {
+    return e instanceof LaminaPdfError && (code === undefined || e.code === code);
+}
+/** Whether `value` is the §1 object the WASM throws. */
+export function isDiagnostic(value) {
+    if (typeof value !== "object" || value === null || value instanceof Error)
+        return false;
+    const v = value;
+    return typeof v.code === "string" && typeof v.kind === "string" && typeof v.docsUrl === "string";
+}
+/** A LaminaPdfError for a code `@laminapdf/sdk` raises itself (kind and hint from codes.json). */
+export function packageError(code, message, extra = {}) {
+    const { kind, hint } = RAISED_BY_PACKAGE[code];
+    const { cause, ...fields } = extra;
+    return new LaminaPdfError({ code, kind, message, hint, ...fields, docsUrl: docsUrl(code) }, cause === undefined ? undefined : { cause });
+}
+/**
+ * The names in `known` within two edits of `given`, closest first; names at the same distance in
+ * code-point order. Edits count code points, after lowercasing ASCII letters only.
+ * laminapdf-wasm follows the same rule, and fixtures/did-you-mean.json pins both. `<` compares
+ * UTF-16 code units, which is code-point order for the library's names (all ASCII).
+ */
+export function didYouMean(given, known) {
+    const chars = (s) => Array.from(s.replace(/[A-Z]/g, (c) => c.toLowerCase()));
+    const distance = (a, b) => {
+        let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+        for (let i = 0; i < a.length; i++) {
+            const next = [i + 1];
+            for (let j = 0; j < b.length; j++) {
+                const cost = (row[j] ?? 0) + (a[i] === b[j] ? 0 : 1);
+                next.push(Math.min(cost, (row[j + 1] ?? 0) + 1, (next[j] ?? 0) + 1));
+            }
+            row = next;
+        }
+        return row[b.length] ?? 0;
+    };
+    const target = chars(given);
+    return known
+        .map((k) => [distance(target, chars(k)), k])
+        .filter(([d]) => d <= 2)
+        .sort(([dx, x], [dy, y]) => dx - dy || (x < y ? -1 : Number(x > y)))
+        .map(([, k]) => k);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/explain.d.ts

@@ -0,0 +1,20 @@
+import { type ErrorCode, type WarningCode } from "./generated/codes.js";
+export type { ErrorCode, ErrorKind, WarningCode } from "./generated/codes.js";
+export { DOCS_URL, docsUrl, ERROR_CODES, HINTS, KINDS, WARNING_CODES } from "./generated/codes.js";
+/** Whether `code` is one of Lamina PDF's error or warning codes. */
+export declare function isCode(code: string): code is ErrorCode | WarningCode;
+/**
+ * The explain page of `code` as Markdown (`docs/errors/<code>.md`: what happened, why, how to fix,
+ * an example and the `data` fields), or `undefined` for a string that is not a code. The same
+ * text as `docsUrl` and `laminapdf::explain` in Rust.
+ *
+ * @param code - an error or warning code, such as `LaminaPdfError.code`.
+ * @example
+ * ```ts
+ * import { explain } from "@laminapdf/sdk/explain";
+ * console.log(explain("wrong-password"));
+ * ```
+ */
+export declare function explain(code: ErrorCode | WarningCode): string;
+export declare function explain(code: string): string | undefined;
+//# sourceMappingURL=explain.d.ts.map

package/dist/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,SAAS,EAAS,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAG/E,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEnG,oEAAoE;AACpE,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,SAAS,GAAG,WAAW,CAEpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAC/D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC"}

package/dist/explain.js

@@ -0,0 +1,14 @@
+// `@laminapdf/sdk/explain` (ADR 0026 §6): every code's explain page, kind and hint, for tools and
+// agents that want to tell a user what a code means and what to do. A separate subpath, so the
+// ~80 KB of page text and the tables stay out of the main bundle (and out of the WebAssembly).
+import { HINTS } from "./generated/codes.js";
+import { PAGES } from "./generated/explain.js";
+export { DOCS_URL, docsUrl, ERROR_CODES, HINTS, KINDS, WARNING_CODES } from "./generated/codes.js";
+/** Whether `code` is one of Lamina PDF's error or warning codes. */
+export function isCode(code) {
+    return Object.hasOwn(HINTS, code);
+}
+export function explain(code) {
+    return isCode(code) ? PAGES[code] : undefined;
+}
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,+FAA+F;AAC/F,+FAA+F;AAC/F,OAAO,EAAkB,KAAK,EAAoB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAG/C,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEnG,oEAAoE;AACpE,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC;AAgBD,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChD,CAAC"}

package/dist/extract.d.ts

@@ -0,0 +1,57 @@
+import type { ExtractFormat, ReadingOrderName as ReadingOrder, SplitOnName as SplitOn, TableModeName as TableMode } from "@laminapdf/wasm/extract";
+import type { LaminaPdfWarning } from "./errors.js";
+import type { Chunk, Extraction as ExtractionJson } from "./generated/extract.js";
+export type { Cell, Coordinates, Dropped, DropReason, ExtractedPage, ExtractedSource, Flags, Generator, JsonBlock as ExtractedBlock, Region, Span, StructRef, StructSource, TableDetector, TextRange, } from "./generated/extract.js";
+/**
+ * The `laminapdf.extract/1` document: the schema's type, with the file's warnings as the
+ * {@link LaminaPdfWarning}s they are (the schema leaves their shape to ADR 0026's).
+ */
+export type Extraction = Omit<ExtractionJson, "warnings"> & {
+    warnings: LaminaPdfWarning[];
+};
+export type { ExtractFormat, ReadingOrder, SplitOn, TableMode };
+/** How the Markdown is cut into chunks. */
+export interface ChunkOptions {
+    /** A chunk's budget in approximate tokens (characters / 4); 512 by default. Blocks are never cut. */
+    readonly maxTokens?: number;
+    /** Approximate tokens of whole blocks a chunk repeats from the one before it; 0 by default. */
+    readonly overlap?: number;
+    /** Where chunks may start. */
+    readonly splitOn?: SplitOn;
+}
+/** Options for {@link Document.extract}. */
+export interface ExtractOptions<F extends ExtractFormat = ExtractFormat> {
+    /** What to return: Markdown or plain text as a string, the JSON as an {@link Extraction}, or {@link Chunk}s. */
+    readonly format: F;
+    /** The 0-based page indices to extract, in this order; every page by default. */
+    readonly pages?: readonly number[];
+    /** Where the reading order comes from; `"auto"` by default. */
+    readonly readingOrder?: ReadingOrder;
+    /**
+     * `keepSpans` keeps each dropped run's text in its `dropped` entry (JSON), for auditing a file.
+     * `furniture` (on by default) drops running headers, footers, page numbers and artifact-marked text too.
+     */
+    readonly drop?: {
+        readonly keepSpans?: boolean;
+        readonly furniture?: boolean;
+    };
+    /** Which table detectors run; `"lattice"` by default. */
+    readonly tables?: TableMode;
+    /** Join words hyphenated across lines; on by default. */
+    readonly dehyphenate?: boolean;
+    /** Write `<!-- page N -->` before each page's first block (Markdown, chunks and the JSON's text ranges). */
+    readonly pageMarkers?: boolean;
+    /** How chunks are cut (`"chunks"`, and `"json"` to include them). */
+    readonly chunk?: ChunkOptions;
+}
+/** The result of {@link Document.extract} for each format. */
+export interface ExtractResult {
+    readonly markdown: string;
+    readonly text: string;
+    readonly json: Extraction;
+    readonly chunks: Chunk[];
+}
+/** The WASM's string as the type `format` promises. */
+export declare function parseExtract<F extends ExtractFormat>(format: F, out: string): ExtractResult[F];
+export type { Chunk };
+//# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,IAAI,YAAY,EAChC,WAAW,IAAI,OAAO,EACtB,aAAa,IAAI,SAAS,EAC3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAElF,YAAY,EACV,IAAI,EACJ,WAAW,EACX,OAAO,EACP,UAAU,EACV,aAAa,EACb,eAAe,EACf,KAAK,EACL,SAAS,EACT,SAAS,IAAI,cAAc,EAC3B,MAAM,EACN,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,aAAa,EACb,SAAS,GACV,MAAM,wBAAwB,CAAC;AAEhC;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,GAAG;IAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC;AAI7F,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAEhE,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,qGAAqG;IACrG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa;IACrE,gHAAgH;IAChH,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/E,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,4GAA4G;IAC5G,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CAC/B;AAED,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;CAC1B;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CAE9F;AAED,YAAY,EAAE,KAAK,EAAE,CAAC"}

package/dist/extract.js

@@ -0,0 +1,5 @@
+/** The WASM's string as the type `format` promises. */
+export function parseExtract(format, out) {
+    return (format === "json" || format === "chunks" ? JSON.parse(out) : out);
+}
+//# sourceMappingURL=extract.js.map

package/dist/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAkFA,uDAAuD;AACvD,MAAM,UAAU,YAAY,CAA0B,MAAS,EAAE,GAAW;IAC1E,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAqB,CAAC;AAChG,CAAC"}

package/dist/font.d.ts

@@ -0,0 +1,73 @@
+import type { WasmImage } from "@laminapdf/wasm/base";
+import { type BaseGlue } from "./init.js";
+import type { Instance } from "./internal/instance.js";
+/** The standard 14 fonts, by PostScript name: no bytes needed, not embedded, Latin only, unshaped. */
+export type Standard14 = "Times-Roman" | "Times-Bold" | "Times-Italic" | "Times-BoldItalic" | "Helvetica" | "Helvetica-Bold" | "Helvetica-Oblique" | "Helvetica-BoldOblique" | "Courier" | "Courier-Bold" | "Courier-Oblique" | "Courier-BoldOblique" | "Symbol" | "ZapfDingbats";
+/** What a builder knows of a font once registered. */
+export interface FontInfo {
+    /** The family name. */
+    readonly family: string;
+    /** The PostScript name. */
+    readonly postscriptName: string;
+    /** Whether it is one of the standard 14 (not embedded). */
+    readonly isStandard: boolean;
+}
+/**
+ * A font to draw text with: TrueType or OpenType bytes (subset to the glyphs drawn and embedded)
+ * or one of the standard 14. Needs the text module (`init({ text: true })`).
+ *
+ * @example
+ * ```ts
+ * const inter = Font.fromBytes(await (await fetch("/Inter.ttf")).arrayBuffer());
+ * surface.text("Hello", { font: inter, size: 12, at: [72, 72] });
+ * ```
+ */
+export declare class Font {
+    /** The font program, for a font loaded from bytes. */
+    readonly bytes: Uint8Array | undefined;
+    /** The PostScript name, for a standard 14 font. */
+    readonly standard: Standard14 | undefined;
+    private constructor();
+    /**
+     * A font from its bytes (TrueType or OpenType/CFF). The bytes are checked when a builder first
+     * uses the font (`invalid-font`, `font-not-embeddable`).
+     */
+    static fromBytes(bytes: Uint8Array | ArrayBuffer): Font;
+    /** One of the standard 14 fonts. */
+    static standard(name: Standard14): Font;
+}
+/**
+ * An image to draw: a JPEG (passed through), a PNG (alpha as a soft mask) or raw RGBA pixels.
+ * The bytes are copied when the image is created. It is decoded once per WASM module, the first
+ * time a builder of that module draws it (or `width`/`height` is read), so problems with the
+ * data (`invalid-image`, `unsupported-image`, …) surface there. Written once per document however
+ * often it is drawn. It keeps its bytes, so it outlives `reset()` and decodes again.
+ */
+export declare class Image {
+    #private;
+    private constructor();
+    /** A JPEG. */
+    static jpeg(bytes: Uint8Array): Image;
+    /** A PNG. */
+    static png(bytes: Uint8Array): Image;
+    /** 8-bit RGBA pixels, row by row (`image-data-length` at first use for a wrong length). */
+    static rgba(width: number, height: number, pixels: Uint8Array): Image;
+    /** Width in pixels (decodes the image if no module has yet). @throws {@link LaminaPdfError} as `in`. */
+    get width(): number;
+    /** Height in pixels (decodes the image if no module has yet). @throws {@link LaminaPdfError} as `in`. */
+    get height(): number;
+    /**
+     * Frees the image's WASM memory now; without it, the garbage collector frees it later. A second
+     * call does nothing, and any other call afterwards throws `disposed`. Prefer `using`.
+     */
+    free(): void;
+    /** Frees the image at the end of a `using` block (an alias of `free()`). */
+    [Symbol.dispose](): void;
+    /**
+     * @internal The image in `instance`, decoded there at first use (and again after a reset).
+     * @throws {@link LaminaPdfError} `disposed`; `invalid-image`, `unsupported-image`,
+     *   `image-too-large`, `image-data-length`.
+     */
+    in(instance: Instance<BaseGlue>): WasmImage;
+}
+//# sourceMappingURL=font.d.ts.map

package/dist/font.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font.d.ts","sourceRoot":"","sources":["../src/font.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,KAAK,QAAQ,EAAc,MAAM,WAAW,CAAC;AAEtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD,sGAAsG;AACtG,MAAM,MAAM,UAAU,GAClB,aAAa,GACb,YAAY,GACZ,cAAc,GACd,kBAAkB,GAClB,WAAW,GACX,gBAAgB,GAChB,mBAAmB,GACnB,uBAAuB,GACvB,SAAS,GACT,cAAc,GACd,iBAAiB,GACjB,qBAAqB,GACrB,QAAQ,GACR,cAAc,CAAC;AAEnB,sDAAsD;AACtD,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,qBAAa,IAAI;IACf,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;IACvC,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAC;IAE1C,OAAO,eAGN;IAED;;;OAGG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAEtD;IAED,oCAAoC;IACpC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAEtC;CACF;AAoBD;;;;;;GAMG;AACH,qBAAa,KAAK;;IAMhB,OAAO,eAEN;IAED,cAAc;IACd,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,CAEpC;IAED,aAAa;IACb,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,CAEnC;IAED,2FAA2F;IAC3F,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,KAAK,CAEpE;IAED,wGAAwG;IACxG,IAAI,KAAK,IAAI,MAAM,CAGlB;IAED,yGAAyG;IACzG,IAAI,MAAM,IAAI,MAAM,CAGnB;IAYD;;;OAGG;IACH,IAAI,IAAI,IAAI,CAQX;IAED,4EAA4E;IAC5E,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;IAED;;;;OAIG;IACH,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,SAAS,CAS1C;CACF"}

package/dist/font.js

@@ -0,0 +1,133 @@
+import { packageError } from "./errors.js";
+import { baseModule } from "./init.js";
+import { disposable, forget, watch } from "./internal/handle.js";
+/**
+ * A font to draw text with: TrueType or OpenType bytes (subset to the glyphs drawn and embedded)
+ * or one of the standard 14. Needs the text module (`init({ text: true })`).
+ *
+ * @example
+ * ```ts
+ * const inter = Font.fromBytes(await (await fetch("/Inter.ttf")).arrayBuffer());
+ * surface.text("Hello", { font: inter, size: 12, at: [72, 72] });
+ * ```
+ */
+export class Font {
+    /** The font program, for a font loaded from bytes. */
+    bytes;
+    /** The PostScript name, for a standard 14 font. */
+    standard;
+    constructor(bytes, standard) {
+        this.bytes = bytes;
+        this.standard = standard;
+    }
+    /**
+     * A font from its bytes (TrueType or OpenType/CFF). The bytes are checked when a builder first
+     * uses the font (`invalid-font`, `font-not-embeddable`).
+     */
+    static fromBytes(bytes) {
+        return new Font(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes), undefined);
+    }
+    /** One of the standard 14 fonts. */
+    static standard(name) {
+        return new Font(undefined, name);
+    }
+}
+function decode(instance, source) {
+    return instance.call((glue) => {
+        switch (source.kind) {
+            case "jpeg":
+                return glue.WasmImage.jpeg(source.bytes);
+            case "png":
+                return glue.WasmImage.png(source.bytes);
+            case "rgba":
+                return glue.WasmImage.rgba(source.width, source.height, source.bytes);
+        }
+    });
+}
+/**
+ * An image to draw: a JPEG (passed through), a PNG (alpha as a soft mask) or raw RGBA pixels.
+ * The bytes are copied when the image is created. It is decoded once per WASM module, the first
+ * time a builder of that module draws it (or `width`/`height` is read), so problems with the
+ * data (`invalid-image`, `unsupported-image`, …) surface there. Written once per document however
+ * often it is drawn. It keeps its bytes, so it outlives `reset()` and decodes again.
+ */
+export class Image {
+    #source;
+    /** The decoded copy in each module, with the generation of the instance it lives in. */
+    #decoded = new Map();
+    #freed = false;
+    constructor(source) {
+        this.#source = source;
+    }
+    /** A JPEG. */
+    static jpeg(bytes) {
+        return new Image({ kind: "jpeg", bytes: bytes.slice() });
+    }
+    /** A PNG. */
+    static png(bytes) {
+        return new Image({ kind: "png", bytes: bytes.slice() });
+    }
+    /** 8-bit RGBA pixels, row by row (`image-data-length` at first use for a wrong length). */
+    static rgba(width, height, pixels) {
+        return new Image({ kind: "rgba", width, height, bytes: pixels.slice() });
+    }
+    /** Width in pixels (decodes the image if no module has yet). @throws {@link LaminaPdfError} as `in`. */
+    get width() {
+        const [instance, image] = this.#any();
+        return instance.call(() => image.width);
+    }
+    /** Height in pixels (decodes the image if no module has yet). @throws {@link LaminaPdfError} as `in`. */
+    get height() {
+        const [instance, image] = this.#any();
+        return instance.call(() => image.height);
+    }
+    /** A decoded copy, in any module (the base module when none has one). */
+    #any() {
+        for (const [instance, held] of this.#decoded) {
+            instance.live();
+            if (held.generation === instance.generation)
+                return [instance, held.image];
+        }
+        const base = baseModule();
+        return [base, this.in(base)];
+    }
+    /**
+     * Frees the image's WASM memory now; without it, the garbage collector frees it later. A second
+     * call does nothing, and any other call afterwards throws `disposed`. Prefer `using`.
+     */
+    free() {
+        if (this.#freed)
+            return;
+        this.#freed = true;
+        forget(this);
+        for (const [instance, held] of this.#decoded) {
+            if (instance.owns(held.generation))
+                held.image.free();
+        }
+        this.#decoded.clear();
+    }
+    /** Frees the image at the end of a `using` block (an alias of `free()`). */
+    [Symbol.dispose]() {
+        this.free();
+    }
+    /**
+     * @internal The image in `instance`, decoded there at first use (and again after a reset).
+     * @throws {@link LaminaPdfError} `disposed`; `invalid-image`, `unsupported-image`,
+     *   `image-too-large`, `image-data-length`.
+     */
+    in(instance) {
+        if (this.#freed)
+            throw packageError("disposed", "the Image was used after free() or its using block");
+        instance.live();
+        const held = this.#decoded.get(instance);
+        if (held !== undefined && held.generation === instance.generation)
+            return held.image;
+        const image = decode(instance, this.#source);
+        if (this.#decoded.size === 0)
+            watch(this, "Image");
+        this.#decoded.set(instance, { generation: instance.generation, image });
+        return image;
+    }
+}
+disposable(Image);
+//# sourceMappingURL=font.js.map

package/dist/font.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"font.js","sourceRoot":"","sources":["../src/font.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAiB,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AA8BjE;;;;;;;;;GASG;AACH,MAAM,OAAO,IAAI;IACf,sDAAsD;IAC7C,KAAK,CAAyB;IACvC,mDAAmD;IAC1C,QAAQ,CAAyB;IAE1C,YAAoB,KAA6B,EAAE,QAAgC;QACjF,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,SAAS,CAAC,KAA+B;QAC9C,OAAO,IAAI,IAAI,CAAC,KAAK,YAAY,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;IAC1F,CAAC;IAED,oCAAoC;IACpC,MAAM,CAAC,QAAQ,CAAC,IAAgB;QAC9B,OAAO,IAAI,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;CACF;AAOD,SAAS,MAAM,CAAC,QAA4B,EAAE,MAAmB;IAC/D,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QAC5B,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;YACpB,KAAK,MAAM;gBACT,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3C,KAAK,KAAK;gBACR,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC1C,KAAK,MAAM;gBACT,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,KAAK;IACP,OAAO,CAAc;IAC9B,wFAAwF;IAC/E,QAAQ,GAAG,IAAI,GAAG,EAAkF,CAAC;IAC9G,MAAM,GAAG,KAAK,CAAC;IAEf,YAAoB,MAAmB;QACrC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,cAAc;IACd,MAAM,CAAC,IAAI,CAAC,KAAiB;QAC3B,OAAO,IAAI,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,aAAa;IACb,MAAM,CAAC,GAAG,CAAC,KAAiB;QAC1B,OAAO,IAAI,KAAK,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,2FAA2F;IAC3F,MAAM,CAAC,IAAI,CAAC,KAAa,EAAE,MAAc,EAAE,MAAkB;QAC3D,OAAO,IAAI,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,wGAAwG;IACxG,IAAI,KAAK;QACP,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACtC,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,yGAAyG;IACzG,IAAI,MAAM;QACR,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACtC,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,yEAAyE;IACzE,IAAI;QACF,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC7C,QAAQ,CAAC,IAAI,EAAE,CAAC;YAChB,IAAI,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU;gBAAE,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7E,CAAC;QACD,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;QAC1B,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,IAAI;QACF,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,MAAM,CAAC,IAAI,CAAC,CAAC;QACb,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC7C,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC;gBAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACxD,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IAED,4EAA4E;IAC5E,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,EAAE,CAAC,QAA4B;QAC7B,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,YAAY,CAAC,UAAU,EAAE,oDAAoD,CAAC,CAAC;QACtG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;QACrF,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACnD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;QACxE,OAAO,KAAK,CAAC;IACf,CAAC;CACF;AAED,UAAU,CAAC,KAAK,CAAC,CAAC"}

package/dist/generated/builder-enums.d.ts

@@ -0,0 +1,29 @@
+/** Every FillRule, as the WASM module names it. */
+export declare const FILL_RULES: readonly ["nonZero", "evenOdd"];
+/** How a filled or clipped path decides what is inside. */
+export type FillRule = (typeof FILL_RULES)[number];
+/** Every LineCap, as the WASM module names it. */
+export declare const LINE_CAPS: readonly ["butt", "round", "square"];
+/** How open line ends are drawn. */
+export type LineCap = (typeof LINE_CAPS)[number];
+/** Every LineJoin, as the WASM module names it. */
+export declare const LINE_JOINS: readonly ["miter", "round", "bevel"];
+/** How corners are drawn. */
+export type LineJoin = (typeof LINE_JOINS)[number];
+/** Every BlendMode, as the WASM module names it. */
+export declare const BLEND_MODES: readonly ["normal", "multiply", "screen", "overlay", "darken", "lighten", "colorDodge", "colorBurn", "hardLight", "softLight", "difference", "exclusion", "hue", "saturation", "color", "luminosity"];
+/** Blend modes (`/BM`), camelCase. */
+export type BlendMode = (typeof BLEND_MODES)[number];
+/** Every ArtifactKind, as the WASM module names it. */
+export declare const ARTIFACT_KINDS: readonly ["layout", "page", "pagination", "background"];
+/** What kind of artifact (content outside the logical structure). */
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number];
+/** Every TableScope, as the WASM module names it. */
+export declare const TABLE_SCOPES: readonly ["row", "column", "both"];
+/** Which header cells a `TH` heads (`/Scope`). */
+export type TableScope = (typeof TABLE_SCOPES)[number];
+/** Every TagName, as the WASM module names it. */
+export declare const TAG_NAMES: readonly ["Document", "Part", "Sect", "H1", "H2", "H3", "H4", "H5", "H6", "P", "L", "LI", "Lbl", "LBody", "Table", "TR", "TH", "TD", "Figure", "Caption", "Link", "Span", "Quote", "Note", "Code"];
+/** A standard structure type (ISO 32000-1 §14.8.4). */
+export type TagName = (typeof TAG_NAMES)[number];
+//# sourceMappingURL=builder-enums.d.ts.map

package/dist/generated/builder-enums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder-enums.d.ts","sourceRoot":"","sources":["../../src/generated/builder-enums.ts"],"names":[],"mappings":"AAGA,mDAAmD;AACnD,eAAO,MAAM,UAAU,YACrB,SAAS,EACT,SAAS,CACD,CAAC;AAEX,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,kDAAkD;AAClD,eAAO,MAAM,SAAS,YACpB,MAAM,EACN,OAAO,EACP,QAAQ,CACA,CAAC;AAEX,oCAAoC;AACpC,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,mDAAmD;AACnD,eAAO,MAAM,UAAU,YACrB,OAAO,EACP,OAAO,EACP,OAAO,CACC,CAAC;AAEX,6BAA6B;AAC7B,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,oDAAoD;AACpD,eAAO,MAAM,WAAW,YACtB,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,WAAW,EACX,KAAK,EACL,YAAY,EACZ,OAAO,EACP,YAAY,CACJ,CAAC;AAEX,sCAAsC;AACtC,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,uDAAuD;AACvD,eAAO,MAAM,cAAc,YACzB,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,YAAY,CACJ,CAAC;AAEX,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,qDAAqD;AACrD,eAAO,MAAM,YAAY,YACvB,KAAK,EACL,QAAQ,EACR,MAAM,CACE,CAAC;AAEX,kDAAkD;AAClD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,kDAAkD;AAClD,eAAO,MAAM,SAAS,YACpB,UAAU,EACV,MAAM,EACN,MAAM,EACN,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,GAAG,EACH,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,MAAM,EACN,MAAM,EACN,OAAO,EACP,MAAM,EACN,MAAM,CACE,CAAC;AAEX,uDAAuD;AACvD,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC"}