simdra 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Narek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+<p align="center">
+  <img src="./image.png" alt="simdra — SIMD-accelerated 2D canvas, in a Worker" width="100%" />
+</p>
+
+# simdra
+
+**SIMD-accelerated 2D canvas and image manipulation. In a Worker.**
+
+Cloudflare Workers · browser Web Workers · Vercel Edge · Deno Deploy ·
+any V8 isolate with WASM-SIMD.
+
+📖 **[See the docs → bynarek.com/simdra](https://bynarek.com/simdra/)** — installation, API reference, integration examples.
+
+```bash
+npm install simdra
+```
+
+## Why
+
+[`sharp`](https://sharp.pixelplumbing.com) is great. So is
+[`@napi-rs/canvas`](https://github.com/Brooooooklyn/canvas). Neither
+runs in a Cloudflare Worker, browser Web Worker, or any other V8
+isolate that doesn't let you spawn threads. simdra fills that gap:
+HTML5 Canvas 2D plus a sharp-shaped fluent surface, both compiled to
+one ~500 KB gzipped WASM bundle with NEON / SSE / WASM-SIMD code
+paths under the hood.
+
+| Library | Cloudflare Workers? | Browser? | Native deps | Bundle |
+|---|---|---|---|---|
+| `sharp` | ❌ needs libvips | ❌ | yes (libvips) | — |
+| `@napi-rs/canvas` | ❌ Node-API only | ❌ | yes (Skia) | — |
+| `node-canvas` | ❌ Cairo native | ❌ | yes (Cairo) | — |
+| `canvaskit-wasm` | ❌ too large | ✅ | no | ~7 MB |
+| **`simdra`** | ✅ | ✅ | **no** | **~500 KB gz** |
+
+CanvasKit is the closest comparable — both are WASM, both work in
+the browser — but CanvasKit is a full Skia port (~7 MB) that's too
+large for the Cloudflare Workers bundle limit and gives you the Skia
+API rather than HTML5 Canvas. simdra targets the smaller, more
+familiar Canvas surface plus the sharp shape, in 1/14 the size.
+
+## What
+
+Three surfaces, one SIMD-accelerated Zig core:
+
+- **🎨 Canvas 2D** — drop-in HTML5 Canvas (`createCanvas`,
+  `getContext('2d')`, `Path2D`, `ImageData`, `DOMMatrix`,
+  `CanvasGradient`, `CanvasPattern`).
+- **🖼 MicroSharp** — drop-in sharp-shaped fluent API
+  (`microsharp(input).resize(...).toBuffer()`).
+- **🦎 Zig core** — Skia-style `Sm*` primitives (`SmCanvas`,
+  `SmPaint`, `SmPath`, `SmBitmap`). Embed in your own Zig project.
+
+The three are independent at the consumer layer but call the same
+Zig types underneath — same SIMD kernels, same encoders, same
+decoders.
+
+## Quick start
+
+### Resize in a Cloudflare Worker
+
+```js
+import { microsharp } from 'simdra';
+
+export default {
+  async fetch(request) {
+    const out = await microsharp(request.body)
+      .resize(800, 600, { fit: 'cover', kernel: 'lanczos3' })
+      .jpeg({ quality: 85 })
+      .toBuffer();
+    return new Response(out, {
+      headers: { 'content-type': 'image/jpeg' },
+    });
+  },
+};
+```
+
+### Canvas 2D in a Web Worker
+
+```js
+import { createCanvas } from 'simdra';
+
+const canvas = createCanvas(400, 300);
+const ctx = canvas.getContext('2d');
+
+ctx.fillStyle = '#10b981';
+ctx.fillRect(0, 0, 400, 300);
+ctx.fillStyle = '#fff';
+ctx.font = '24px sans-serif';
+ctx.fillText('Hello, Worker', 20, 40);
+
+const png = canvas.toBytes();
+postMessage(png, [png.buffer]);
+```
+
+### Sharp-style chain in the browser
+
+```js
+import { microsharp } from 'simdra';
+
+async function autoCrop(file) {
+  const out = await microsharp(file)
+    .rotate()                                 // autoOrient via EXIF
+    .resize(1200, 800, { fit: 'cover', position: 'attention' })
+    .modulate({ brightness: 1.1, saturation: 1.2 })
+    .sharpen()
+    .jpeg({ quality: 90 })
+    .toBuffer();
+  return new Blob([out], { type: 'image/jpeg' });
+}
+```
+
+### Sharp's image-ops chain — single-thread, in WASM
+
+simdra implements sharp's full image-operations API (~22 ops):
+
+```js
+const out = await microsharp(input)
+  .rotate(90)                                 // 90° / 180° / 270° byte-exact
+  .flip().flop()                              // mirrors
+  .affine([1, 0.3, 0.1, 0.7])                 // affine transform
+  .blur(2)                                    // separable Gaussian
+  .sharpen({ sigma: 1, m1: 1, m2: 2 })        // libvips USM
+  .median(3).dilate(1).erode(1)               // morphology
+  .convolve({ width: 3, height: 3, kernel: [-1,0,1,-2,0,2,-1,0,1] })
+  .gamma(2.2).negate({ alpha: false })        // tone curves
+  .linear(1.2, -10).threshold(128)            // levels
+  .normalise().clahe({ width: 16, height: 16 })
+  .modulate({ brightness: 1.1, hue: 30 })
+  .tint('#ff8800').greyscale()
+  .png()
+  .toBuffer();
+```
+
+See [`COMPATIBILITY.md`](./COMPATIBILITY.md) for sharp-API divergences.
+
+## Two builds, one package
+
+- `simdra` / `simdra/core` — Node, native via
+  [node-zigar](https://github.com/chung-leong/node-zigar). NEON
+  kernels on aarch64.
+- `simdra/wasm` — browsers, Cloudflare Workers, Vercel Edge, Deno.
+  WASM bundle, ~440 KB raw / ~175 KB gzip.
+
+## When NOT to use simdra
+
+- Multi-core image-processing servers — use `sharp`. simdra is
+  single-thread by design; sharp wins on a 16-core box.
+- GPU-bound workloads — use Skia / WebGPU.
+- Wide-gamut, 16-bit, ICC-aware pipelines — use libvips.
+- WebP / AVIF / JXL output — `stb_image_write` doesn't ship them;
+  use `sharp`.
+
+The bullseye is: *"I'm shipping image processing in a Cloudflare
+Worker / Vercel Edge function / browser Web Worker / single-vCPU
+lambda, and the Node-API libraries don't run there."*
+
+## What you give up vs sharp / @napi-rs/canvas
+
+- No multi-core throughput on a 16-core box.
+- No WebP / AVIF / JXL output.
+- No 16-bit / Lab / CMYK pipelines. RGBA8 sRGB only.
+- No EXIF / ICC / XMP metadata round-trip (only `Orientation` is
+  read for `autoOrient`).
+- No tile-streaming for very-large-image inputs.
+
+If any of those are dealbreakers, use sharp.
+
+## Architecture
+
+simdra is a two-layer library:
+
+- **Zig** is a pure drawing library — Skia-style class taxonomy with
+  the **`Sm` prefix** (analogous to Skia's `Sk*`): `SmSurface`,
+  `SmCanvas`, `SmPaint`, `SmBitmap`, `SmPath`, `SmMatrix`,
+  `SmGradient`. No HTML5 names anywhere in Zig. Folder structure
+  mirrors Skia's `include/{core,effects,encode}/` and `src/{opts,utils}/`.
+- **TypeScript** (`src/index.ts` + `src/microsharp/index.ts`) is the
+  HTML5 / WebIDL compatibility layer plus the sharp-shaped fluent
+  API. Both lower to the same vectorised raster pipeline.
+
+Every hot loop is vectorised through Zig's `@Vector` primitives:
+`@Vector(N, u8)` for byte ops, `@Vector(4, f32)` for per-pixel FMA
+chains, `@select` for branchless masking, `@reduce(.Add, ...)` for
+dot-products, `@splat` for kernel-weight broadcast. Same source
+compiles to NEON on aarch64, SSE on x86, WASM-SIMD in browsers.
+
+See the [Zig core docs](./docs/zig/index.md) for the full
+architecture writeup.
+
+## Documentation
+
+📖 **Full docs: [bynarek.com/simdra](https://bynarek.com/simdra/)** — searchable, with the integration examples laid out side-by-side.
+
+Quick links:
+
+- [Installation](https://bynarek.com/simdra/installation) — Cloudflare Workers, Vercel Edge, Deno, Bun, browsers, Web Workers.
+- [Examples](https://bynarek.com/simdra/examples/) — image-resize API, OG cards, avatar pipeline, watermarking, format converter, document & chart renderers, plus canvg / pdfjs-serverless / unpdf integrations.
+- [Canvas 2D API](https://bynarek.com/simdra/canvas/api) — drawing, paths, transforms, text, images, encoding.
+- [MicroSharp API](https://bynarek.com/simdra/microsharp/api) — full sharp-shaped pipeline, all 22 image-ops methods.
+- [Zig core](https://bynarek.com/simdra/zig/) — Skia-shaped class taxonomy, Scan→Blitter pipeline, SIMD backends.
+- [Compatibility matrix](./COMPATIBILITY.md) — HTML5 + sharp spec coverage and divergences.
+- [Roadmap](./Roadmap.md) — pixel format expansion (F16 / F32 / 10:10:10:2 / single-channel), codec independence (replace stb with pure Zig).
+
+## Marketing reference
+
+Internal copy decks for landing-page / launch-post / CFP work:
+
+- [`Marketing.md`](./Marketing.md) — cross-audience positioning,
+  pitch ladder, framing notes.
+- [`Marketing-js.md`](./Marketing-js.md) — JS / TS audience.
+  Competitive matrix, code snippets, "in a Worker" framing.
+- [`Marketing-zig.md`](./Marketing-zig.md) — Zig audience.
+  `@Vector` patterns, file-is-struct, comptime backend dispatch.
+
+## License
+
+MIT.

package/dist/core/index.d.ts

@@ -0,0 +1,385 @@
+import { parseCssColor } from '../zig/simdra.zig';
+import type { SmSurface as ZigSurface, SmCanvas as ZigCanvas, SmBitmap as ZigBitmap, SmMatrix as ZigMatrix, SmPath as ZigPath, SmGradient as ZigGradient, SmPattern as ZigPattern } from '../zig/simdra.zig';
+/**
+ * Module-private symbols — wrappers store their underlying Zig proxy and
+ * provide internal-construction factories. Same-module code can read them;
+ * consumers cannot, because they don't have the symbol reference.
+ */
+declare const ZIG: unique symbol;
+declare const FROM_ZIG: unique symbol;
+export interface ImageDataSettings {
+    colorSpace?: 'srgb' | 'display_p3';
+    pixelFormat?: 'rgba_unorm8' | 'rgba_float16';
+}
+export declare class ImageData {
+    /** @internal */ [ZIG]: ZigBitmap;
+    constructor(width: number, height: number, settings?: ImageDataSettings);
+    constructor(data: ArrayBufferView, width: number, height?: number, settings?: ImageDataSettings);
+    /** @internal — wrap an existing Zig bitmap (used by getImageData). */
+    static [FROM_ZIG](bitmap: ZigBitmap): ImageData;
+    get data(): Uint8Array;
+    get width(): number;
+    get height(): number;
+    get colorSpace(): string;
+    get pixelFormat(): string;
+}
+export declare class Image {
+    /** @internal */ [ZIG]: ZigBitmap;
+    private constructor();
+    /** Decode PNG / JPEG / BMP / GIF (first frame) bytes into an Image. */
+    static fromBytes(bytes: ArrayBufferView | Uint8Array | Buffer): Image;
+    /** @internal — wrap an existing Zig bitmap (used by the sharp-shaped
+     *  binding's pipeline so it can hand over a decoded buffer). */
+    static [FROM_ZIG](bitmap: ZigBitmap): Image;
+    get width(): number;
+    get height(): number;
+}
+export declare class DOMMatrix {
+    /** @internal */ [ZIG]: ZigMatrix;
+    constructor(init?: number[] | string);
+    /** @internal */
+    static [FROM_ZIG](zig: ZigMatrix): DOMMatrix;
+    static fromFloat32Array(arr: Float32Array): DOMMatrix;
+    static fromFloat64Array(arr: Float64Array): DOMMatrix;
+    static fromMatrix(other?: DOMMatrix | DOMMatrix2DInit): DOMMatrix;
+    get a(): number;
+    get b(): number;
+    get c(): number;
+    get d(): number;
+    get e(): number;
+    get f(): number;
+    set a(v: number);
+    set b(v: number);
+    set c(v: number);
+    set d(v: number);
+    set e(v: number);
+    set f(v: number);
+    get m11(): number;
+    get m12(): number;
+    get m21(): number;
+    get m22(): number;
+    get m41(): number;
+    get m42(): number;
+    set m11(v: number);
+    set m12(v: number);
+    set m21(v: number);
+    set m22(v: number);
+    set m41(v: number);
+    set m42(v: number);
+    get m13(): number;
+    get m14(): number;
+    get m23(): number;
+    get m24(): number;
+    get m31(): number;
+    get m32(): number;
+    get m33(): number;
+    get m34(): number;
+    get m43(): number;
+    get m44(): number;
+    get is2D(): boolean;
+    get isIdentity(): boolean;
+    multiplySelf(other: DOMMatrix): DOMMatrix;
+    preMultiplySelf(other: DOMMatrix): DOMMatrix;
+    translateSelf(tx: number, ty: number): DOMMatrix;
+    scaleSelf(sx: number, sy: number): DOMMatrix;
+    rotateSelf(angleDegrees: number): DOMMatrix;
+    rotateFromVectorSelf(x: number, y: number): DOMMatrix;
+    rotateAxisAngleSelf(x: number, y: number, z: number, angleDegrees: number): DOMMatrix;
+    scale3dSelf(scale: number, originX?: number, originY?: number, originZ?: number): DOMMatrix;
+    skewXSelf(angleDegrees: number): DOMMatrix;
+    skewYSelf(angleDegrees: number): DOMMatrix;
+    invertSelf(): DOMMatrix;
+}
+export declare class Path2D {
+    /** @internal */ [ZIG]: ZigPath;
+    constructor(other?: Path2D | string);
+    closePath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    arc(cx: number, cy: number, r: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    arcTo(x1: number, y1: number, x2: number, y2: number, r: number): void;
+    roundRect(x: number, y: number, w: number, h: number, radii?: number | DOMPointInit | Array<number | DOMPointInit>): void;
+    ellipse(cx: number, cy: number, rx: number, ry: number, rotation: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    addPath(other: Path2D, transform?: DOMMatrix): void;
+}
+export declare class CanvasGradient {
+    /** @internal */ [ZIG]: ZigGradient;
+    /** @internal — module-internal construction only. */
+    constructor(zig: ZigGradient);
+    addColorStop(offset: number, color: string): void;
+}
+export interface DOMMatrix2DInit {
+    a?: number;
+    b?: number;
+    c?: number;
+    d?: number;
+    e?: number;
+    f?: number;
+    m11?: number;
+    m12?: number;
+    m21?: number;
+    m22?: number;
+    m41?: number;
+    m42?: number;
+}
+export declare class CanvasPattern {
+    /** @internal */ [ZIG]: ZigPattern;
+    /** @internal — module-internal construction only. */
+    constructor(zig: ZigPattern);
+    setTransform(matrix?: DOMMatrix | DOMMatrix2DInit): void;
+}
+/**
+ * Register a TTF/OTF font under one or more CSS family names. Mirrors the
+ * non-spec `registerFont` extension that node-canvas / @napi-rs/canvas
+ * expose. Family lookup is case-insensitive.
+ *
+ * After registration, set `ctx.font` to a CSS shorthand string that names
+ * the family (e.g. `'14px MyFont'`) to use it.
+ */
+/**
+ * Single entry in the `fonts` array passed to `createCanvas(w, h, { fonts })`.
+ * `data` must be already-fetched TTF or OTF bytes; WOFF / WOFF2 are not decoded.
+ * `name` becomes the family selector for `ctx.font = '<size>px <name>'`.
+ * `weight` / `style` describe the registered face — when omitted, simdra
+ * auto-detects them from the font's `OS/2.usWeightClass` / `head.macStyle`.
+ */
+export interface FontInit {
+    name: string;
+    data: ArrayBuffer | ArrayBufferView;
+    weight?: number | string;
+    style?: FontStyle;
+}
+/**
+ * Optional second-arg bag for `createCanvas` / `new Canvas`. Today only carries
+ * `fonts`, a non-spec convenience that registers each entry via `registerFont`
+ * before the constructor returns.
+ */
+export interface CanvasOptions {
+    fonts?: FontInit[];
+}
+/**
+ * Optional descriptor for `registerFont` — pin the face's weight/style
+ * explicitly. When omitted, simdra reads `OS/2.usWeightClass` and the
+ * `head.macStyle` italic bit from the TTF/OTF bytes.
+ */
+export interface FontFaceDescriptor {
+    weight?: number | string;
+    style?: FontStyle;
+}
+export declare function registerFont(bytes: ArrayBufferView | ArrayBuffer, family: string, descriptor?: FontFaceDescriptor): void;
+type FontStyle = 'normal' | 'italic' | 'oblique';
+type DOMPointInit = {
+    x?: number;
+    y?: number;
+};
+export declare class TextMetrics {
+    readonly width: number;
+    /** @internal */ constructor(width: number);
+}
+export declare class CanvasRenderingContext2D {
+    #private;
+    /** @internal */ [ZIG]: ZigCanvas;
+    /** @internal — only `Canvas.getContext('2d')` constructs these. */
+    constructor(canvas: Canvas, zig: ZigCanvas);
+    get canvas(): Canvas;
+    getContextAttributes(): {
+        alpha: boolean;
+        colorSpace: 'srgb';
+        desynchronized: boolean;
+        willReadFrequently: boolean;
+    };
+    /**
+     * Drop the JS-side references this context holds. The underlying SmCanvas
+     * is owned by the SmSurface and is deinit'd when `Canvas#destroy()` runs;
+     * this method is a no-op for Zig memory but releases JS-held strong refs
+     * to gradient / pattern style objects so they GC sooner. Idempotent.
+     */
+    destroy(): void;
+    [Symbol.dispose](): void;
+    save(): void;
+    restore(): void;
+    reset(): void;
+    translate(tx: number, ty: number): void;
+    rotate(angleRadians: number): void;
+    scale(sx: number, sy: number): void;
+    transform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    resetTransform(): void;
+    getTransform(): DOMMatrix;
+    get fillStyle(): string | CanvasGradient | CanvasPattern;
+    set fillStyle(v: string | CanvasGradient | CanvasPattern);
+    get strokeStyle(): string | CanvasGradient | CanvasPattern;
+    set strokeStyle(v: string | CanvasGradient | CanvasPattern);
+    get lineWidth(): number;
+    set lineWidth(v: number);
+    get lineCap(): string;
+    set lineCap(v: string);
+    get lineJoin(): string;
+    set lineJoin(v: string);
+    get miterLimit(): number;
+    set miterLimit(v: number);
+    get lineDashOffset(): number;
+    set lineDashOffset(v: number);
+    setLineDash(segments: number[]): void;
+    getLineDash(): number[];
+    get globalAlpha(): number;
+    set globalAlpha(v: number);
+    get globalCompositeOperation(): string;
+    set globalCompositeOperation(v: string);
+    fillRect(x: number, y: number, w: number, h: number): void;
+    strokeRect(x: number, y: number, w: number, h: number): void;
+    clearRect(x: number, y: number, w: number, h: number): void;
+    beginPath(): void;
+    closePath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    arc(cx: number, cy: number, r: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    arcTo(x1: number, y1: number, x2: number, y2: number, r: number): void;
+    roundRect(x: number, y: number, w: number, h: number, radii?: number | DOMPointInit | Array<number | DOMPointInit>): void;
+    ellipse(cx: number, cy: number, rx: number, ry: number, rotation: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    fill(pathOrRule?: Path2D | 'nonzero' | 'evenodd', maybeRule?: 'nonzero' | 'evenodd'): void;
+    stroke(path?: Path2D): void;
+    isPointInPath(x: number, y: number, fillRule?: 'nonzero' | 'evenodd'): boolean;
+    isPointInPath(path: Path2D, x: number, y: number, fillRule?: 'nonzero' | 'evenodd'): boolean;
+    isPointInStroke(x: number, y: number): boolean;
+    isPointInStroke(path: Path2D, x: number, y: number): boolean;
+    clip(pathOrRule?: Path2D | 'nonzero' | 'evenodd', maybeRule?: 'nonzero' | 'evenodd'): void;
+    get font(): string;
+    set font(v: string);
+    get textAlign(): string;
+    set textAlign(v: string);
+    get textBaseline(): string;
+    set textBaseline(v: string);
+    get direction(): string;
+    set direction(v: string);
+    get letterSpacing(): string;
+    set letterSpacing(v: string);
+    get wordSpacing(): string;
+    set wordSpacing(v: string);
+    get fontKerning(): string;
+    set fontKerning(v: string);
+    get fontStretch(): string;
+    set fontStretch(v: string);
+    get fontVariantCaps(): string;
+    set fontVariantCaps(v: string);
+    get textRendering(): string;
+    set textRendering(v: string);
+    get filter(): string;
+    set filter(v: string);
+    get shadowBlur(): number;
+    set shadowBlur(v: number);
+    get shadowColor(): string;
+    set shadowColor(v: string);
+    get shadowOffsetX(): number;
+    set shadowOffsetX(v: number);
+    get shadowOffsetY(): number;
+    set shadowOffsetY(v: number);
+    get imageSmoothingEnabled(): boolean;
+    set imageSmoothingEnabled(v: boolean);
+    get imageSmoothingQuality(): string;
+    set imageSmoothingQuality(v: string);
+    fillText(text: string, x: number, y: number, _maxWidth?: number): void;
+    strokeText(text: string, x: number, y: number, maxWidth?: number): void;
+    measureText(text: string): TextMetrics;
+    createImageData(width: number, height: number, settings?: ImageDataSettings): ImageData;
+    createImageData(imagedata: ImageData): ImageData;
+    getImageData(sx: number, sy: number, sw: number, sh: number, settings?: ImageDataSettings): ImageData;
+    putImageData(imageData: ImageData, dx: number, dy: number, dirtyX?: number, dirtyY?: number, dirtyW?: number, dirtyH?: number): void;
+    drawImage(image: ImageData | Image | Canvas, dx: number, dy: number): void;
+    drawImage(image: ImageData | Image | Canvas, dx: number, dy: number, dw: number, dh: number): void;
+    drawImage(image: ImageData | Image | Canvas, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number): CanvasGradient;
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): CanvasGradient;
+    createConicGradient(startAngle: number, x: number, y: number): CanvasGradient;
+    createPattern(image: ImageData | Image | Canvas, repetition: string | null): CanvasPattern;
+}
+export declare class Canvas {
+    #private;
+    /** @internal */ [ZIG]: ZigSurface;
+    constructor(width: number, height: number, opts?: CanvasOptions);
+    get width(): number;
+    set width(n: number);
+    get height(): number;
+    set height(n: number);
+    getContext(kind: '2d', _attrs?: object): CanvasRenderingContext2D;
+    toDataURL(type?: string, quality?: number): string;
+    /**
+     * Encode the canvas and return the raw bytes. Skips the base64 round-trip
+     * that `toDataURL()` does — pass directly to `new Response(...)`,
+     * `fs.writeFile`, etc.
+     *
+     * `type` defaults to `'image/png'`; `'image/jpeg'` is also supported with
+     * an optional `quality` in the HTML5 0.0–1.0 range (default 0.92).
+     *
+     * The returned `Uint8Array` is a JS-owned defensive copy; safe to retain
+     * past further drawing.
+     */
+    toBytes(type?: string, quality?: number): Uint8Array;
+    /**
+     * Promise-returning sibling of `toBytes`. Mirrors `@napi-rs/canvas`'s
+     * `encode(format)`: encodes off the JS thread on Node (real pthread
+     * offload via zigar's WorkQueue — equivalent to N-API `AsyncWorker`).
+     *
+     * On WASM targets — browsers, Cloudflare Workers, edge runtimes — the
+     * Zig WorkQueue is comptime-gated out and this falls through to a
+     * microtask-yielded sync encode. CF Workers can't spawn worker threads
+     * in any case, so the API shape stays uniform; only the offload behavior
+     * differs by target.
+     */
+    toBytesAsync(type?: string, quality?: number): Promise<Uint8Array>;
+    /**
+     * Promise-returning sibling of `toDataURL`. Built on top of
+     * `toBytesAsync`, so the same target-dependent offload story applies —
+     * see that method's docstring.
+     */
+    toDataURLAsync(type?: string, quality?: number): Promise<string>;
+    /**
+     * Eagerly release the underlying Zig surface (pixel buffer, cached
+     * SmCanvas, last encoded payload). Idempotent. Calling any other method
+     * after `destroy()` is undefined behavior — the wrapper's Zig handle is
+     * dangling. Mirrors the pdf.js `BaseCanvasFactory#destroy` contract and
+     * supports the Stage-3 `using` syntax (via `Symbol.dispose`).
+     *
+     * Without this, the same cleanup happens lazily through the
+     * FinalizationRegistry when the wrapper is GC'd. Use `destroy()` to
+     * release sooner — large canvases on long-lived servers, request-scoped
+     * canvases under Cloudflare Workers' tight memory caps, etc.
+     */
+    destroy(): void;
+    [Symbol.dispose](): void;
+}
+export declare function createCanvas(width: number, height: number, opts?: CanvasOptions): Canvas;
+export { microsharp, MicroSharpPipeline } from './microsharp/index.ts';
+export type { ImageFormat, ImageFormatName, ResizeOptions, ResizeKernel, ResizeFit, ResizePosition, ExtendOptions, ExtendWithMode, ExtractRegion, TrimOptions, CompositeImage, CompositeBlend, CompositeGravity, CompositeOverlayInput, CompositeRawDescriptor, CompositeCreateInput, ChannelSelector, BandBoolOp, PngOptions, JpegOptions, Metadata, MicroSharpInput, BackgroundInput, BackgroundColor, OutputInfo, ToBufferOptions, } from './microsharp/index.ts';
+export { parseCssColor };
+/**
+ * WASM source accepted by async `init()`.
+ */
+export type InitInput = ArrayBuffer | ArrayBufferView | Response | WebAssembly.Module | Promise<ArrayBuffer | ArrayBufferView | Response | WebAssembly.Module>;
+/**
+ * Synchronous init from a pre-compiled `WebAssembly.Module`. Designed for
+ * Cloudflare Workers / Vercel Edge — call at module-init scope:
+ *
+ *     import { initSync, createCanvas } from 'simdra/wasm';
+ *     import wasm from 'simdra/wasm/simdra.wasm';
+ *     initSync(wasm);
+ *
+ * Workers forbids `WebAssembly.compile()` on raw bytes, but allows
+ * `new WebAssembly.Instance(precompiledModule, imports)`. The runtime
+ * compiles the imported `.wasm` at deploy time, so this stays sync.
+ *
+ * In dev (`npm test` via node-zigar) zigar loads the module itself, so this
+ * is a no-op.
+ */
+export declare function initSync(mod: WebAssembly.Module): void;
+/**
+ * Async init for environments where `WebAssembly.compile()` is allowed
+ * (Node, browsers). Accepts bytes / Response / a `Module`. Idempotent.
+ */
+export default function init(input?: InitInput): Promise<void>;