@wasmedia/wenblend 0.1.0

package/src/staging.ts

@@ -0,0 +1,173 @@
+/**
+ * How a run's files reach the tool and come back.
+ *
+ * runTool() has one flow: stage, callMain, collect, release. This interface
+ * is what varies. stageBuffers is the MEMFS path every caller used before file
+ * mode existed, and its behaviour is unchanged. stageFiles (file mode) mounts
+ * files through wopfs.
+ */
+
+import type { FileInput, InputImage, LoaderOptions, OutputDir, WasmModule, WrittenFile } from "./types.js";
+import { createWorkDir, stageInputs, collectOutputs, cleanWorkDir, nextWorkDirName, toBytes } from "./filesystem.js";
+import { tiffPixelCount, tiffPixelCountAt, type ReadAt } from "./tiff-header.js";
+import { loadWopfs, type WopfsCommittedFile } from "./wopfs.js";
+
+export interface Staging {
+  /** The directory the tool runs in (its cwd). */
+  readonly workDir: string;
+  readonly inputNames: ReadonlySet<string>;
+  /** Everything the run created. Buffer mode: bytes. File mode: committed files. */
+  collect(): Promise<Map<string, Uint8Array | WrittenFile>>;
+  /** Total input pixels, for OutOfMemoryError. Callable after release(). */
+  pixelCount(): Promise<number | undefined>;
+  /** Idempotent. runTool calls it in a finally on every path. */
+  release(): Promise<void>;
+}
+
+export function stageBuffers(module: WasmModule, inputs: InputImage[]): Staging {
+  const workDir = createWorkDir(module);
+  const inputNames = stageInputs(module, workDir, inputs);
+  let released = false;
+  return {
+    workDir,
+    inputNames,
+    async collect() {
+      return collectOutputs(module, workDir, inputNames);
+    },
+    async pixelCount() {
+      // With no inputs no header states a count, so none is known; 0 would be a claim.
+      if (inputs.length === 0) return undefined;
+      let total = 0;
+      for (const input of inputs) {
+        const n = tiffPixelCount(toBytes(input.data));
+        if (n === undefined) return undefined;
+        total += n;
+      }
+      return total;
+    },
+    async release() {
+      if (released) return;
+      released = true;
+      // The instance is discarded after this call (never reused, per
+      // createInstance's contract), so there is no previous cwd to restore.
+      cleanWorkDir(module, workDir);
+    },
+  };
+}
+
+/** True for `{ name, file }`, the file-mode input shape. */
+export function isFileInput(x: unknown): x is FileInput {
+  return typeof x === "object" && x !== null && "file" in x && "name" in x && !("data" in x);
+}
+
+// getopt_long accepts any unambiguous prefix of a long option. Over-counting
+// costs an empty pre-opened file; under-counting fails the run, so a prefix
+// match errs on the generous side.
+const longName = (arg: string) => (arg.startsWith("--") ? arg.slice(2).split("=", 1)[0]! : "");
+const names = (argv: readonly string[], option: string) =>
+  argv.some((arg) => { const n = longName(arg); return n.length >= 2 && option.startsWith(n); });
+
+/**
+ * How many files a run can create, from its argv: the -o output, plus
+ * --visualize's image, plus a soft and a hard mask per input for
+ * --save-mask(s). enblend and enfuse create no temporary files (spec,
+ * finding 2). --load-mask(s) reads, so it adds nothing here.
+ */
+export function scratchFor(argv: readonly string[], inputCount: number): number {
+  let n = 1;
+  if (names(argv, "visualize")) n += 1;
+  if (names(argv, "save-masks")) n += 2 * inputCount;
+  return n;
+}
+
+/** A reader for the pixel count: a byte range of a file, without reading the rest. */
+function readerFor(file: FileSystemFileHandle | string): ReadAt {
+  if (typeof file === "string") {
+    return async (offset, length) => {
+      // A variable specifier: the browser build never resolves node:fs.
+      const specifier = "node:fs/promises";
+      const { open } = await import(/* @vite-ignore */ specifier);
+      const handle = await open(file, "r");
+      try {
+        const buffer = new Uint8Array(length);
+        const { bytesRead } = await handle.read(buffer, 0, length, offset);
+        return buffer.subarray(0, bytesRead);
+      } finally {
+        await handle.close();
+      }
+    };
+  }
+  return async (offset, length) =>
+    new Uint8Array(await (await file.getFile()).slice(offset, offset + length).arrayBuffer());
+}
+
+/**
+ * Turn what wopfs committed into a WrittenFile. On the main thread wopfs
+ * falls back to MEMFS, which returns bytes and ignores outputDir. Write those
+ * into outputDir here, so file mode hands back a file in every environment.
+ */
+async function toWrittenFile(c: WopfsCommittedFile, outputDir: OutputDir): Promise<WrittenFile> {
+  if (c.handle) return { name: c.path, file: c.handle, size: c.size };
+  if (c.hostPath) return { name: c.path, file: c.hostPath, size: c.size };
+  if (c.bytes && typeof outputDir !== "string") {
+    // Check before creating the file, so a failure leaves no empty file behind.
+    if (typeof FileSystemFileHandle === "undefined" || !("createWritable" in FileSystemFileHandle.prototype)) {
+      throw new Error("file mode on this thread needs FileSystemFileHandle.createWritable; run it in a dedicated worker instead");
+    }
+    const handle = await outputDir.getFileHandle(c.path, { create: true });
+    const writable = await handle.createWritable();
+    await writable.write(c.bytes as Uint8Array<ArrayBuffer>);
+    await writable.close();
+    return { name: c.path, file: handle, size: c.bytes.length };
+  }
+  throw new Error(`wopfs committed "${c.path}" with neither a file nor bytes`);
+}
+
+/**
+ * Mount the run's files through wopfs. Everything is opened here, before
+ * callMain, because the tool cannot await. The pool is strict: spilling
+ * would put new files back in memory and defeat the point (spec, Decisions).
+ */
+export async function stageFiles(
+  module: WasmModule,
+  inputs: FileInput[],
+  outputDir: OutputDir,
+  argv: readonly string[],
+  options?: LoaderOptions,
+): Promise<Staging> {
+  const wopfs = await loadWopfs(options);
+  const workDir = nextWorkDirName();
+  const mount = await wopfs.mountFiles(module, workDir, {
+    inputs: Object.fromEntries(inputs.map((i) => [i.name, i.file])),
+    outputDir,
+    scratch: scratchFor(argv, inputs.length),
+    onExhausted: "strict",
+  });
+  let released = false;
+  return {
+    workDir,
+    inputNames: new Set(inputs.map((i) => i.name)),
+    async collect() {
+      const out = new Map<string, Uint8Array | WrittenFile>();
+      for (const c of await mount.commit()) out.set(c.path, await toWrittenFile(c, outputDir));
+      return out;
+    },
+    async pixelCount() {
+      if (inputs.length === 0) return undefined;
+      let total = 0;
+      for (const input of inputs) {
+        const n = await tiffPixelCountAt(readerFor(input.file));
+        if (n === undefined) return undefined;
+        total += n;
+      }
+      return total;
+    },
+    async release() {
+      if (released) return;
+      released = true;
+      // runTool ran the tool inside the mount; wopfs >= 0.2.0 moves the cwd
+      // out before unmounting (https://gitlab.com/wasmedia/wopfs/-/work_items/2).
+      await mount.release();
+    },
+  };
+}

