@divvun/cg3 0.0.0-stage → 0.5.0

package/dist/binding.js

@@ -0,0 +1,7 @@
+import { Core } from "./core.js";
+import * as glue from "./pkg/cg3_wasm.js";
+// [spec:cg3:req:wasm.module+1]
+// The package's one .wasm file ships in pkg/, beside the compiled entry
+// module, so a URL relative to this module finds it in every runtime.
+/** The package's module instance. Making it loads nothing. */
+export const core = new Core(glue, new URL("./pkg/cg3_wasm_bg.wasm", import.meta.url));

package/dist/core.d.ts

@@ -0,0 +1,37 @@
+import type { Glue, GlueObject } from "./glue.ts";
+import { type Logger, type LogLevel } from "./logging.ts";
+/**
+ * Where `init()` loads the module from: a URL (a string is read as one), a
+ * `Response`, the module's bytes, or a compiled `WebAssembly.Module`.
+ */
+export type InitSource = string | URL | Response | BufferSource | WebAssembly.Module;
+/**
+ * A WebAssembly module instance and the state the wrapper keeps about it.
+ * The package makes exactly one, in binding.ts, and every call into the
+ * module goes through it.
+ */
+export declare class Core {
+    #private;
+    /** `defaultSource` is the package's own `.wasm` file. Nothing is loaded yet. */
+    constructor(glue: Glue, defaultSource: URL);
+    /**
+     * Loads and starts the module. Every call after the first returns the first
+     * call's promise, whatever its argument, so there is only ever one instance.
+     * A start that fails leaves no instance, and the next call tries again.
+     */
+    init(source?: InitSource): Promise<void>;
+    /**
+     * Runs `f` against the glue once `init()` has resolved, and turns whatever
+     * it throws into a `Cg3Error`. After a trap it throws `poisoned` without
+     * running `f`.
+     */
+    call<T>(f: (glue: Glue) => T): T;
+    /** Sends the library's log events to `logger`, or to the console for null. */
+    setLogger(logger: Logger | null): void;
+    /** Logs events at `level` and the levels before it. The module skips the rest. */
+    setLogLevel(level: LogLevel): void;
+    /** Frees `glue` when `owner` becomes unreachable, unless `release` frees it first. */
+    adopt(owner: object, glue: GlueObject): void;
+    /** Frees `glue` at once, for `owner.free()`. Throws `poisoned` only if freeing traps. */
+    release(owner: object, glue: GlueObject): void;
+}

package/dist/core.js

