bgcut 0.1.0-beta.0

package/README.md

@@ -0,0 +1,106 @@
+# bgcut
+
+Local background removal with WebGPU as the primary execution path.
+
+The browser implementation uses a pinned BiRefNet Lite 512 ONNX model with ONNX Runtime WebGPU, shares one application-owned `GPUDevice` with TypeGPU, captures the inference graph, and exports transparent PNGs at the source image resolution.
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run dev
+```
+
+Run the full project checks with:
+
+```sh
+bun run check
+```
+
+That runs oxlint, TypeScript, product tests, the production build, and an npm package dry run. Vendored anti-slop maintainer tests are excluded from Bun's project-level test discovery through `bunfig.toml` because Oxlint `RuleTester` expects its upstream Node/tsx environment.
+
+## Browser pipeline
+
+```text
+image
+  -> source decode
+  -> TypeGPU resize + ImageNet normalization on the shared WebGPU device
+  -> BiRefNet Lite ONNX inference with WebGPU graph capture
+  -> GPU output readback
+  -> alpha matte
+  -> source-resolution compositing
+  -> transparent PNG
+```
+
+The model artifact is verified by exact byte count and SHA-256 during production builds. Source images never go to an inference backend.
+
+## Native CLI
+
+The first npm release is published on the `beta` tag. The CLI currently runs on Bun, so install Bun before installing or invoking `bgcut`.
+
+Install the beta globally with npm:
+
+```sh
+npm install -g bgcut@beta
+```
+
+Or with Bun:
+
+```sh
+bun add -g bgcut@beta
+```
+
+For a one-off run without a global install:
+
+```sh
+bunx bgcut@beta photo.jpg
+```
+
+The canonical command is `bgcut`:
+
+```sh
+bgcut photo.jpg
+bgcut photo.jpg --png
+bgcut photo.jpg -png
+bgcut photo.jpg --webp
+bgcut photo.jpg -webp -o portrait.webp
+bgcut photo.jpg -o portrait.png
+```
+
+From a source checkout, `bun run cli -- ...` runs the same entrypoint without installing the package binary.
+
+The format itself is the option; there is deliberately no `--format png` syntax. PNG is the default. WebP is encoded losslessly. JPG/JPEG is supported, but because JPEG has no alpha channel it is flattened onto white.
+
+The CLI uses the same validated ONNX model and shared normalization/matte functions. It tries native ONNX Runtime WebGPU in automatic mode and falls back to native CPU execution if WebGPU session creation is unavailable. Use `-gpu`/`--gpu` or `-cpu`/`--cpu` to require one engine while validating the native path. The selected engine is printed after each run.
+
+The CLI does not launch Chromium and does not upload the input image. It caches the exact validated model in the operating system's user cache directory and verifies the model before use.
+
+## BG0 comparison
+
+After this build removes a background, the browser result uses a draggable comparison slider rather than two independent panes. By default it compares the original image with this build's result.
+
+Use **Load BG0 output** to select a BG0 result from disk. The file stays local. The comparison requires the BG0 image to have the same width and height as this build's output so the two results remain pixel-aligned while dragging the divider.
+
+This comparison is intended for local acceptance of hair, fur, whiskers, thin edges, holes, and semi-transparent boundaries. It is a visual inspection tool, not a substitute for numeric matte regression tests.
+
+## Direction
+
+Local execution alone is not a differentiator from projects such as BG0. The intended differentiation is lower-level ownership of the GPU pipeline and the editing/refinement capabilities that ownership makes possible. Performance and output-quality claims must be benchmarked rather than assumed.
+
+The target is a GPU-native cutout editor rather than only a one-shot background remover. Near-term work includes stronger job/cancellation APIs, quality refinement, non-destructive restore/erase editing, compatibility fallback, persistence, and benchmark coverage.
+
+See [`IMPROVEMENTS.md`](IMPROVEMENTS.md) for the prioritized roadmap, competitive baseline, benchmark plan, architecture direction, and exact manual-acceptance baseline.
+
+## Model
+
+- Model: `studioludens/birefnet-lite-512`
+- Revision: `4a3c40c36c94093cc1e724d9ea428b8fa4b57dc7`
+- Validated runtime artifact: `birefnet-lite-512-ort-basic-webgpu-v2.onnx`
+- Artifact size: `195,872,736` bytes
+- SHA-256: `4461109672dda07a054892aef076b5fcc5fc40bbc91f51a357a7593c7f45ad9c`
+- Inference size: 512×512
+- Export size: original source dimensions
+
+## Privacy
+
+Source images, decoded pixels, masks, and generated outputs stay on the user's machine. The model is downloaded from the pinned release artifact; source images are not sent there or to an application inference backend.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "bgcut",
+  "version": "0.1.0-beta.0",
+  "description": "Local background removal CLI with native WebGPU and CPU fallback.",
+  "type": "module",
+  "packageManager": "bun@1.4.2",
+  "bin": {
+    "bgcut": "src/cli/main.ts"
+  },
+  "files": [
+    "src/cli/alpha-mask.ts",
+    "src/cli/args.ts",
+    "src/cli/main.ts",
+    "src/cli/model-cache.ts",
+    "src/cli/runtime.ts",
+    "src/engine/errors.ts",
+    "src/engine/image.ts",
+    "src/engine/matte.ts",
+    "src/engine/model-config.ts",
+    "src/engine/preprocess.ts",
+    "src/shared/model-file.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jhomra21/bgremove.git"
+  },
+  "homepage": "https://github.com/jhomra21/bgremove#readme",
+  "bugs": {
+    "url": "https://github.com/jhomra21/bgremove/issues"
+  },
+  "keywords": [
+    "background-removal",
+    "image-processing",
+    "webgpu",
+    "onnx",
+    "cli",
+    "local-ai"
+  ],
+  "publishConfig": {
+    "tag": "beta"
+  },
+  "scripts": {
+    "dev": "vite",
+    "cli": "bun run src/cli/main.ts",
+    "model:prepare": "bun run scripts/prepare-model.ts",
+    "model:verify-dist": "bun run scripts/verify-model.ts",
+    "build": "bun run model:prepare && vite build && bun run model:verify-dist",
+    "preview": "vite preview",
+    "lint": "oxlint .",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "package:dry-run": "npm pack --dry-run",
+    "package:smoke": "bun run scripts/package-smoke.ts",
+    "check": "bun run lint && bun run typecheck && bun run test && bun run build && bun run package:dry-run && bun run package:smoke"
+  },
+  "dependencies": {
+    "effect": "3.22.2",
+    "onnxruntime-node": "1.30.0",
+    "sharp": "0.35.4"
+  },
+  "devDependencies": {
+    "@oxlint/plugins": "1.83.0",
+    "@solidjs/vite-plugin": "3.0.0-next.43",
+    "@solidjs/web": "2.0.0-rc.8",
+    "@types/bun": "1.4.2",
+    "@typescript/lib-dom": "npm:@types/web@0.0.356",
+    "onnxruntime-web": "1.30.0",
+    "oxlint": "1.83.0",
+    "solid-js": "2.0.0-rc.8",
+    "typegpu": "0.12.5",
+    "typescript": "7.0.2",
+    "vite": "8.3.0"
+  }
+}

package/src/cli/alpha-mask.ts

@@ -0,0 +1,28 @@
+export const compositeAlphaMask = (
+  rgba: Uint8Array,
+  mask: Uint8Array,
+  maskChannels: number,
+): void => {
+  if (!Number.isInteger(maskChannels) || maskChannels < 1) {
+    throw new Error(`Mask channel count must be a positive integer; received ${maskChannels}.`);
+  }
+
+  if (rgba.length % 4 !== 0) {
+    throw new Error(`RGBA byte length must be divisible by 4; received ${rgba.length}.`);
+  }
+
+  const pixelCount = rgba.length / 4;
+  const requiredMaskBytes = pixelCount * maskChannels;
+
+  if (mask.length < requiredMaskBytes) {
+    throw new Error(`Mask contains ${mask.length} bytes; expected at least ${requiredMaskBytes}.`);
+  }
+
+  for (let pixelIndex = 0; pixelIndex < pixelCount; pixelIndex += 1) {
+    const rgbaAlphaIndex = pixelIndex * 4 + 3;
+    const maskIndex = pixelIndex * maskChannels;
+    const maskAlpha = mask[maskIndex];
+
+    rgba[rgbaAlphaIndex] = Math.round((rgba[rgbaAlphaIndex] * maskAlpha) / 255);
+  }
+};

package/src/cli/args.ts

@@ -0,0 +1,192 @@
+import { Data, Effect } from "effect";
+import { dirname, extname, join, parse } from "node:path";
+
+export type CliFormat = "png" | "webp" | "jpg";
+
+export type CliEngine = "auto" | "gpu" | "cpu";
+
+export type CliOptions = {
+  readonly inputPath: string;
+  readonly outputPath: string;
+  readonly format: CliFormat;
+  readonly engine: CliEngine;
+};
+
+export type ParsedCli =
+  | { readonly kind: "help" }
+  | { readonly kind: "run"; readonly options: CliOptions };
+
+export class CliArgumentError extends Data.TaggedError("CliArgumentError")<{
+  readonly message: string;
+}> {}
+
+const formatFlags = new Map<string, CliFormat>([
+  ["--png", "png"],
+  ["-png", "png"],
+  ["--webp", "webp"],
+  ["-webp", "webp"],
+  ["--jpg", "jpg"],
+  ["-jpg", "jpg"],
+  ["--jpeg", "jpg"],
+  ["-jpeg", "jpg"],
+]);
+
+const engineFlags = new Map<string, CliEngine>([
+  ["--gpu", "gpu"],
+  ["-gpu", "gpu"],
+  ["--cpu", "cpu"],
+  ["-cpu", "cpu"],
+]);
+
+const formatFromExtension = (path: string): CliFormat | undefined => {
+  const extension = extname(path).toLowerCase();
+
+  if (extension === ".png") {
+    return "png";
+  }
+
+  if (extension === ".webp") {
+    return "webp";
+  }
+
+  if (extension === ".jpg" || extension === ".jpeg") {
+    return "jpg";
+  }
+
+  return undefined;
+};
+
+const extensionForFormat = (format: CliFormat): string => `.${format}`;
+
+const defaultOutputPath = (inputPath: string, format: CliFormat): string => {
+  const parsed = parse(inputPath);
+  const baseName = parsed.name.length > 0 ? parsed.name : "image";
+
+  return join(dirname(inputPath), `${baseName}-nobg${extensionForFormat(format)}`);
+};
+
+const resolveOutputPath = (
+  inputPath: string,
+  requestedOutput: string | undefined,
+  requestedFormat: CliFormat | undefined,
+): Effect.Effect<{ readonly outputPath: string; readonly format: CliFormat }, CliArgumentError> =>
+  Effect.gen(function* () {
+    if (requestedOutput === undefined) {
+      const format = requestedFormat ?? "png";
+
+      return { outputPath: defaultOutputPath(inputPath, format), format };
+    }
+
+    const extension = extname(requestedOutput);
+    const outputFormat = formatFromExtension(requestedOutput);
+
+    if (extension.length > 0 && outputFormat === undefined) {
+      return yield* new CliArgumentError({
+        message: `Unsupported output extension "${extension}". Use PNG, WebP, JPG, or JPEG.`,
+      });
+    }
+
+    if (requestedFormat !== undefined && outputFormat !== undefined && requestedFormat !== outputFormat) {
+      return yield* new CliArgumentError({
+        message: `Output path "${requestedOutput}" conflicts with the requested --${requestedFormat} format.`,
+      });
+    }
+
+    const format = requestedFormat ?? outputFormat ?? "png";
+
+    const outputPath = extension.length === 0
+      ? `${requestedOutput}${extensionForFormat(format)}`
+      : requestedOutput;
+
+    return { outputPath, format };
+  });
+
+export const parseCliArgs = (args: readonly string[]): Effect.Effect<ParsedCli, CliArgumentError> =>
+  Effect.gen(function* () {
+    let inputPath: string | undefined;
+    let outputPath: string | undefined;
+    let format: CliFormat | undefined;
+    let engine: CliEngine = "auto";
+
+    for (let index = 0; index < args.length; index += 1) {
+      const argument = args[index];
+
+      if (argument === "--") {
+        continue;
+      }
+
+      if (argument === "-h" || argument === "--help") {
+        return { kind: "help" };
+      }
+
+      if (argument === "--format" || argument === "-f") {
+        return yield* new CliArgumentError({
+          message: "Use the format itself as a flag: --png, --webp, --jpg, -png, -webp, or -jpg.",
+        });
+      }
+
+      if (argument === "-o" || argument === "--output") {
+        const next = args[index + 1];
+
+        if (next === undefined || next.startsWith("-")) {
+          return yield* new CliArgumentError({ message: `${argument} requires an output path.` });
+        }
+
+        if (outputPath !== undefined) {
+          return yield* new CliArgumentError({ message: "Only one output path can be specified." });
+        }
+
+        outputPath = next;
+        index += 1;
+        continue;
+      }
+
+      const requestedFormat = formatFlags.get(argument);
+
+      if (requestedFormat !== undefined) {
+        if (format !== undefined && format !== requestedFormat) {
+          return yield* new CliArgumentError({ message: "Only one output format can be specified." });
+        }
+
+        format = requestedFormat;
+        continue;
+      }
+
+      const requestedEngine = engineFlags.get(argument);
+
+      if (requestedEngine !== undefined) {
+        if (engine !== "auto" && engine !== requestedEngine) {
+          return yield* new CliArgumentError({ message: "Choose either GPU or CPU execution, not both." });
+        }
+
+        engine = requestedEngine;
+        continue;
+      }
+
+      if (argument.startsWith("-")) {
+        return yield* new CliArgumentError({ message: `Unknown option "${argument}".` });
+      }
+
+      if (inputPath !== undefined) {
+        return yield* new CliArgumentError({ message: "Only one input image can be processed per command for now." });
+      }
+
+      inputPath = argument;
+    }
+
+    if (inputPath === undefined) {
+      return yield* new CliArgumentError({ message: "An input image path is required." });
+    }
+
+    const output = yield* resolveOutputPath(inputPath, outputPath, format);
+
+    return {
+      kind: "run",
+      options: {
+        inputPath,
+        outputPath: output.outputPath,
+        format: output.format,
+        engine,
+      },
+    };
+  });

package/src/cli/main.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env bun
+
+import { Cause, Effect, Exit } from "effect";
+
+import { parseCliArgs } from "./args";
+import { removeBackgroundCli } from "./runtime";
+
+const HELP = `Usage:
+  bgcut <image> [format] [options]
+
+Formats:
+  --png,  -png             Transparent PNG (default)
+  --webp, -webp            Lossless WebP with transparency
+  --jpg,  -jpg             JPEG flattened onto white
+  --jpeg, -jpeg            Alias for JPG
+
+Options:
+  -o, --output <path>      Output filename or path
+  --gpu, -gpu              Require native WebGPU
+  --cpu, -cpu              Require CPU inference
+  -h, --help               Show this help
+
+Examples:
+  bgcut photo.jpg -png
+  bgcut photo.jpg --webp
+  bgcut photo.jpg -o portrait.png
+  bgcut photo.jpg -webp -o portrait.webp
+  bgcut photo.jpg -gpu
+`;
+
+const formatDuration = (milliseconds: number): string => {
+  if (milliseconds < 10) {
+    return `${milliseconds.toFixed(1)} ms`;
+  }
+
+  if (milliseconds < 1000) {
+    return `${Math.round(milliseconds)} ms`;
+  }
+
+  return `${(milliseconds / 1000).toFixed(2)} s`;
+};
+
+const program = Effect.gen(function* () {
+  const parsed = yield* parseCliArgs(process.argv.slice(2));
+
+  if (parsed.kind === "help") {
+    console.log(HELP);
+
+    return;
+  }
+
+  const result = yield* removeBackgroundCli(parsed.options);
+  const timings = result.timings;
+
+  console.log(`✓ ${result.engine} · ${result.width}×${result.height} · saved ${result.outputPath}`);
+
+  if (result.fallbackReason !== undefined) {
+    console.log(`↳ WebGPU unavailable; automatic mode used CPU. ${result.fallbackReason}`);
+  }
+
+  console.log(
+    `  model ${formatDuration(timings.modelMs)} · prepare ${formatDuration(timings.prepareMs)} · session ${formatDuration(timings.sessionMs)} · inference ${formatDuration(timings.inferenceMs)} · encode ${formatDuration(timings.encodeMs)} · total ${formatDuration(timings.totalMs)}`,
+  );
+});
+
+const exit = await Effect.runPromiseExit(program);
+
+if (Exit.isFailure(exit)) {
+  console.error(Cause.pretty(exit.cause));
+  process.exitCode = 1;
+}

package/src/cli/model-cache.ts

@@ -0,0 +1,122 @@
+import { Data, Effect } from "effect";
+import { mkdir, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+  MODEL_FILENAME,
+  MODEL_RELEASE_URL,
+  MODEL_SHA256,
+  MODEL_SIZE_BYTES,
+} from "../engine/model-config";
+import { inspectModelFile, type ModelFileFingerprint } from "../shared/model-file";
+
+export class CliModelError extends Data.TaggedError("CliModelError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+const cacheRoot = (appName: string): string => {
+  if (process.platform === "darwin") {
+    return join(homedir(), "Library", "Caches", appName);
+  }
+
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA;
+
+    return join(localAppData ?? join(homedir(), "AppData", "Local"), appName);
+  }
+
+  return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), appName);
+};
+
+export const cliModelPath = (): string => join(cacheRoot("bgcut"), "models", MODEL_FILENAME);
+
+const previousCliModelPaths = (): readonly string[] => [
+  join(cacheRoot("bgremove"), "models", MODEL_FILENAME),
+  join(cacheRoot("removebg-webgpu"), "models", MODEL_FILENAME),
+];
+
+const isExpectedModel = (fingerprint: ModelFileFingerprint | undefined): boolean =>
+  fingerprint?.sizeBytes === MODEL_SIZE_BYTES && fingerprint.sha256 === MODEL_SHA256;
+
+const inspectCachedModel = (path: string): Effect.Effect<ModelFileFingerprint | undefined, CliModelError> =>
+  inspectModelFile(path).pipe(
+    Effect.mapError((cause) =>
+      new CliModelError({ message: `Could not inspect the cached model at ${path}.`, cause }),
+    ),
+  );
+
+export const ensureCliModel = (): Effect.Effect<string, CliModelError> =>
+  Effect.gen(function* () {
+    const modelPath = cliModelPath();
+    const existing = yield* inspectCachedModel(modelPath);
+
+    if (isExpectedModel(existing)) {
+      return modelPath;
+    }
+
+    for (const previousModelPath of previousCliModelPaths()) {
+      const previousExisting = yield* inspectCachedModel(previousModelPath);
+
+      if (isExpectedModel(previousExisting)) {
+        return previousModelPath;
+      }
+    }
+
+    const temporaryPath = `${modelPath}.download`;
+
+    yield* Effect.tryPromise({
+      try: () => mkdir(dirname(modelPath), { recursive: true }),
+      catch: (cause) => new CliModelError({ message: `Could not create ${dirname(modelPath)}.`, cause }),
+    });
+
+    yield* Effect.tryPromise({
+      try: () => rm(temporaryPath, { force: true }),
+      catch: (cause) => new CliModelError({ message: `Could not clear ${temporaryPath}.`, cause }),
+    });
+
+    const response = yield* Effect.tryPromise({
+      try: () => fetch(MODEL_RELEASE_URL),
+      catch: (cause) =>
+        new CliModelError({ message: "Could not download the validated BiRefNet model.", cause }),
+    });
+
+    if (!response.ok) {
+      return yield* new CliModelError({
+        message: `Validated model download failed with HTTP ${response.status}.`,
+      });
+    }
+
+    yield* Effect.tryPromise({
+      try: () => Bun.write(temporaryPath, response),
+      catch: (cause) => new CliModelError({ message: `Could not write ${temporaryPath}.`, cause }),
+    });
+
+    const downloaded = yield* inspectModelFile(temporaryPath).pipe(
+      Effect.mapError((cause) =>
+        new CliModelError({ message: `Could not verify ${temporaryPath}.`, cause }),
+      ),
+    );
+
+    if (!isExpectedModel(downloaded)) {
+      yield* Effect.tryPromise({
+        try: () => rm(temporaryPath, { force: true }),
+        catch: (cause) => new CliModelError({ message: `Could not remove invalid ${temporaryPath}.`, cause }),
+      });
+
+      return yield* new CliModelError({
+        message: `Downloaded model did not match the expected ${MODEL_SIZE_BYTES}-byte artifact with SHA-256 ${MODEL_SHA256}.`,
+      });
+    }
+
+    yield* Effect.tryPromise({
+      try: async () => {
+        await rm(modelPath, { force: true });
+        await rename(temporaryPath, modelPath);
+      },
+      catch: (cause) => new CliModelError({ message: `Could not install the model at ${modelPath}.`, cause }),
+    });
+
+    return modelPath;
+  });

package/src/cli/runtime.ts

@@ -0,0 +1,347 @@
+import { Data, Effect } from "effect";
+import * as ort from "onnxruntime-node";
+import { mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import sharp from "sharp";
+
+import { MODEL_INPUT_SIZE } from "../engine/image";
+import { logitToAlphaByte } from "../engine/matte";
+import { resizeRgbaLinearToNchw } from "../engine/preprocess";
+import { compositeAlphaMask } from "./alpha-mask";
+import type { CliEngine, CliFormat, CliOptions } from "./args";
+import { CliModelError, ensureCliModel } from "./model-cache";
+
+export type CliExecutionEngine = "webgpu" | "cpu";
+
+export type CliTimings = {
+  readonly totalMs: number;
+  readonly modelMs: number;
+  readonly prepareMs: number;
+  readonly sessionMs: number;
+  readonly inferenceMs: number;
+  readonly encodeMs: number;
+};
+
+export type CliRemovalResult = {
+  readonly width: number;
+  readonly height: number;
+  readonly outputPath: string;
+  readonly engine: CliExecutionEngine;
+  readonly fallbackReason: string | undefined;
+  readonly timings: CliTimings;
+};
+
+export class CliImageError extends Data.TaggedError("CliImageError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+export class CliSessionError extends Data.TaggedError("CliSessionError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+export class CliInferenceError extends Data.TaggedError("CliInferenceError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+export class CliOutputError extends Data.TaggedError("CliOutputError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+type PreparedImage = {
+  readonly source: Buffer;
+  readonly width: number;
+  readonly height: number;
+  readonly modelInput: Float32Array;
+};
+
+type NativeSession = {
+  readonly session: ort.InferenceSession;
+  readonly engine: CliExecutionEngine;
+  readonly fallbackReason: string | undefined;
+};
+
+const supportedSharpFormats = new Set(["jpeg", "png", "webp"]);
+
+const prepareImage = (inputPath: string): Effect.Effect<PreparedImage, CliImageError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const input = Bun.file(inputPath);
+
+      if (!(await input.exists())) {
+        throw new Error(`Input file does not exist: ${inputPath}`);
+      }
+
+      const metadata = await sharp(inputPath).metadata();
+
+      if (metadata.format === undefined || !supportedSharpFormats.has(metadata.format)) {
+        throw new Error(`Unsupported image type: ${metadata.format ?? "unknown"}`);
+      }
+
+      const source = await sharp(inputPath)
+        .rotate()
+        .ensureAlpha()
+        .toColourspace("srgb")
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+
+      if (source.info.channels !== 4) {
+        throw new Error("Decoded image did not produce RGBA pixels.");
+      }
+
+      return {
+        source: source.data,
+        width: source.info.width,
+        height: source.info.height,
+        modelInput: resizeRgbaLinearToNchw(
+          source.data,
+          source.info.width,
+          source.info.height,
+          MODEL_INPUT_SIZE,
+          MODEL_INPUT_SIZE,
+        ),
+      };
+    },
+    catch: (cause) =>
+      new CliImageError({
+        message: `Could not decode and prepare ${inputPath}.`,
+        cause,
+      }),
+  });
+
+const createSessionForProvider = (
+  modelPath: string,
+  engine: CliExecutionEngine,
+): Effect.Effect<NativeSession, CliSessionError> =>
+  Effect.tryPromise({
+    try: async () => ({
+      session: await ort.InferenceSession.create(modelPath, {
+        executionProviders: [engine],
+        graphOptimizationLevel: "all",
+      }),
+      engine,
+      fallbackReason: undefined,
+    }),
+    catch: (cause) =>
+      new CliSessionError({
+        message: `ONNX Runtime could not create the native ${engine} session.`,
+        cause,
+      }),
+  });
+
+const createSession = (
+  modelPath: string,
+  engine: CliEngine,
+): Effect.Effect<NativeSession, CliSessionError> => {
+  if (engine === "gpu") {
+    return createSessionForProvider(modelPath, "webgpu");
+  }
+
+  if (engine === "cpu") {
+    return createSessionForProvider(modelPath, "cpu");
+  }
+
+  return createSessionForProvider(modelPath, "webgpu").pipe(
+    Effect.catchAll((webGpuError) =>
+      createSessionForProvider(modelPath, "cpu").pipe(
+        Effect.map((nativeSession) => ({
+          ...nativeSession,
+          fallbackReason: webGpuError.message,
+        })),
+      ),
+    ),
+  );
+};
+
+const runInference = (
+  session: ort.InferenceSession,
+  modelInput: Float32Array,
+): Effect.Effect<Float32Array, CliInferenceError> =>
+  Effect.gen(function* () {
+    const inputName = session.inputNames.at(0);
+    const outputName = session.outputNames.at(0);
+
+    if (inputName === undefined || outputName === undefined) {
+      return yield* new CliInferenceError({
+        message: "BiRefNet does not expose the expected input and output tensors.",
+      });
+    }
+
+    const input = new ort.Tensor("float32", modelInput, [1, 3, MODEL_INPUT_SIZE, MODEL_INPUT_SIZE]);
+
+    const outputs = yield* Effect.tryPromise({
+      try: () => session.run({ [inputName]: input }),
+      catch: (cause) => new CliInferenceError({ message: "BiRefNet inference failed.", cause }),
+    });
+
+    const output = outputs[outputName];
+
+    if (output === undefined) {
+      return yield* new CliInferenceError({ message: "BiRefNet returned no foreground matte." });
+    }
+
+    const data = output.data;
+
+    if (!(data instanceof Float32Array)) {
+      return yield* new CliInferenceError({
+        message: `BiRefNet returned ${output.type} data instead of float32 logits.`,
+      });
+    }
+
+    if (data.length !== MODEL_INPUT_SIZE * MODEL_INPUT_SIZE) {
+      return yield* new CliInferenceError({
+        message: `BiRefNet returned ${data.length} logits instead of ${MODEL_INPUT_SIZE * MODEL_INPUT_SIZE}.`,
+      });
+    }
+
+    return data;
+  });
+
+const createMask = (logits: Float32Array): Uint8Array => {
+  const alpha = new Uint8Array(logits.length);
+
+  for (let index = 0; index < logits.length; index += 1) {
+    alpha[index] = logitToAlphaByte(logits[index]);
+  }
+
+  return alpha;
+};
+
+const encodeOutput = (
+  prepared: PreparedImage,
+  logits: Float32Array,
+  outputPath: string,
+  format: CliFormat,
+): Effect.Effect<void, CliOutputError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const alpha = createMask(logits);
+
+      const resizedAlpha = await sharp(Buffer.from(alpha), {
+        raw: {
+          width: MODEL_INPUT_SIZE,
+          height: MODEL_INPUT_SIZE,
+          channels: 1,
+        },
+      })
+        .resize(prepared.width, prepared.height, {
+          fit: "fill",
+          kernel: sharp.kernel.cubic,
+          fastShrinkOnLoad: false,
+        })
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+
+      if (resizedAlpha.info.width !== prepared.width || resizedAlpha.info.height !== prepared.height) {
+        throw new Error(
+          `Resized matte is ${resizedAlpha.info.width} × ${resizedAlpha.info.height}; expected ${prepared.width} × ${prepared.height}.`,
+        );
+      }
+
+      const rgba = Buffer.from(prepared.source);
+
+      compositeAlphaMask(rgba, resizedAlpha.data, resizedAlpha.info.channels);
+
+      await mkdir(dirname(outputPath), { recursive: true });
+
+      const image = sharp(rgba, {
+        raw: {
+          width: prepared.width,
+          height: prepared.height,
+          channels: 4,
+        },
+      });
+
+      if (format === "png") {
+        await image.png().toFile(outputPath);
+
+        return;
+      }
+
+      if (format === "webp") {
+        await image.webp({ lossless: true }).toFile(outputPath);
+
+        return;
+      }
+
+      await image
+        .flatten({ background: { r: 255, g: 255, b: 255 } })
+        .jpeg({ quality: 95, chromaSubsampling: "4:4:4" })
+        .toFile(outputPath);
+    },
+    catch: (cause) =>
+      new CliOutputError({
+        message: `Could not encode ${outputPath}.`,
+        cause,
+      }),
+  });
+
+export const removeBackgroundCli = (
+  options: CliOptions,
+): Effect.Effect<
+  CliRemovalResult,
+  CliImageError | CliSessionError | CliInferenceError | CliOutputError | CliModelError
+> =>
+  Effect.gen(function* () {
+    if (resolve(options.inputPath) === resolve(options.outputPath)) {
+      return yield* new CliOutputError({
+        message: "Input and output paths must be different.",
+      });
+    }
+
+    const totalStartedAt = performance.now();
+    let stageStartedAt = performance.now();
+
+    const modelPath = yield* ensureCliModel();
+    const modelMs = performance.now() - stageStartedAt;
+
+    stageStartedAt = performance.now();
+
+    const prepared = yield* prepareImage(options.inputPath);
+    const prepareMs = performance.now() - stageStartedAt;
+
+    stageStartedAt = performance.now();
+
+    const nativeSession = yield* createSession(modelPath, options.engine);
+    const sessionMs = performance.now() - stageStartedAt;
+
+    stageStartedAt = performance.now();
+
+    const logits = yield* Effect.acquireUseRelease(
+      Effect.succeed(nativeSession.session),
+      (session) => runInference(session, prepared.modelInput),
+      (session) =>
+        Effect.tryPromise({
+          try: () => session.release(),
+          catch: () => undefined,
+        }).pipe(Effect.orElseSucceed(() => undefined)),
+    );
+
+    const inferenceMs = performance.now() - stageStartedAt;
+
+    stageStartedAt = performance.now();
+
+    yield* encodeOutput(prepared, logits, options.outputPath, options.format);
+
+    const encodeMs = performance.now() - stageStartedAt;
+    const totalMs = performance.now() - totalStartedAt;
+
+    return {
+      width: prepared.width,
+      height: prepared.height,
+      outputPath: options.outputPath,
+      engine: nativeSession.engine,
+      fallbackReason: nativeSession.fallbackReason,
+      timings: {
+        totalMs,
+        modelMs,
+        prepareMs,
+        sessionMs,
+        inferenceMs,
+        encodeMs,
+      },
+    };
+  });

package/src/engine/errors.ts

@@ -0,0 +1,95 @@
+import { Data, Match } from "effect";
+
+export class WebGpuUnavailable extends Data.TaggedError("WebGpuUnavailable")<{
+  readonly message: string;
+}> {}
+
+export class AdapterUnavailable extends Data.TaggedError("AdapterUnavailable")<{
+  readonly message: string;
+}> {}
+
+export class DeviceRequestFailed extends Data.TaggedError("DeviceRequestFailed")<{
+  readonly message: string;
+}> {}
+
+export class RuntimeInitializationFailed extends Data.TaggedError("RuntimeInitializationFailed")<{
+  readonly message: string;
+}> {}
+
+export class UnsupportedImage extends Data.TaggedError("UnsupportedImage")<{
+  readonly mimeType: string;
+}> {}
+
+export class ImageDecodeFailed extends Data.TaggedError("ImageDecodeFailed")<{
+  readonly fileName: string;
+}> {}
+
+export class ImageProcessingFailed extends Data.TaggedError("ImageProcessingFailed")<{
+  readonly message: string;
+}> {}
+
+export class ModelDownloadFailed extends Data.TaggedError("ModelDownloadFailed")<{
+  readonly message: string;
+}> {}
+
+export class ModelLoadFailed extends Data.TaggedError("ModelLoadFailed")<{
+  readonly message: string;
+}> {}
+
+export class InferenceFailed extends Data.TaggedError("InferenceFailed")<{
+  readonly message: string;
+}> {}
+
+export class ExportFailed extends Data.TaggedError("ExportFailed")<{
+  readonly message: string;
+}> {}
+
+export type GpuRuntimeError =
+  | WebGpuUnavailable
+  | AdapterUnavailable
+  | DeviceRequestFailed
+  | RuntimeInitializationFailed;
+
+export type ImageError = UnsupportedImage | ImageDecodeFailed | ImageProcessingFailed;
+
+export type BackgroundRemovalError =
+  | GpuRuntimeError
+  | ImageError
+  | ModelDownloadFailed
+  | ModelLoadFailed
+  | InferenceFailed
+  | ExportFailed;
+
+export const formatGpuRuntimeError = (error: GpuRuntimeError): string => error.message;
+
+export const formatImageError = (error: ImageError): string =>
+  Match.value(error).pipe(
+    Match.tag("UnsupportedImage", (unsupported) =>
+      `Unsupported image type: ${unsupported.mimeType || "unknown"}`
+    ),
+    Match.tag("ImageDecodeFailed", (decodeFailure) => `Could not decode ${decodeFailure.fileName}.`),
+    Match.tag("ImageProcessingFailed", (processingFailure) => processingFailure.message),
+    Match.exhaustive,
+  );
+
+export const formatBackgroundRemovalError = (error: BackgroundRemovalError): string =>
+  Match.value(error).pipe(
+    Match.tag(
+      "UnsupportedImage",
+      "ImageDecodeFailed",
+      "ImageProcessingFailed",
+      (imageError) => formatImageError(imageError),
+    ),
+    Match.tag(
+      "WebGpuUnavailable",
+      "AdapterUnavailable",
+      "DeviceRequestFailed",
+      "RuntimeInitializationFailed",
+      "ModelDownloadFailed",
+      "ModelLoadFailed",
+      "InferenceFailed",
+      "ExportFailed",
+      (failure) => failure.message,
+    ),
+    Match.exhaustive,
+  );

package/src/engine/image.ts

@@ -0,0 +1,84 @@
+import { Effect } from "effect";
+
+import { ImageDecodeFailed, ImageProcessingFailed, UnsupportedImage, type ImageError } from "./errors";
+import { normalizeRgbaToNchw } from "./preprocess";
+
+export const MODEL_INPUT_SIZE = 512;
+
+const supportedImageTypes = new Set(["image/jpeg", "image/png", "image/webp"]);
+
+export const isSupportedImageType = (mimeType: string): boolean => supportedImageTypes.has(mimeType);
+
+export type DecodedImage = {
+  readonly width: number;
+  readonly height: number;
+};
+
+export const loadImageBitmap = (file: File): Effect.Effect<ImageBitmap, ImageError> =>
+  Effect.gen(function* () {
+    if (!isSupportedImageType(file.type)) {
+      return yield* new UnsupportedImage({ mimeType: file.type });
+    }
+
+    return yield* Effect.tryPromise({
+      try: () => createImageBitmap(file, { imageOrientation: "from-image" }),
+      catch: () => new ImageDecodeFailed({ fileName: file.name }),
+    });
+  });
+
+export const decodeImage = (file: File): Effect.Effect<DecodedImage, ImageError> =>
+  Effect.acquireUseRelease(
+    loadImageBitmap(file),
+    (bitmap) => Effect.succeed({ width: bitmap.width, height: bitmap.height }),
+    (bitmap) => Effect.sync(() => bitmap.close()),
+  );
+
+export const prepareModelCanvas = (
+  bitmap: ImageBitmap,
+): Effect.Effect<HTMLCanvasElement, ImageProcessingFailed> =>
+  Effect.try({
+    try: () => {
+      const canvas = document.createElement("canvas");
+      canvas.width = MODEL_INPUT_SIZE;
+      canvas.height = MODEL_INPUT_SIZE;
+
+      const context = canvas.getContext("2d");
+
+      if (context === null) {
+        throw new Error("2D canvas is unavailable.");
+      }
+
+      context.imageSmoothingEnabled = true;
+      context.imageSmoothingQuality = "high";
+      context.drawImage(bitmap, 0, 0, MODEL_INPUT_SIZE, MODEL_INPUT_SIZE);
+
+      return canvas;
+    },
+    catch: () =>
+      new ImageProcessingFailed({
+        message: "The image could not be resized for background-removal inference.",
+      }),
+  });
+
+export const prepareModelInput = (bitmap: ImageBitmap): Effect.Effect<Float32Array, ImageProcessingFailed> =>
+  Effect.gen(function* () {
+    const canvas = yield* prepareModelCanvas(bitmap);
+
+    return yield* Effect.try({
+      try: () => {
+        const context = canvas.getContext("2d", { willReadFrequently: true });
+
+        if (context === null) {
+          throw new Error("2D canvas is unavailable.");
+        }
+
+        const image = context.getImageData(0, 0, MODEL_INPUT_SIZE, MODEL_INPUT_SIZE);
+
+        return normalizeRgbaToNchw(image.data, MODEL_INPUT_SIZE, MODEL_INPUT_SIZE);
+      },
+      catch: () =>
+        new ImageProcessingFailed({
+          message: "The image could not be prepared for background-removal inference.",
+        }),
+    });
+  });

package/src/engine/matte.ts

@@ -0,0 +1,2 @@
+export const logitToAlphaByte = (logit: number): number =>
+  Math.round(255 / (1 + Math.exp(-logit)));

package/src/engine/model-config.ts

@@ -0,0 +1,12 @@
+export const MODEL_FILENAME = "birefnet-lite-512-ort-basic-webgpu-v2.onnx";
+
+export const MODEL_PUBLIC_PATH = `/models/${MODEL_FILENAME}`;
+
+export const MODEL_RELEASE_URL =
+  `https://github.com/jhomra21/bgremove/releases/download/model-birefnet-lite-512-ort-basic-webgpu-v2/${MODEL_FILENAME}`;
+
+export const MODEL_REVISION = "4a3c40c36c94093cc1e724d9ea428b8fa4b57dc7";
+
+export const MODEL_SHA256 = "4461109672dda07a054892aef076b5fcc5fc40bbc91f51a357a7593c7f45ad9c";
+
+export const MODEL_SIZE_BYTES = 195_872_736;