package/src/tiff-header.ts

@@ -0,0 +1,94 @@
+/**
+ * Pixel count of a TIFF, read from its header and image directories only.
+ *
+ * One walker serves both callers: buffer mode, which has the whole file's
+ * bytes, and file mode, where the file sits in OPFS or on disk and only the
+ * few hundred bytes the walk needs should be read. The walker is a generator
+ * that yields the byte ranges it needs; tiffPixelCount drives it from a byte
+ * array, and tiffPixelCountAt from an async reader.
+ */
+
+type Need = { offset: number; length: number };
+
+/** A random-access reader. A short or empty result means past the end. */
+export type ReadAt = (offset: number, length: number) => Promise<Uint8Array>;
+
+const view = (b: Uint8Array) => new DataView(b.buffer, b.byteOffset, b.byteLength);
+
+/**
+ * Sum of width x height over every image directory, from the ImageWidth and
+ * ImageLength tags. Undefined for anything that cannot be read with certainty:
+ * not a classic TIFF (BigTIFF included), truncated, a cycle, or a directory
+ * missing either tag. Never a guess.
+ */
+function* walk(): Generator<Need, number | undefined, Uint8Array | undefined> {
+  const head = yield { offset: 0, length: 8 };
+  if (!head || head.length < 8) return undefined;
+  const hv = view(head);
+  const order = hv.getUint16(0);
+  if (order !== 0x4949 && order !== 0x4d4d) return undefined;
+  const le = order === 0x4949;
+  if (hv.getUint16(2, le) !== 42) return undefined;
+  let offset = hv.getUint32(4, le);
+  let total = 0;
+  const visited = new Set<number>();
+  while (offset !== 0) {
+    if (visited.has(offset)) return undefined;
+    visited.add(offset);
+    const countBytes = yield { offset, length: 2 };
+    if (!countBytes || countBytes.length < 2) return undefined;
+    const count = view(countBytes).getUint16(0, le);
+    const size = count * 12 + 4;
+    const dir = yield { offset: offset + 2, length: size };
+    if (!dir || dir.length < size) return undefined;
+    const dv = view(dir);
+    let width: number | undefined;
+    let height: number | undefined;
+    for (let i = 0; i < count; i++) {
+      const entry = i * 12;
+      const tag = dv.getUint16(entry, le);
+      if (tag !== 256 && tag !== 257) continue;
+      const type = dv.getUint16(entry + 2, le);
+      // SHORT (3) or LONG (4), exactly one value, stored in the entry itself.
+      // Any other count is malformed; reading it as one value would misreport.
+      const values = dv.getUint32(entry + 4, le);
+      const value = values !== 1 ? undefined
+        : type === 3 ? dv.getUint16(entry + 8, le)
+        : type === 4 ? dv.getUint32(entry + 8, le)
+        : undefined;
+      if (tag === 256) width = value;
+      else height = value;
+    }
+    if (width === undefined || height === undefined) return undefined;
+    total += width * height;
+    offset = dv.getUint32(count * 12, le);
+  }
+  return total;
+}
+
+/** The pixel count of a TIFF held in memory. */
+export function tiffPixelCount(bytes: Uint8Array): number | undefined {
+  const it = walk();
+  let step = it.next();
+  while (!step.done) {
+    const { offset, length } = step.value;
+    step = it.next(bytes.subarray(offset, offset + length));
+  }
+  return step.value;
+}
+
+/** The pixel count of a TIFF read through `readAt`, fetching only what the walk needs. */
+export async function tiffPixelCountAt(readAt: ReadAt): Promise<number | undefined> {
+  const it = walk();
+  let step = it.next();
+  while (!step.done) {
+    let chunk: Uint8Array | undefined;
+    try {
+      chunk = await readAt(step.value.offset, step.value.length);
+    } catch {
+      chunk = undefined;
+    }
+    step = it.next(chunk);
+  }
+  return step.value;
+}