@@ -0,0 +1,210 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { Cg3Error, fromGlue, messageOf } from "./errors.js";
+import { consoleLogger, eventLevel, isLogLevel, levelNumber, } from "./logging.js";
+/**
+ * A WebAssembly module instance and the state the wrapper keeps about it.
+ * The package makes exactly one, in binding.ts, and every call into the
+ * module goes through it.
+ */
+export class Core {
+    #glue;
+    #defaultSource;
+    #starting = null;
+    #ready = false;
+    /** Set by the first trap, and never cleared. */
+    #poison = null;
+    /** The message of a panic whose trap has not reached the wrapper yet. */
+    #panic = null;
+    #logger = consoleLogger;
+    /**
+     * Glue objects held for the life of the page once the instance is poisoned.
+     * Unreachable, wasm-bindgen's own registry would free them by entering the
+     * module, which a poisoned instance must never do.
+     */
+    #kept = [];
+    /**
+     * Frees the glue object of a wrapper the caller dropped. Holding the glue
+     * object as the held value keeps it reachable, so wasm-bindgen's registry
+     * never frees it first.
+     */
+    #registry = new FinalizationRegistry((glue) => this.#free(glue, false));
+    #sink = {
+        log: (level, target, message) => this.#deliver(level, target, message),
+        panic: (message) => {
+            this.#panic = message;
+        },
+    };
+    /** `defaultSource` is the package's own `.wasm` file. Nothing is loaded yet. */
+    constructor(glue, defaultSource) {
+        this.#glue = glue;
+        this.#defaultSource = defaultSource;
+    }
+    // [spec:cg3:req:wasm.init]
+    /**
+     * Loads and starts the module. Every call after the first returns the first
+     * call's promise, whatever its argument, so there is only ever one instance.
+     * A start that fails leaves no instance, and the next call tries again.
+     */
+    init(source) {
+        if (this.#starting === null) {
+            const starting = this.#start(source ?? this.#defaultSource);
+            this.#starting = starting;
+            starting.catch(() => {
+                if (this.#starting === starting)
+                    this.#starting = null;
+            });
+        }
+        return this.#starting;
+    }
+    async #start(source) {
+        try {
+            await this.#glue.default({ module_or_path: await load(source) });
+        }
+        catch (error) {
+            throw new Cg3Error("init-failed", `cannot start @divvun/cg3: ${messageOf(error)}`, {
+                cause: error,
+            });
+        }
+        this.#enter(() => this.#glue.install(this.#sink, levelNumber("warn")));
+        this.#ready = true;
+    }
+    // [spec:cg3:req:wasm.init]
+    // [spec:cg3:req:wasm.errors+1]
+    /**
+     * Runs `f` against the glue once `init()` has resolved, and turns whatever
+     * it throws into a `Cg3Error`. After a trap it throws `poisoned` without
+     * running `f`.
+     */
+    call(f) {
+        this.#check();
+        return this.#enter(() => f(this.#glue));
+    }
+    #check() {
+        if (this.#poison !== null)
+            throw this.#poisoned();
+        if (!this.#ready) {
+            throw new Cg3Error("not-initialised", "@divvun/cg3 is not initialised: call init() and wait for it to resolve first");
+        }
+    }
+    #enter(f) {
+        let result;
+        try {
+            result = f();
+        }
+        catch (error) {
+            throw this.#translate(error);
+        }
+        // A logger that called back in can trap the module in a nested call. That
+        // poisons the instance without unwinding this call, whose result is then
+        // as untrustworthy as the memory it came from.
+        if (this.#poison !== null)
+            throw this.#poisoned();
+        return result;
+    }
+    #translate(error) {
+        if (error instanceof Cg3Error)
+            return error;
+        if (error instanceof WebAssembly.RuntimeError) {
+            this.#poisonWith(error);
+            return this.#poisoned();
+        }
+        return fromGlue(error) ?? error;
+    }
+    #poisonWith(trap) {
+        if (this.#poison !== null)
+            return;
+        const panic = this.#panic;
+        this.#panic = null;
+        const message = panic === null ? `the module trapped: ${trap.message}` : `the module panicked: ${panic}`;
+        this.#poison = { message, trap };
+    }
+    #poisoned() {
+        const message = this.#poison?.message ?? "the module trapped";
+        return new Cg3Error("poisoned", `${message}. Load the page or process again to recover.`, {
+            cause: this.#poison?.trap,
+        });
+    }
+    // [spec:cg3:req:wasm.logging]
+    /** Sends the library's log events to `logger`, or to the console for null. */
+    setLogger(logger) {
+        this.#check();
+        if (logger !== null && typeof logger !== "function") {
+            throw new Cg3Error("invalid-argument", "a logger is a function, or null for the console");
+        }
+        this.#logger = logger ?? consoleLogger;
+    }
+    /** Logs events at `level` and the levels before it. The module skips the rest. */
+    setLogLevel(level) {
+        this.#check();
+        if (!isLogLevel(level)) {
+            throw new Cg3Error("invalid-argument", `there is no log level called ${String(level)}`);
+        }
+        this.#enter(() => this.#glue.setLogLevel(levelNumber(level)));
+    }
+    // A logger that throws must not throw into the module, which is mid-call.
+    #deliver(level, target, message) {
+        try {
+            this.#logger({ level: eventLevel(level), target, message });
+        }
+        catch (error) {
+            console.error("@divvun/cg3: the logger threw:", error);
+        }
+    }
+    // [spec:cg3:req:wasm.handle-lifetime]
+    /** Frees `glue` when `owner` becomes unreachable, unless `release` frees it first. */
+    adopt(owner, glue) {
+        this.#registry.register(owner, glue, owner);
+    }
+    /** Frees `glue` at once, for `owner.free()`. Throws `poisoned` only if freeing traps. */
+    release(owner, glue) {
+        this.#registry.unregister(owner);
+        this.#free(glue, true);
+    }
+    #free(glue, explicit) {
+        if (this.#poison !== null) {
+            this.#kept.push(glue);
+            return;
+        }
+        try {
+            this.#enter(() => glue.free());
+        }
+        catch (error) {
+            // A finalizer has no caller to throw to. The next call reports the poison.
+            if (explicit)
+                throw error;
+        }
+    }
+}
+// [spec:cg3:req:wasm.init]
+async function load(source) {
+    if (typeof source === "string" || source instanceof URL) {
+        const url = typeof source === "string" && URL.canParse(source) ? new URL(source) : source;
+        if (url instanceof URL && url.protocol === "file:")
+            return await readFile(url);
+        return checked(await fetch(url));
+    }
+    if (source instanceof Response)
+        return checked(source);
+    return source;
+}
+function checked(response) {
+    if (!response.ok) {
+        throw new Error(`${response.url || "the response"} answered HTTP ${response.status}`);
+    }
+    return response;
+}
+// Node's fetch cannot read file: URLs, so they are read with node:fs. The
+// specifier is a variable so that bundlers and type checkers do not follow it:
+// code that never passes a file URL never asks for node:fs.
+async function readFile(url) {
+    const specifier = "node:fs/promises";
+    const fs = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ /* webpackIgnore: true */ specifier));
+    return await fs.readFile(url);
+}

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Every code a {@link Cg3Error} can carry. Code may test `error.code` against
+ * these; they do not change between releases.
+ *
+ * From the wrapper:
+ * - `not-initialised`: a call came before `init()` had resolved.
+ * - `init-failed`: `init()` could not load, compile or start the module.
+ * - `poisoned`: the module trapped, for instance on a panic. Its memory cannot
+ *   be trusted after that, so every later call throws this without entering it.
+ * - `freed`: a call on a grammar after its `free()`.
+ *
+ * From the wrapper or the library, which `crates/cg3-wasm/src/error.rs` maps
+ * here:
+ * - `invalid-argument`: an argument or run option the package cannot use,
+ *   such as bytes that are not a `Uint8Array`, or an option it does not know.
+ * - `invalid-grammar`: bytes that are not a `.cg3b` the library reads. The
+ *   message is the library's.
+ * - `run-failed`: a run the library reports as failed, such as one that
+ *   reaches an `EXTERNAL` rule. The message is the library's. The grammar
+ *   stays usable.
+ */
+export declare const CG3_ERROR_CODES: readonly ["not-initialised", "init-failed", "poisoned", "freed", "invalid-argument", "invalid-grammar", "run-failed"];
+export type Cg3ErrorCode = (typeof CG3_ERROR_CODES)[number];
+/** An error from `@divvun/cg3`. `code` says what went wrong, in a form code can test. */
+export declare class Cg3Error extends Error {
+    readonly code: Cg3ErrorCode;
+    constructor(code: Cg3ErrorCode, message: string, options?: ErrorOptions);
+}
+/**
+ * The error for an object a glue call threw, or null when it is not one. The
+ * glue throws plain objects with `code` and `message`. It only sends the codes
+ * `crates/cg3-wasm/src/error.rs` lists, which a test there checks are listed
+ * here; a code from a mismatched build reads as `run-failed` and is named in
+ * the message.
+ */
+export declare function fromGlue(thrown: unknown): Cg3Error | null;
+/** The message of anything a caller might throw. */
+export declare function messageOf(error: unknown): string;