package/src/engine/preprocess.ts

@@ -0,0 +1,130 @@
+const imageNetMean = [0.485, 0.456, 0.406] as const;
+
+const imageNetStd = [0.229, 0.224, 0.225] as const;
+
+type RgbChannel = 0 | 1 | 2;
+
+const normalizeChannel = (value: number, channel: RgbChannel): number =>
+  (value - imageNetMean[channel]) / imageNetStd[channel];
+
+export const normalizeRgbaToNchw = (
+  pixels: Uint8Array | Uint8ClampedArray,
+  width: number,
+  height: number,
+): Float32Array => {
+  const pixelCount = width * height;
+  const tensor = new Float32Array(pixelCount * 3);
+
+  for (let pixelIndex = 0; pixelIndex < pixelCount; pixelIndex += 1) {
+    const rgbaIndex = pixelIndex * 4;
+
+    tensor[pixelIndex] = normalizeChannel(pixels[rgbaIndex] / 255, 0);
+    tensor[pixelCount + pixelIndex] = normalizeChannel(pixels[rgbaIndex + 1] / 255, 1);
+    tensor[pixelCount * 2 + pixelIndex] = normalizeChannel(pixels[rgbaIndex + 2] / 255, 2);
+  }
+
+  return tensor;
+};
+
+const clampIndex = (value: number, maximum: number): number =>
+  Math.min(Math.max(value, 0), maximum);
+
+const writeSampledChannel = (
+  tensor: Float32Array,
+  pixels: Uint8Array | Uint8ClampedArray,
+  channel: RgbChannel,
+  targetPixelCount: number,
+  targetIndex: number,
+  topLeftIndex: number,
+  topRightIndex: number,
+  bottomLeftIndex: number,
+  bottomRightIndex: number,
+  xMix: number,
+  yMix: number,
+): void => {
+  const top = pixels[topLeftIndex + channel] * (1 - xMix)
+    + pixels[topRightIndex + channel] * xMix;
+
+  const bottom = pixels[bottomLeftIndex + channel] * (1 - xMix)
+    + pixels[bottomRightIndex + channel] * xMix;
+
+  const sampled = (top * (1 - yMix) + bottom * yMix) / 255;
+
+  tensor[channel * targetPixelCount + targetIndex] = normalizeChannel(sampled, channel);
+};
+
+export const resizeRgbaLinearToNchw = (
+  pixels: Uint8Array | Uint8ClampedArray,
+  sourceWidth: number,
+  sourceHeight: number,
+  targetWidth: number,
+  targetHeight: number,
+): Float32Array => {
+  const targetPixelCount = targetWidth * targetHeight;
+  const tensor = new Float32Array(targetPixelCount * 3);
+  const sourceMaxX = sourceWidth - 1;
+  const sourceMaxY = sourceHeight - 1;
+
+  for (let targetY = 0; targetY < targetHeight; targetY += 1) {
+    const sourceY = ((targetY + 0.5) * sourceHeight) / targetHeight - 0.5;
+    const sourceYFloor = Math.floor(sourceY);
+    const yMix = sourceY - sourceYFloor;
+    const y0 = clampIndex(sourceYFloor, sourceMaxY);
+    const y1 = clampIndex(sourceYFloor + 1, sourceMaxY);
+
+    for (let targetX = 0; targetX < targetWidth; targetX += 1) {
+      const sourceX = ((targetX + 0.5) * sourceWidth) / targetWidth - 0.5;
+      const sourceXFloor = Math.floor(sourceX);
+      const xMix = sourceX - sourceXFloor;
+      const x0 = clampIndex(sourceXFloor, sourceMaxX);
+      const x1 = clampIndex(sourceXFloor + 1, sourceMaxX);
+      const topLeftIndex = (y0 * sourceWidth + x0) * 4;
+      const topRightIndex = (y0 * sourceWidth + x1) * 4;
+      const bottomLeftIndex = (y1 * sourceWidth + x0) * 4;
+      const bottomRightIndex = (y1 * sourceWidth + x1) * 4;
+      const targetIndex = targetY * targetWidth + targetX;
+
+      writeSampledChannel(
+        tensor,
+        pixels,
+        0,
+        targetPixelCount,
+        targetIndex,
+        topLeftIndex,
+        topRightIndex,
+        bottomLeftIndex,
+        bottomRightIndex,
+        xMix,
+        yMix,
+      );
+      writeSampledChannel(
+        tensor,
+        pixels,
+        1,
+        targetPixelCount,
+        targetIndex,
+        topLeftIndex,
+        topRightIndex,
+        bottomLeftIndex,
+        bottomRightIndex,
+        xMix,
+        yMix,
+      );
+      writeSampledChannel(
+        tensor,
+        pixels,
+        2,
+        targetPixelCount,
+        targetIndex,
+        topLeftIndex,
+        topRightIndex,
+        bottomLeftIndex,
+        bottomRightIndex,
+        xMix,
+        yMix,
+      );
+    }
+  }
+
+  return tensor;
+};

package/src/shared/model-file.ts

@@ -0,0 +1,43 @@
+import { Data, Effect } from "effect";
+
+export type ModelFileFingerprint = {
+  readonly sizeBytes: number;
+  readonly sha256: string;
+};
+
+export class ModelFileError extends Data.TaggedError("ModelFileError")<{
+  readonly path: string;
+  readonly cause: unknown;
+}> {}
+
+export const inspectModelFile = (
+  path: string,
+): Effect.Effect<ModelFileFingerprint | undefined, ModelFileError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const file = Bun.file(path);
+
+      if (!(await file.exists())) {
+        return undefined;
+      }
+
+      const reader = file.stream().getReader();
+      const hasher = new Bun.CryptoHasher("sha256");
+
+      for (;;) {
+        const chunk = await reader.read();
+
+        if (chunk.done) {
+          break;
+        }
+
+        hasher.update(chunk.value);
+      }
+
+      return {
+        sizeBytes: file.size,
+        sha256: hasher.digest("hex"),
+      };
+    },
+    catch: (cause) => new ModelFileError({ path, cause }),
+  });