package/src/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Shared types for wenblend.
+ *
+ * Only three C symbols are exported by the wasm modules (`_malloc`,
+ * `_free`, `_main`), so `WasmModule` describes the Emscripten runtime
+ * surface rather than a bound C API.
+ */
+
+/** Emscripten MEMFS node stat. */
+export interface FSStat {
+  size: number;
+  mode: number;
+}
+
+/** The subset of Emscripten's FS we use. */
+export interface EmscriptenFS {
+  mkdir(path: string): void;
+  chdir(path: string): void;
+  cwd(): string;
+  writeFile(path: string, data: Uint8Array): void;
+  readFile(path: string, opts?: { encoding?: "binary" | "utf8" }): Uint8Array;
+  readdir(path: string): string[];
+  unlink(path: string): void;
+  rmdir(path: string): void;
+  stat(path: string): FSStat;
+  analyzePath(path: string): { exists: boolean };
+}
+
+/** The Emscripten module surface this wrapper relies on. */
+export interface WasmModule {
+  FS: EmscriptenFS;
+  callMain(argv: string[]): number | undefined;
+  print?: (text: string) => void;
+  printErr?: (text: string) => void;
+  _malloc(size: number): number;
+  _free(ptr: number): void;
+  HEAPU8: Uint8Array;
+}
+
+/** A named input image. Callers control the names their argv references. */
+export interface InputImage {
+  name: string;
+  data: Uint8Array | ArrayBuffer;
+}
+
+/** The result of one CLI invocation. */
+export interface CLIResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  /** Files present in the work directory that were not inputs. */
+  outputFiles: Map<string, Uint8Array>;
+}
+
+/** A file a file-mode run committed to its output directory. */
+export interface WrittenFile {
+  name: string;
+  /** The committed file: an OPFS handle in a browser, a host path under Node. */
+  file: FileSystemFileHandle | string;
+  size: number;
+}
+
+/** An input that stays in a file: an OPFS handle in a browser, a host path under Node. */
+export interface FileInput {
+  name: string;
+  file: FileSystemFileHandle | string;
+}
+
+/** Where file mode commits outputs: an OPFS directory, or a host directory under Node. */
+export type OutputDir = FileSystemDirectoryHandle | string;
+
+/** A file-mode CLI result: outputs are committed files, not bytes. */
+export interface CLIFileResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  /** Committed outputs by name. Empty unless the tool exited 0. */
+  written: Map<string, WrittenFile>;
+}
+
+export type FileModeOptions = LoaderOptions & { outputDir: OutputDir };
+
+/** Options common to both tools. */
+export interface CommonOptions {
+  /** Output filename inside MEMFS. Defaults to `output.tif`. */
+  output?: string;
+  /** Extra argv appended verbatim, exactly as typed on a command line. */
+  args?: string[];
+}
+
+export type BlendOptions = CommonOptions;
+export type FuseOptions = CommonOptions;
+
+/** Progress phases reported by the loader. */
+export type LoadPhase = "loading" | "initializing" | "ready";
+
+export interface LoaderOptions {
+  /** Override the module URL (for bundlers or custom hosting). */
+  wasmPath?: string;
+  /**
+   * Where file mode loads @wasmedia/wopfs from. The default imports
+   * "@wasmedia/wopfs" itself, which works under Node and with a bundler. A
+   * browser without a bundler (plain ES modules, workers) passes the URL of
+   * wopfs's dist/index.js.
+   */
+  wopfsPath?: string;
+  onProgress?: (phase: LoadPhase) => void;
+}
+
+/** A non-zero exit from enblend or enfuse. Carries the tool's own diagnostics. */
+export class EnblendError extends Error {
+  readonly exitCode: number;
+  readonly stderr: string;
+
+  constructor(message: string, exitCode: number, stderr: string) {
+    super(message);
+    this.name = "EnblendError";
+    this.exitCode = exitCode;
+    this.stderr = stderr;
+  }
+}
+
+/**
+ * Allocation failure.
+ *
+ * Nothing bounds memory in this port: enblend's image cache was removed
+ * upstream in 4.2.1, so there is no spill-to-disk and no graceful
+ * degradation. `ALLOW_MEMORY_GROWTH=1` with `MAXIMUM_MEMORY=4GB` is the
+ * only ceiling and browsers allocate less in practice. This is the
+ * runtime signal for the documented ceiling in `docs/building.md`.
+ */
+export class OutOfMemoryError extends Error {
+  /**
+   * Total input pixels, read from the inputs' TIFF headers (every image
+   * directory of every input). Undefined when any input's header could not
+   * be read with certainty; it is never estimated from byte counts, which
+   * for compressed TIFFs can be off several-fold.
+   */
+  readonly pixels: number | undefined;
+  /** The tool's stderr, including its own `out of memory` line. */
+  readonly stderr: string;
+
+  constructor(pixels: number | undefined, stderr = "") {
+    super(
+      `Out of memory${pixels === undefined ? "" : ` blending ${pixels} input pixels`}. ` +
+        `This port has no image cache, so memory scales with total input area. ` +
+        `See the measured ceiling in docs/building.md.`,
+    );
+    this.name = "OutOfMemoryError";
+    this.pixels = pixels;
+    this.stderr = stderr;
+  }
+}