package/dist/errors.js

@@ -0,0 +1,65 @@
+// [spec:cg3:req:wasm.errors+1]
+/**
+ * Every code a {@link Cg3Error} can carry. Code may test `error.code` against
+ * these; they do not change between releases.
+ *
+ * From the wrapper:
+ * - `not-initialised`: a call came before `init()` had resolved.
+ * - `init-failed`: `init()` could not load, compile or start the module.
+ * - `poisoned`: the module trapped, for instance on a panic. Its memory cannot
+ *   be trusted after that, so every later call throws this without entering it.
+ * - `freed`: a call on a grammar after its `free()`.
+ *
+ * From the wrapper or the library, which `crates/cg3-wasm/src/error.rs` maps
+ * here:
+ * - `invalid-argument`: an argument or run option the package cannot use,
+ *   such as bytes that are not a `Uint8Array`, or an option it does not know.
+ * - `invalid-grammar`: bytes that are not a `.cg3b` the library reads. The
+ *   message is the library's.
+ * - `run-failed`: a run the library reports as failed, such as one that
+ *   reaches an `EXTERNAL` rule. The message is the library's. The grammar
+ *   stays usable.
+ */
+export const CG3_ERROR_CODES = [
+    "not-initialised",
+    "init-failed",
+    "poisoned",
+    "freed",
+    "invalid-argument",
+    "invalid-grammar",
+    "run-failed",
+];
+/** An error from `@divvun/cg3`. `code` says what went wrong, in a form code can test. */
+export class Cg3Error extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "Cg3Error";
+        this.code = code;
+    }
+}
+function isCg3ErrorCode(code) {
+    return CG3_ERROR_CODES.includes(code);
+}
+/**
+ * The error for an object a glue call threw, or null when it is not one. The
+ * glue throws plain objects with `code` and `message`. It only sends the codes
+ * `crates/cg3-wasm/src/error.rs` lists, which a test there checks are listed
+ * here; a code from a mismatched build reads as `run-failed` and is named in
+ * the message.
+ */
+export function fromGlue(thrown) {
+    if (typeof thrown !== "object" || thrown === null || thrown instanceof Error)
+        return null;
+    const code = Reflect.get(thrown, "code");
+    const message = Reflect.get(thrown, "message");
+    if (typeof code !== "string" || typeof message !== "string")
+        return null;
+    if (isCg3ErrorCode(code))
+        return new Cg3Error(code, message);
+    return new Cg3Error("run-failed", `${message} (the module sent the unknown code ${code})`);
+}
+/** The message of anything a caller might throw. */
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/glue.d.ts

