@slothpdf/render 0.4.0

package/README.md

@@ -0,0 +1,242 @@
+# @slothpdf/render
+
+Fast PDF generation from templates. **16,000+ PDFs per second.** No headless browser.
+
+Built on a native engine written in Zig — no Puppeteer, no Chrome, no runtime overhead. Constant memory.
+
+## Install
+
+```bash
+bun add @slothpdf/render
+```
+
+> Requires [Bun](https://bun.sh) v1.1+. The correct native binary is installed automatically.
+
+## Quick start
+
+```ts
+import { render } from "@slothpdf/render";
+
+const pdf = render(`
+  <Page size="A4" margin="20mm">
+    <Box class="text-2xl font-bold mb-4">Hello, {name}!</Box>
+    <Box class="text-sm text-gray-600">{description}</Box>
+  </Page>
+`, { name: "World", description: "Generated with SlothPDF" });
+
+await Bun.write("hello.pdf", pdf);
+```
+
+## Batch
+
+Pass an array and `render` yields one PDF per row:
+
+```ts
+for (const { index, buffer } of render(template, invoices)) {
+  await Bun.write(`invoices/${index}.pdf`, buffer);
+}
+```
+
+## Merge
+
+All rows into a single multi-page PDF:
+
+```ts
+await Bun.write("report.pdf", render(template, rows, { merge: true }));
+```
+
+## ZIP
+
+All rows as a ZIP archive:
+
+```ts
+await Bun.write("invoices.zip", render(template, rows, { zip: true }));
+```
+
+## Encryption
+
+AES-256 password protection:
+
+```ts
+await Bun.write("secure.pdf", render(template, data, { password: "secret" }));
+```
+
+Works with all modes — single, merge, zip, compress.
+
+## Init
+
+Preload fonts and images at startup. Skips assets already loaded.
+
+```ts
+import { init, render } from "@slothpdf/render";
+
+init({
+  fonts: {
+    Inter: { regular: "fonts/Inter-Regular.ttf", bold: "fonts/Inter-Bold.ttf" },
+    Mono: "fonts/JetBrainsMono-Regular.ttf",
+  },
+  images: {
+    logo: "assets/logo.png",
+  },
+});
+```
+
+## Custom fonts
+
+```ts
+import { loadFont } from "@slothpdf/render";
+
+loadFont("Inter", await Bun.file("Inter-Regular.ttf").bytes());
+loadFont("Inter", await Bun.file("Inter-Bold.ttf").bytes(), "bold");
+```
+
+```
+<Page size="A4" margin="20mm" font="Inter">
+  <Box class="font-bold">This renders in Inter Bold</Box>
+</Page>
+```
+
+## Images
+
+```ts
+import { loadImage } from "@slothpdf/render";
+
+loadImage("logo", await Bun.file("logo.png").bytes());
+```
+
+```
+<Image src="logo" class="w-32" />
+```
+
+## QR codes
+
+```
+<QrCode src="https://example.com/pay/inv-042" class="h-[120]" />
+```
+
+## Page headers & footers
+
+```
+<Page size="A4" margin="20mm">
+  <PageHeader class="flex-row border-b border-gray-200 pb-3">
+    <Box class="text-lg font-bold">Acme Corp</Box>
+    <Box class="text-right text-sm">Invoice #2026-042</Box>
+  </PageHeader>
+
+  <!-- page content -->
+
+  <PageFooter class="flex-row border-t border-gray-200 pt-2 text-xs text-gray-400">
+    <Box>hello@acme.com</Box>
+    <Box class="text-right">Page {page}</Box>
+  </PageFooter>
+</Page>
+```
+
+## Template syntax
+
+Templates use an HTML-like markup with utility classes. If you've built a web page, the syntax will feel familiar.
+
+**Elements:** `Page`, `Box`, `Text`, `Image`, `QrCode`, `Line`, `Columns`, `Column`, `PageHeader`, `PageFooter`
+
+**Layout:** `flex-row`, `flex-col`, `justify-between`, `items-center`, `gap-4`
+
+**Sizing:** `w-1/2`, `w-full`, `h-16`
+
+**Spacing:** `p-4`, `px-6`, `mt-2`, `mb-8`
+
+**Typography:** `text-sm`, `text-2xl`, `font-bold`, `text-gray-500`, `text-center`
+
+**Data:** `{field}`, `{nested.field}`, `each="arrayField"`, `when="condition"`
+
+```
+<Box each="items" class="flex-row py-2 border-b border-gray-100">
+  <Box class="w-2/3 text-sm">{name}</Box>
+  <Box class="w-1/3 text-sm text-right">{price}</Box>
+</Box>
+
+<Box when="discount" class="text-green-600">
+  Discount applied: {discount}
+</Box>
+```
+
+## CLI
+
+```bash
+slothpdf render template.sloth data.json -o output.pdf
+slothpdf batch template.sloth rows.json -o invoices/
+slothpdf render template.sloth --font "Inter=Inter-Regular.ttf" --compress -o out.pdf
+```
+
+## API reference
+
+### `render(template, data?, options?)`
+
+The only function you need. Behavior depends on what you pass:
+
+| Call | Returns |
+|------|---------|
+| `render(template, object)` | `Buffer` — single PDF |
+| `render(template, array)` | `Generator<{ index, buffer }>` — one PDF per row |
+| `render(template, array, { merge: true })` | `Buffer` — one multi-page PDF |
+| `render(template, array, { zip: true })` | `Buffer` — ZIP archive |
+
+**Options:**
+- **compress** `boolean` — FlateDecode compression (smaller files)
+- **password** `string` — AES-256 encryption
+- **merge** `boolean` — combine all rows into one PDF
+- **zip** `boolean` — package all PDFs into a ZIP
+
+All options are additive — `{ compress: true, password: "secret", merge: true }` works.
+
+### `init(options)`
+
+Preload fonts and images from file paths. Skips assets already loaded.
+
+### `loadFont(name, ttf, variant?)`
+
+Register a TrueType font. Variant: `"regular"` | `"bold"` | `"italic"`.
+
+### `loadImage(key, data)` · `hasImage(key)` · `clearImages()`
+
+Register, check, or clear images for `<Image src="key" />`.
+
+### `hasFont(name)`
+
+Check if a font family is loaded. Returns `boolean`.
+
+## Performance
+
+Benchmarked on Apple M4, single-threaded, 1000 unique invoices with 3–10 line items:
+
+| Mode | Latency | Throughput |
+|------|---------|------------|
+| No encryption | 0.057ms | **17,600 /sec** |
+| AES-256 encrypted | 0.067ms | **14,900 /sec** |
+
+Memory is constant after warmup — 50,000 renders with no growth.
+
+Compared to other tools:
+
+| Tool | ~Speed |
+|------|--------|
+| **SlothPDF** | **17,600 /sec** |
+| jsPDF | 7,750 /sec |
+| Chromium/Puppeteer | ~18 /sec |
+| wkhtmltopdf | ~8 /sec |
+
+## Platforms
+
+| Platform | Package |
+|----------|---------|
+| macOS arm64 | `@slothpdf/darwin-arm64` |
+| Linux x64 | `@slothpdf/linux-x64` |
+
+Set `SLOTHPDF_LIB` to use a custom binary path.
+
+## Playground
+
+Build and preview templates at [slothpdf.jsoto.cloud/editor](https://slothpdf.jsoto.cloud/editor).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@slothpdf/render",
+  "version": "0.4.0",
+  "description": "Fast PDF generation from templates. 16,000+ PDFs/sec. No headless browser.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "slothpdf": "src/cli.ts"
+  },
+  "files": ["src", "README.md"],
+  "keywords": [
+    "pdf", "pdf-generation", "template", "render", "batch",
+    "invoice", "receipt", "report", "html-to-pdf", "fast",
+    "zig", "native", "bun"
+  ],
+  "author": "SlothPDF",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voidzer0-dev/slothpdf-render"
+  },
+  "homepage": "https://slothpdf.jsoto.cloud",
+  "bugs": {
+    "url": "https://github.com/voidzer0-dev/slothpdf-render/issues"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "optionalDependencies": {
+    "@slothpdf/darwin-arm64": "0.4.0",
+    "@slothpdf/linux-x64": "0.4.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env bun
+/**
+ * SlothPDF CLI
+ *
+ * Usage:
+ *   slothpdf render template.sloth [data.json] [-o output.pdf]
+ *   slothpdf batch  template.sloth data.json [-o outdir/]
+ *
+ * data.json for batch: array of objects, one PDF per element.
+ */
+
+import { render, batch, loadFont } from "./index";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join, basename, extname } from "path";
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+function usage(): never {
+  console.log(`
+  slothpdf — fast PDF generation from templates
+
+  Usage:
+    slothpdf render template.sloth [data.json] [-o output.pdf]
+    slothpdf batch  template.sloth data.json [-o outdir/] [--name field]
+
+  Options:
+    -o          Output path (file for render, directory for batch)
+    --name      JSON field to use for filenames in batch mode
+    --font      Load a TTF font: --font "Name=path.ttf" or --font "Name:bold=path.ttf"
+    --compress  Enable FlateDecode compression
+`);
+  process.exit(1);
+}
+
+if (!cmd || cmd === "--help" || cmd === "-h") usage();
+
+// Parse flags
+function flag(name: string): string | undefined {
+  const i = args.indexOf(name);
+  if (i === -1) return undefined;
+  return args[i + 1];
+}
+function hasFlag(name: string): boolean {
+  return args.includes(name);
+}
+
+// Load fonts from --font flags
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--font" && args[i + 1]) {
+    const spec = args[i + 1];
+    const [nameSpec, path] = spec.split("=");
+    if (!path) { console.error(`Invalid --font: ${spec}. Use "Name=path.ttf"`); process.exit(1); }
+    const [name, variant] = nameSpec.split(":");
+    const ttf = readFileSync(path);
+    loadFont(name, ttf, (variant as "regular" | "bold" | "italic") ?? "regular");
+    i++;
+  }
+}
+
+const compress = hasFlag("--compress");
+
+if (cmd === "render") {
+  const templatePath = args[1];
+  if (!templatePath) usage();
+  const template = readFileSync(templatePath, "utf-8");
+
+  const dataPath = args.find((a, i) => i > 1 && !a.startsWith("-") && a !== flag("-o"));
+  const data = dataPath ? JSON.parse(readFileSync(dataPath, "utf-8")) : undefined;
+
+  const out = flag("-o") ?? "output.pdf";
+  const t0 = performance.now();
+  const pdf = render(template, data, { compress });
+  const elapsed = performance.now() - t0;
+
+  writeFileSync(out, pdf);
+  console.log(`${out} (${(pdf.length / 1024).toFixed(1)}KB) in ${elapsed.toFixed(1)}ms`);
+
+} else if (cmd === "batch") {
+  const templatePath = args[1];
+  const dataPath = args[2];
+  if (!templatePath || !dataPath) usage();
+
+  const template = readFileSync(templatePath, "utf-8");
+  const rows: Record<string, unknown>[] = JSON.parse(readFileSync(dataPath, "utf-8"));
+  if (!Array.isArray(rows)) { console.error("Data must be a JSON array"); process.exit(1); }
+
+  const outDir = flag("-o") ?? "out";
+  const nameField = flag("--name");
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+
+  const t0 = performance.now();
+  let totalBytes = 0;
+  for (const { index, buffer } of batch(template, rows, { compress })) {
+    const name = nameField && rows[index][nameField]
+      ? String(rows[index][nameField])
+      : String(index + 1).padStart(String(rows.length).length, "0");
+    writeFileSync(join(outDir, `${name}.pdf`), buffer);
+    totalBytes += buffer.length;
+  }
+  const elapsed = performance.now() - t0;
+
+  console.log(`${rows.length} PDFs → ${outDir}/ (${(totalBytes / 1024 / 1024).toFixed(1)}MB) in ${elapsed.toFixed(0)}ms | ${(elapsed / rows.length).toFixed(2)}ms/pdf`);
+
+} else {
+  console.error(`Unknown command: ${cmd}`);
+  usage();
+}