package/src/wopfs.ts

@@ -0,0 +1,70 @@
+/**
+ * The slice of @wasmedia/wopfs that file mode uses, and its lazy loader.
+ *
+ * The types are declared here structurally rather than imported, so a
+ * consumer who never uses file mode needs neither the package nor its type
+ * declarations. Nothing else in src/ imports wopfs; the package is loaded
+ * on the first file-mode call, the way each tool's module is loaded on its
+ * first use.
+ */
+
+import type { LoaderOptions } from "./types.js";
+
+export interface WopfsCommittedFile {
+  path: string;
+  size: number;
+  handle?: FileSystemFileHandle;
+  hostPath?: string;
+  bytes?: Uint8Array;
+}
+
+export interface WopfsMount {
+  readonly backend: "opfs" | "node" | "memfs";
+  commit(): Promise<WopfsCommittedFile[]>;
+  release(): Promise<void>;
+}
+
+export interface WopfsMountOptions {
+  inputs?: Record<string, FileSystemFileHandle | Uint8Array | Blob | string>;
+  outputDir?: FileSystemDirectoryHandle | string;
+  scratch?: number;
+  onExhausted?: "spill" | "strict";
+  backend?: "opfs" | "node" | "memfs" | "auto";
+}
+
+export interface WopfsModule {
+  mountFiles(module: unknown, mountpoint: string, options?: WopfsMountOptions): Promise<WopfsMount>;
+}
+
+const DEFAULT_SPECIFIER = "@wasmedia/wopfs";
+
+// The default is a LITERAL import so a bundler resolves and code-splits it (it
+// stays lazy: nothing evaluates it until the first file-mode call) and Node
+// resolves it from node_modules. An explicit wopfsPath is a URL the bundler
+// cannot know, so it goes through a variable specifier.
+let importer: (specifier: string) => Promise<WopfsModule> = (specifier) =>
+  (specifier === DEFAULT_SPECIFIER
+    ? import("@wasmedia/wopfs")
+    : import(/* @vite-ignore */ specifier)) as Promise<WopfsModule>;
+const cache = new Map<string, Promise<WopfsModule>>();
+
+/** Load wopfs once per specifier. A failed load is not cached, so a retry can succeed. */
+export function loadWopfs(options?: LoaderOptions): Promise<WopfsModule> {
+  const specifier = options?.wopfsPath ?? DEFAULT_SPECIFIER;
+  let loading = cache.get(specifier);
+  if (!loading) {
+    loading = importer(specifier).catch((e: unknown) => {
+      cache.delete(specifier);
+      const why = e instanceof Error ? e.message : String(e);
+      throw new Error(`file mode needs @wasmedia/wopfs, which could not be loaded from "${specifier}": ${why}`);
+    });
+    cache.set(specifier, loading);
+  }
+  return loading;
+}
+
+/** Test seam: replace the importer. Clears the cache. */
+export function __setWopfsLoader(fn: (specifier: string) => Promise<WopfsModule>): void {
+  importer = fn;
+  cache.clear();
+}