@@ -0,0 +1,48 @@
+import type { ApplyResult, GrammarInfo } from "./grammar.ts";
+/** What the generated init function is given. The wrapper resolves URLs itself. */
+export type GlueInitInput = BufferSource | Response | WebAssembly.Module;
+/**
+ * What the module calls back into, from `crates/cg3-wasm/src/sink.rs`.
+ * Levels are numbers: 0 is off, then 1 error, 2 warn, 3 info, 4 debug, 5 trace.
+ * These calls arrive while the module is running, so none of them may throw:
+ * an exception would unwind through the module and leave it half run.
+ */
+export interface GlueSink {
+    /** One tracing event, which the module has already checked against the level. */
+    log(level: number, target: string, message: string): void;
+    /** A panic's message. The trap that ends the call follows at once. */
+    panic(message: string): void;
+}
+/**
+ * An object the glue hands out, which owns module memory until `free()`.
+ * wasm-bindgen also frees one from its own `FinalizationRegistry` when the
+ * object becomes unreachable, which the wrapper must never let happen after a
+ * trap; see `Core`.
+ */
+export interface GlueObject {
+    free(): void;
+}
+/** A grammar the glue holds, from `crates/cg3-wasm/src/grammar.rs`. */
+export interface GrammarGlue extends GlueObject {
+    /** A plain object the module builds. */
+    info(): GrammarInfo;
+    /**
+     * Runs the grammar on `input`. `options` is the JSON text of an
+     * `ApplyOptions` object; the module refuses a key it does not know. The
+     * result is a plain object the module builds.
+     */
+    apply(input: string, options: string): ApplyResult;
+}
+/** The exports of `crates/cg3-wasm`. */
+export interface Glue {
+    /** Instantiates the module. The generated glue keeps the instance it makes. */
+    default(options: {
+        module_or_path: GlueInitInput;
+    }): Promise<unknown>;
+    /** Starts the instance with the wrapper's sink and a log level. Called once, by `init()`. */
+    install(sink: GlueSink, level: number): void;
+    /** Sends events at `level` and above from here on, and nothing below it. */
+    setLogLevel(level: number): void;
+    version(): string;
+    readGrammar(bytes: Uint8Array): GrammarGlue;
+}