package/src/index.ts

@@ -0,0 +1,365 @@
+/**
+ * @slothpdf/render — Fast PDF generation from templates.
+ *
+ * @example
+ * ```ts
+ * import { render, loadFont } from "@slothpdf/render";
+ *
+ * // Single PDF
+ * const pdf = render(template, { name: "Acme" });
+ *
+ * // Batch — one PDF per row
+ * for (const { index, buffer } of render(template, rows)) {
+ *   fs.writeFileSync(`out/${index}.pdf`, buffer);
+ * }
+ *
+ * // Merge — all rows into one multi-page PDF
+ * const merged = render(template, rows, { merge: true });
+ *
+ * // ZIP — all rows as a ZIP archive
+ * const zip = render(template, rows, { zip: true });
+ * ```
+ */
+
+import { lib, ptr, toArrayBuffer } from "./native";
+
+/** Copy bytes from a Zig-owned pointer into a new Buffer.
+ *  The copy must complete before the Zig memory is freed. */
+function copyFromPtr(p: any, len: number): Buffer {
+  const view = toArrayBuffer(p, 0, len)!;
+  const copy = Buffer.alloc(len);
+  copy.set(new Uint8Array(view));
+  return copy;
+}
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface RenderOptions {
+  compress?: boolean;
+  password?: string;
+  merge?: boolean;
+  zip?: boolean;
+}
+
+export interface BatchItem {
+  index: number;
+  buffer: Buffer;
+}
+
+// ── Render ───────────────────────────────────────────────────────────
+
+/**
+ * Render PDFs from a template and data.
+ *
+ * - Object → single PDF (Buffer)
+ * - Array → generator yielding one PDF per row
+ * - Array + `{ merge: true }` → single multi-page PDF (Buffer)
+ * - Array + `{ zip: true }` → ZIP archive of all PDFs (Buffer)
+ */
+export function render(
+  template: string,
+  data: Record<string, unknown>[],
+  options: RenderOptions & { merge: true },
+): Buffer;
+export function render(
+  template: string,
+  data: Record<string, unknown>[],
+  options: RenderOptions & { zip: true },
+): Buffer;
+export function render(
+  template: string,
+  data: Record<string, unknown>[],
+  options?: RenderOptions,
+): Generator<BatchItem>;
+export function render(
+  template: string,
+  data?: Record<string, unknown>,
+  options?: RenderOptions,
+): Buffer;
+export function render(
+  template: string,
+  data?: Record<string, unknown> | Record<string, unknown>[],
+  options?: RenderOptions,
+): Buffer | Generator<BatchItem> {
+  if (Array.isArray(data)) {
+    if (options?.merge) return _renderMerge(template, data, options);
+    if (options?.zip) return _renderZip(template, data, options);
+    return _renderBatch(template, data, options);
+  }
+  return _renderOne(template, data, options);
+}
+
+// ── Single render ────────────────────────────────────────────────────
+
+function _renderOne(
+  template: string,
+  data?: Record<string, unknown>,
+  options?: RenderOptions,
+): Buffer {
+  const l = lib();
+  const templateBuf = Buffer.from(template);
+  const jsonBuf = data ? Buffer.from(JSON.stringify(data)) : null;
+  const pwBuf = options?.password ? Buffer.from(options.password) : null;
+  const flags = options?.compress ? 1 : 0;
+
+  const result = l.symbols.slothpdf_render_pdf(
+    ptr(templateBuf), templateBuf.length,
+    jsonBuf ? ptr(jsonBuf) : null, jsonBuf?.length ?? 0,
+    null, 0,
+    pwBuf ? ptr(pwBuf) : null, pwBuf?.length ?? 0,
+    flags,
+  );
+
+  if (!result) throw new Error("SlothPDF render failed");
+
+  const p = l.symbols.slothpdf_result_ptr(result);
+  const len = Number(l.symbols.slothpdf_result_len(result));
+  const pdf = copyFromPtr(p!, len);
+  l.symbols.slothpdf_result_free(result);
+
+  return pdf;
+}
+
+// ── Batch render (generator) ─────────────────────────────────────────
+
+function* _renderBatch(
+  template: string,
+  rows: Record<string, unknown>[],
+  options?: RenderOptions,
+): Generator<BatchItem> {
+  for (let i = 0; i < rows.length; i++) {
+    yield { index: i, buffer: _renderOne(template, rows[i], options) };
+  }
+}
+
+// ── Merge render ─────────────────────────────────────────────────────
+
+function _renderMerge(
+  template: string,
+  rows: Record<string, unknown>[],
+  options?: RenderOptions,
+): Buffer {
+  const l = lib();
+  const templateBuf = Buffer.from(template);
+  const packed = packRows(rows);
+  const pwBuf = options?.password ? Buffer.from(options.password) : null;
+  const flags = (options?.compress ? 1 : 0) | 2; // bit 1 = merge mode
+
+  const result = l.symbols.slothpdf_render_pdf(
+    ptr(templateBuf), templateBuf.length,
+    ptr(packed), packed.length,
+    null, 0,
+    pwBuf ? ptr(pwBuf) : null, pwBuf?.length ?? 0,
+    flags,
+  );
+
+  if (!result) throw new Error("SlothPDF merge failed");
+
+  const p = l.symbols.slothpdf_result_ptr(result);
+  const len = Number(l.symbols.slothpdf_result_len(result));
+  const pdf = copyFromPtr(p!, len);
+  l.symbols.slothpdf_result_free(result);
+
+  return pdf;
+}
+
+// ── ZIP render ───────────────────────────────────────────────────────
+
+function _renderZip(
+  template: string,
+  rows: Record<string, unknown>[],
+  options?: RenderOptions,
+): Buffer {
+  // Render each PDF individually (supports all options), then ZIP
+  const pdfs: Buffer[] = [];
+  for (let i = 0; i < rows.length; i++) {
+    pdfs.push(_renderOne(template, rows[i], options));
+  }
+
+  const pad = String(rows.length).length;
+  const entries = pdfs.map((buf, i) => ({
+    name: `${String(i + 1).padStart(pad, "0")}.pdf`,
+    data: buf,
+  }));
+
+  return buildZip(entries);
+}
+
+function buildZip(entries: { name: string; data: Buffer }[]): Buffer {
+  const parts: Buffer[] = [];
+  const centralDir: Buffer[] = [];
+  let offset = 0;
+
+  for (const { name, data } of entries) {
+    const nameBytes = Buffer.from(name);
+    const crc = crc32(data);
+
+    // Local file header
+    const local = Buffer.alloc(30 + nameBytes.length);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(data.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(nameBytes.length, 26);
+    nameBytes.copy(local, 30);
+    parts.push(local, data);
+
+    // Central directory entry
+    const cd = Buffer.alloc(46 + nameBytes.length);
+    cd.writeUInt32LE(0x02014b50, 0);
+    cd.writeUInt16LE(20, 4);
+    cd.writeUInt16LE(20, 6);
+    cd.writeUInt32LE(crc, 16);
+    cd.writeUInt32LE(data.length, 20);
+    cd.writeUInt32LE(data.length, 24);
+    cd.writeUInt16LE(nameBytes.length, 28);
+    cd.writeUInt32LE(offset, 42);
+    nameBytes.copy(cd, 46);
+    centralDir.push(cd);
+
+    offset += local.length + data.length;
+  }
+
+  let cdSize = 0;
+  for (const cd of centralDir) cdSize += cd.length;
+
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(entries.length, 8);
+  eocd.writeUInt16LE(entries.length, 10);
+  eocd.writeUInt32LE(cdSize, 12);
+  eocd.writeUInt32LE(offset, 16);
+
+  return Buffer.concat([...parts, ...centralDir, eocd]);
+}
+
+function crc32(buf: Buffer): number {
+  let crc = 0xFFFFFFFF;
+  for (let i = 0; i < buf.length; i++) {
+    crc ^= buf[i];
+    for (let j = 0; j < 8; j++) crc = (crc >>> 1) ^ (crc & 1 ? 0xEDB88320 : 0);
+  }
+  return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+
+// ── Internal helpers ─────────────────────────────────────────────────
+
+function packRows(rows: Record<string, unknown>[]): Buffer {
+  const jsonStrings = rows.map(r => JSON.stringify(r));
+  const totalLen = 4 + jsonStrings.reduce((s, j) => s + 4 + Buffer.byteLength(j), 0);
+  const buf = Buffer.alloc(totalLen);
+  buf.writeUInt32LE(rows.length, 0);
+  let offset = 4;
+  for (const j of jsonStrings) {
+    const len = Buffer.byteLength(j);
+    buf.writeUInt32LE(len, offset); offset += 4;
+    buf.write(j, offset); offset += len;
+  }
+  return buf;
+}
+
+// ── Fonts ────────────────────────────────────────────────────────────
+
+/**
+ * Register a TrueType font for use in templates.
+ */
+export function loadFont(
+  name: string,
+  ttf: Buffer,
+  variant: "regular" | "bold" | "italic" = "regular",
+): void {
+  const l = lib();
+  const nameBuf = Buffer.from(name);
+  const v = variant === "bold" ? 1 : variant === "italic" ? 2 : 0;
+  l.symbols.slothpdf_load_font(ptr(nameBuf), nameBuf.length, ptr(ttf), ttf.length, v);
+}
+
+/**
+ * Check if a font family is loaded.
+ */
+export function hasFont(name: string): boolean {
+  const l = lib();
+  const buf = Buffer.from(name);
+  return l.symbols.slothpdf_has_font(ptr(buf), buf.length) === 1;
+}
+
+// ── Images ───────────────────────────────────────────────────────────
+
+/**
+ * Register an image by key for use in templates via `src="{key}"`.
+ */
+export function loadImage(key: string, data: Buffer): void {
+  const l = lib();
+  const keyBuf = Buffer.from(key);
+  l.symbols.slothpdf_register_image(ptr(keyBuf), keyBuf.length, ptr(data), data.length);
+}
+
+/**
+ * Check if an image is registered.
+ */
+export function hasImage(key: string): boolean {
+  const l = lib();
+  const buf = Buffer.from(key);
+  return l.symbols.slothpdf_has_image(ptr(buf), buf.length) === 1;
+}
+
+/**
+ * Clear all registered images.
+ */
+export function clearImages(): void {
+  lib().symbols.slothpdf_clear_images();
+}
+
+// ── Init ─────────────────────────────────────────────────────────────
+
+export interface FontConfig {
+  regular?: string;
+  bold?: string;
+  italic?: string;
+}
+
+export interface InitOptions {
+  fonts?: Record<string, FontConfig | string>;
+  images?: Record<string, string>;
+}
+
+/**
+ * Preload fonts and images at startup. Skips assets already loaded.
+ *
+ * @example
+ * ```ts
+ * init({
+ *   fonts: {
+ *     Inter: { regular: "fonts/Inter-Regular.ttf", bold: "fonts/Inter-Bold.ttf" },
+ *     Mono: "fonts/JetBrainsMono-Regular.ttf", // shorthand for { regular: ... }
+ *   },
+ *   images: {
+ *     logo: "assets/logo.png",
+ *   },
+ * });
+ * ```
+ */
+export function init(options: InitOptions): void {
+  const { readFileSync } = require("fs");
+
+  if (options.fonts) {
+    for (const [name, config] of Object.entries(options.fonts)) {
+      const variants = typeof config === "string" ? { regular: config } : config;
+      for (const [variant, path] of Object.entries(variants)) {
+        if (!path) continue;
+        if (!hasFont(name)) {
+          loadFont(name, readFileSync(path), variant as "regular" | "bold" | "italic");
+        }
+      }
+    }
+  }
+
+  if (options.images) {
+    for (const [key, path] of Object.entries(options.images)) {
+      if (!hasImage(key)) {
+        loadImage(key, readFileSync(path));
+      }
+    }
+  }
+}

package/src/native.ts

@@ -0,0 +1,77 @@
+/**
+ * Native FFI bridge to libslothpdf.
+ * Internal module — not exported to users.
+ */
+import { dlopen, FFIType, ptr, toArrayBuffer } from "bun:ffi";
+import { join } from "path";
+import { existsSync } from "fs";
+
+// ── Binary resolution ────────────────────────────────────────────────
+
+const LIB_EXT = process.platform === "darwin" ? "dylib" : "so";
+
+function findLibrary(): string {
+  // 1. Explicit env override
+  if (process.env.SLOTHPDF_LIB) return process.env.SLOTHPDF_LIB;
+
+  // 2. Platform-specific optional dependency (@slothpdf/darwin-arm64, etc.)
+  const platform = process.platform === "darwin" ? "darwin" : "linux";
+  const arch = process.arch === "arm64" ? "arm64" : "x64";
+  const pkgName = `@slothpdf/${platform}-${arch}`;
+  try {
+    const pkgPath = require.resolve(`${pkgName}/libslothpdf.${LIB_EXT}`);
+    if (existsSync(pkgPath)) return pkgPath;
+  } catch {}
+
+  // 3. Monorepo development path
+  const devPath = join(import.meta.dir, `../../../engine/zig-out/lib/libslothpdf.${LIB_EXT}`);
+  if (existsSync(devPath)) return devPath;
+
+  throw new Error(
+    `SlothPDF native binary not found. Install the platform package:\n  bun add ${pkgName}\n\nOr set SLOTHPDF_LIB to the path of libslothpdf.${LIB_EXT}`
+  );
+}
+
+// ── FFI symbols ──────────────────────────────────────────────────────
+
+const SYMBOLS = {
+  // Single render
+  slothpdf_render_pdf: {
+    args: [FFIType.ptr, FFIType.u64, FFIType.ptr, FFIType.u64, FFIType.ptr, FFIType.u64, FFIType.ptr, FFIType.u64, FFIType.u32],
+    returns: FFIType.ptr,
+  },
+  // Result accessors
+  slothpdf_result_ptr: { args: [FFIType.ptr], returns: FFIType.ptr },
+  slothpdf_result_len: { args: [FFIType.ptr], returns: FFIType.u64 },
+  slothpdf_result_free: { args: [FFIType.ptr], returns: FFIType.void },
+  // Streaming batch
+  slothpdf_stream_begin: { args: [FFIType.ptr, FFIType.u64, FFIType.u32], returns: FFIType.ptr },
+  slothpdf_stream_next: { args: [FFIType.ptr, FFIType.ptr, FFIType.u64], returns: FFIType.bool },
+  slothpdf_stream_pdf_ptr: { args: [FFIType.ptr], returns: FFIType.ptr },
+  slothpdf_stream_pdf_len: { args: [FFIType.ptr], returns: FFIType.u64 },
+  slothpdf_stream_end: { args: [FFIType.ptr], returns: FFIType.void },
+  // Batch + zip
+  slothpdf_render_batch: { args: [FFIType.ptr, FFIType.u64, FFIType.ptr, FFIType.u64, FFIType.u32], returns: FFIType.ptr },
+  slothpdf_batch_count: { args: [FFIType.ptr], returns: FFIType.u32 },
+  slothpdf_batch_free: { args: [FFIType.ptr], returns: FFIType.void },
+  slothpdf_batch_to_zip: { args: [FFIType.ptr, FFIType.u32], returns: FFIType.ptr },
+  // Fonts & images
+  slothpdf_load_font: { args: [FFIType.ptr, FFIType.u64, FFIType.ptr, FFIType.u64, FFIType.u8], returns: FFIType.void },
+  slothpdf_has_font: { args: [FFIType.ptr, FFIType.u64], returns: FFIType.u8 },
+  slothpdf_register_image: { args: [FFIType.ptr, FFIType.u64, FFIType.ptr, FFIType.u64], returns: FFIType.void },
+  slothpdf_has_image: { args: [FFIType.ptr, FFIType.u64], returns: FFIType.u8 },
+  slothpdf_clear_images: { args: [], returns: FFIType.void },
+} as const;
+
+type Lib = ReturnType<typeof dlopen<typeof SYMBOLS>>;
+
+// ── Singleton ────────────────────────────────────────────────────────
+
+let _lib: Lib | null = null;
+
+export function lib(): Lib {
+  if (!_lib) _lib = dlopen(findLibrary(), SYMBOLS);
+  return _lib;
+}
+
+export { ptr, toArrayBuffer };