package/src/worker.ts

@@ -0,0 +1,31 @@
+/**
+ * Dedicated Web Worker entry — the package's `./worker` export.
+ *
+ * Blending is CPU-bound and single-threaded (OpenMP is off), so it
+ * blocks whatever thread it runs on. Running it in a worker keeps the
+ * page responsive.
+ *
+ * This is the ONLY module in the package with an import-time side
+ * effect: loaded inside a worker, it registers a `message` listener.
+ * The main entry (`src/index.ts`) re-exports the handler from
+ * `./handler.js`, never from here, so importing the library inside a
+ * consumer's own worker attaches nothing. package.json's `sideEffects`
+ * field names this file alone so bundlers know the difference.
+ */
+
+import { handleMessage, isWorkerScope, type WorkerRequest } from "./handler.js";
+
+export { handleMessage, isWorkerScope, type WorkerRequest, type WorkerResponse } from "./handler.js";
+
+// Only register when actually running inside a worker, so importing this
+// entry in a test or on a main thread is harmless.
+if (isWorkerScope()) {
+  self.addEventListener("message", (event: MessageEvent<WorkerRequest>) => {
+    void handleMessage(event.data).then((response) => {
+      // Transfer the output buffer rather than copying it (buffer mode only).
+      const transfer = response.result && response.result instanceof Uint8Array ? [response.result.buffer] : [];
+      (self as unknown as { postMessage: (m: unknown, t: Transferable[]) => void })
+        .postMessage(response, transfer as Transferable[]);
+    });
+  });
+}

package/types/wasm.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Types for the raw Emscripten glue, exported as `@wasmedia/wenblend/wasm/enblend`
+ * and `@wasmedia/wenblend/wasm/enfuse`. Each default-exports its tool's module
+ * factory. Prefer `createInstance()`, which also supplies the cached compiled
+ * module; calling the factory directly compiles the .wasm on every call, and
+ * `print`/`printErr` must be passed in the config object (assigning them after
+ * construction has no effect).
+ */
+import type { ModuleFactory } from "../dist/loader.js";
+
+declare const factory: ModuleFactory;
+export default factory;