package/dist/glue.js

@@ -0,0 +1,7 @@
+// The generated wasm-bindgen glue, as the wrapper uses it. The generated
+// module hands most results back untyped; these types give them the shapes
+// the module builds, and tsc checks at build time that the generated module
+// satisfies them when binding.ts hands it to Core. Declaring them here also
+// lets the unit tests run the wrapper on a fake glue, and lets deno check the
+// wrapper on a checkout that has no build output.
+export {};

package/dist/grammar.d.ts

@@ -0,0 +1,105 @@
+import type { Core } from "./core.ts";
+import type { GrammarGlue } from "./glue.ts";
+import { Handle } from "./handle.ts";
+/**
+ * A stream format, as vislcg3's `--in-*` and `--out-*` options name it. The
+ * binary format is left out: a string cannot carry it.
+ */
+export type Format = "cg" | "niceline" | "apertium" | "fst" | "plain" | "jsonl";
+/**
+ * The options a run reads, each named after its vislcg3 long option in
+ * camelCase: `--num-windows 4` is `{ numWindows: 4 }`. An option whose value
+ * vislcg3 makes optional is `true` without one, as `--trace` is
+ * `{ trace: true }`. `input` and `output` stand for the `--in-*` and
+ * `--out-*` options. Numbers are whole numbers from 0 to 4294967295. The
+ * options a grammar sets with `CMDARGS` apply as they do in vislcg3.
+ */
+export interface ApplyOptions {
+    /** The input stream's format; `cg` when left out. */
+    input?: Format;
+    /** The output stream's format; `cg` when left out. */
+    output?: Format;
+    ordered?: boolean;
+    unsafe?: boolean;
+    sections?: string;
+    rules?: string;
+    rule?: string;
+    debugRules?: string;
+    verbose?: boolean | string;
+    noMappings?: boolean;
+    noCorrections?: boolean;
+    noBeforeSections?: boolean;
+    noSections?: boolean;
+    noAfterSections?: boolean;
+    trace?: boolean | string;
+    traceNameOnly?: boolean;
+    traceNoRemoved?: boolean;
+    traceEncl?: boolean;
+    deleted?: boolean;
+    singleRun?: boolean;
+    maxRuns?: number;
+    unicodeTags?: boolean;
+    uniqueTags?: boolean;
+    printIds?: boolean;
+    printDep?: boolean;
+    numWindows?: number;
+    alwaysSpan?: boolean;
+    softLimit?: number;
+    hardLimit?: number;
+    textDelimit?: boolean | string;
+    depDelimit?: boolean | string;
+    depAbsolute?: boolean;
+    depOriginal?: boolean;
+    depAllowLoops?: boolean;
+    depNoCrossing?: boolean;
+    noMagicReadings?: boolean;
+    noPassOrigin?: boolean;
+    splitMappings?: boolean;
+    showEndTags?: boolean;
+    noBreak?: boolean;
+}
+/** A run's output, and every warning and non-fatal error it logged, in order. */
+export interface ApplyResult {
+    output: string;
+    warnings: string[];
+}
+/** What vislcg3's verbose summary reports about a loaded grammar. */
+export interface GrammarInfo {
+    sections: number;
+    templates: number;
+    rules: number;
+    sets: number;
+    tags: number;
+    /** Rules no tag index can skip. */
+    rulesAny: number;
+    hasDependencyRules: boolean;
+    hasRelationRules: boolean;
+}
+/**
+ * A compiled grammar, loaded once and applied any number of times. It owns
+ * module memory: call `free()` when done with it, or declare it with `using`.
+ */
+export declare class Grammar extends Handle<GrammarGlue> {
+    private constructor();
+    /** What vislcg3's verbose summary reports about the grammar, as a plain object. */
+    info(): GrammarInfo;
+    /**
+     * Runs the grammar on `input`, as vislcg3 runs it on one standard input,
+     * and returns the output with every warning and non-fatal error the run
+     * logged. Each call is a run of its own. A run that fails throws
+     * `run-failed` with the library's message, and the grammar stays usable.
+     * An option it does not know throws `invalid-argument`.
+     */
+    apply(input: string, options?: ApplyOptions): ApplyResult;
+}
+export interface GrammarReader {
+    /**
+     * Loads a compiled grammar from the bytes of a `.cg3b`, as `cg-comp`
+     * writes it. The bytes are copied into the module and not kept. Bytes that
+     * are not a `.cg3b` the library reads throw `invalid-grammar`, with the
+     * library's message.
+     */
+    readGrammar(bytes: Uint8Array): Grammar;
+}
+/** A {@link GrammarReader} that loads into the module instance `core`. */
+export declare function grammarReader(core: Core): GrammarReader;

package/dist/grammar.js

@@ -0,0 +1,67 @@
+import { Cg3Error, messageOf } from "./errors.js";
+import { Handle } from "./handle.js";
+let wrap;
+/**
+ * A compiled grammar, loaded once and applied any number of times. It owns
+ * module memory: call `free()` when done with it, or declare it with `using`.
+ */
+export class Grammar extends Handle {
+    constructor(core, glue) {
+        super(core, glue);
+    }
+    static {
+        wrap = (core, glue) => new Grammar(core, glue);
+    }
+    // [spec:cg3:req:wasm.grammar-load+1]
+    /** What vislcg3's verbose summary reports about the grammar, as a plain object. */
+    info() {
+        return this.use((glue) => glue.info());
+    }
+    // [spec:cg3:req:wasm.parity+2]
+    // The input and options reach the module unchanged and the output comes
+    // back as the module wrote it, so a run gives what vislcg3 gives.
+    /**
+     * Runs the grammar on `input`, as vislcg3 runs it on one standard input,
+     * and returns the output with every warning and non-fatal error the run
+     * logged. Each call is a run of its own. A run that fails throws
+     * `run-failed` with the library's message, and the grammar stays usable.
+     * An option it does not know throws `invalid-argument`.
+     */
+    apply(input, options) {
+        return this.use((glue) => glue.apply(checkedInput(input), optionsJson(options)));
+    }
+}
+function checkedInput(input) {
+    if (typeof input !== "string") {
+        throw new Cg3Error("invalid-argument", `apply takes the input as a string, not ${typeof input}`);
+    }
+    return input;
+}
+/** The JSON text of `options`, which the module reads and checks key by key. */
+function optionsJson(options) {
+    if (options === undefined)
+        return "{}";
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        throw new Cg3Error("invalid-argument", "apply takes its options as an object");
+    }
+    try {
+        return JSON.stringify(options);
+    }
+    catch (error) {
+        throw new Cg3Error("invalid-argument", `the options cannot be read: ${messageOf(error)}`, {
+            cause: error,
+        });
+    }
+}
+// [spec:cg3:req:wasm.grammar-load+1]
+/** A {@link GrammarReader} that loads into the module instance `core`. */
+export function grammarReader(core) {
+    return {
+        readGrammar: (bytes) => core.call((glue) => {
+            if (!(bytes instanceof Uint8Array)) {
+                throw new Cg3Error("invalid-argument", "a grammar loads from the bytes of a .cg3b, as a Uint8Array");
+            }
+            return wrap(core, glue.readGrammar(bytes));
+        }),
+    };
+}

package/dist/handle.d.ts

@@ -0,0 +1,18 @@
+import type { Core } from "./core.ts";
+import type { GlueObject } from "./glue.ts";
+/**
+ * The base of every object that owns WebAssembly memory. `free()` and
+ * `[Symbol.dispose]()` release the memory, so a `using` declaration frees the
+ * object at the end of its block. Freeing twice does nothing, and any other
+ * call on a freed object throws `Cg3Error` with code `freed`. An object
+ * dropped without `free()` is released once it has been garbage collected.
+ */
+export declare abstract class Handle<G extends GlueObject> implements Disposable {
+    #private;
+    protected constructor(core: Core, glue: G);
+    /** Runs `f` on the glue object, with the module instance's call checks. */
+    protected use<T>(f: (glue: G) => T): T;
+    /** Releases the object's WebAssembly memory. Freeing twice does nothing. */
+    free(): void;
+    [Symbol.dispose](): void;
+}

package/dist/handle.js

@@ -0,0 +1,38 @@
+import { Cg3Error } from "./errors.js";
+// [spec:cg3:req:wasm.handle-lifetime]
+/**
+ * The base of every object that owns WebAssembly memory. `free()` and
+ * `[Symbol.dispose]()` release the memory, so a `using` declaration frees the
+ * object at the end of its block. Freeing twice does nothing, and any other
+ * call on a freed object throws `Cg3Error` with code `freed`. An object
+ * dropped without `free()` is released once it has been garbage collected.
+ */
+export class Handle {
+    #core;
+    #glue;
+    constructor(core, glue) {
+        this.#core = core;
+        this.#glue = glue;
+        core.adopt(this, glue);
+    }
+    /** Runs `f` on the glue object, with the module instance's call checks. */
+    use(f) {
+        return this.#core.call(() => {
+            const glue = this.#glue;
+            if (glue === null)
+                throw new Cg3Error("freed", `this ${this.constructor.name} was freed`);
+            return f(glue);
+        });
+    }
+    /** Releases the object's WebAssembly memory. Freeing twice does nothing. */
+    free() {
+        const glue = this.#glue;
+        if (glue === null)
+            return;
+        this.#glue = null;
+        this.#core.release(this, glue);
+    }
+    [Symbol.dispose]() {
+        this.free();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import type { InitSource } from "./core.ts";
+import type { Logger, LogLevel } from "./logging.ts";
+/**
+ * Loads and starts the package's WebAssembly module. Call it once and wait
+ * for it before anything else. With no argument it loads the `.wasm` file
+ * that ships beside the package. Calling it again returns the same promise.
+ */
+export declare function init(source?: InitSource): Promise<void>;
+/** The version of the cg3 library the package was built from, which is the package's own version. */
+export declare function version(): string;
+/**
+ * Sends the library's log events to `logger`. `null` puts back the default,
+ * which writes each event to the console method for its level. Whatever the
+ * logger, `apply` still returns its run's warnings.
+ */
+export declare function setLogger(logger: Logger | null): void;
+/**
+ * Logs events at `level` and the more severe levels; `off` logs nothing.
+ * The default is `warn`. The module never sends the levels below it.
+ */
+export declare function setLogLevel(level: LogLevel): void;
+export declare const readGrammar: (bytes: Uint8Array) => import("./grammar.ts").Grammar;
+export { Grammar } from "./grammar.ts";
+export type { ApplyOptions, ApplyResult, Format, GrammarInfo } from "./grammar.ts";
+export { Cg3Error } from "./errors.ts";
+export type { Cg3ErrorCode } from "./errors.ts";
+export type { InitSource } from "./core.ts";
+export type { LogEvent, Logger, LogLevel } from "./logging.ts";