@c9up/vellum 0.1.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@c9up/vellum",
+  "version": "0.1.0",
+  "description": "PDF toolkit — convert PDF pages to images, author and inspect documents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "index.*.node",
+    "scripts",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/VellumProvider.d.ts",
+      "import": "./dist/VellumProvider.js"
+    },
+    "./configure": {
+      "types": "./dist/configure.d.ts",
+      "import": "./dist/configure.js"
+    },
+    "./services/main": {
+      "types": "./dist/services/main.d.ts",
+      "import": "./dist/services/main.js"
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@c9up/ream": "^0.2.0",
+    "@types/node": "^22.19.15",
+    "@vitest/coverage-v8": "^4.1.2",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/vellum.git"
+  },
+  "peerDependencies": {
+    "@c9up/ream": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@c9up/ream": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:napi": "cargo build --release -p vellum-engine-napi && pnpm build:napi-types && node scripts/copy-napi.mjs",
+    "build:napi-types": "node scripts/build-napi-types.mjs",
+    "test": "vitest run",
+    "test:rust": "cargo test",
+    "lint": "biome check src/ tests/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/scripts/build-napi-types.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Regenerate `src/native/generated.ts` from the Rust.
+ *
+ * Node rather than a shell script because this runs inside `build:napi`, and
+ * that runs on the Windows prebuild runner too: a bash `mktemp` there hands
+ * cargo a `/tmp/...` path the native proc-macro cannot write to, so the
+ * type-def file comes back empty and the build fails for no visible reason.
+ *
+ * One crate at a time on purpose: with napi-derive 2 the writes all went to a
+ * single `TYPE_DEF_TMP_PATH` and a parallel build interleaved them
+ * while cargo compiles, and a parallel build interleaves the writes —
+ * definitions go missing, silently, and the generated file comes out short.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const CRATES = ['vellum-engine-napi']
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+const output = join('src', 'native', 'generated.ts')
+const scratch = mkdtempSync(join(tmpdir(), 'napi-types-'))
+
+try {
+  const lines = []
+  for (const crate of CRATES) {
+    const perCrate = join(scratch, crate)
+    writeFileSync(perCrate, '')
+    execFileSync('cargo', ['build', '-p', crate], {
+      cwd: packageRoot,
+      env: { ...process.env, NAPI_TYPE_DEF_TMP_FOLDER: scratch },
+      stdio: ['ignore', 'ignore', 'inherit'],
+    })
+    const emitted = readFileSync(perCrate, 'utf8').split('\n').filter(Boolean)
+    if (emitted.length === 0) {
+      throw new Error(
+        `[napi-types] ${crate} emitted nothing — is napi-derive's "type-def" feature on?`,
+      )
+    }
+    lines.push(...emitted)
+  }
+
+  const combined = join(scratch, 'combined.jsonl')
+  writeFileSync(combined, `${lines.join('\n')}\n`)
+
+  execFileSync(
+    process.execPath,
+    [join('scripts', 'generate-napi-types.mjs'), combined, output],
+    { cwd: packageRoot, stdio: 'inherit' },
+  )
+
+  // Formatted here rather than excluded from the linter: the file is checked
+  // in, so it should read like the rest of the tree — and formatting it at
+  // generation means it never shows up as a diff someone has to fix by hand.
+  // Resolved through the package entry rather than `node_modules/.bin`, whose
+  // shim is a shell script the Windows runner cannot execute directly.
+  const biome = createRequire(import.meta.url).resolve('@biomejs/biome/bin/biome')
+  execFileSync(process.execPath, [biome, 'format', '--write', output], {
+    cwd: packageRoot,
+    stdio: ['ignore', 'ignore', 'inherit'],
+  })
+} finally {
+  rmSync(scratch, { recursive: true, force: true })
+}

package/scripts/copy-napi.mjs

@@ -0,0 +1,48 @@
+import { copyFileSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { arch, env, platform } from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+const CRATE = 'vellum_engine_napi'
+const TAG = '[vellum:napi]'
+
+const tripleMap = {
+  'x86_64-unknown-linux-gnu': { suffix: 'linux-x64-gnu', os: 'linux' },
+  'aarch64-unknown-linux-gnu': { suffix: 'linux-arm64-gnu', os: 'linux' },
+  'x86_64-apple-darwin': { suffix: 'darwin-x64', os: 'darwin' },
+  'aarch64-apple-darwin': { suffix: 'darwin-arm64', os: 'darwin' },
+  'x86_64-pc-windows-msvc': { suffix: 'win32-x64-msvc', os: 'win32' },
+}
+const hostSuffixMap = {
+  'linux-x64': 'linux-x64-gnu', 'linux-arm64': 'linux-arm64-gnu',
+  'darwin-x64': 'darwin-x64', 'darwin-arm64': 'darwin-arm64', 'win32-x64': 'win32-x64-msvc',
+}
+
+const triple = env.CARGO_BUILD_TARGET ?? ''
+let suffix, os, releaseDir
+if (triple) {
+  const entry = tripleMap[triple]
+  if (!entry) throw new Error(`${TAG} unsupported CARGO_BUILD_TARGET: ${triple}`)
+  suffix = entry.suffix; os = entry.os
+  releaseDir = join(root, 'target', triple, 'release')
+} else {
+  suffix = hostSuffixMap[`${platform}-${arch}`]; os = platform
+  releaseDir = join(root, 'target', 'release')
+  if (!suffix) throw new Error(`${TAG} unsupported platform/arch: ${platform}-${arch}`)
+}
+
+const candidates =
+  os === 'win32'
+    ? [join(releaseDir, `${CRATE}.dll`), join(releaseDir, `lib${CRATE}.dll`)]
+    : os === 'darwin'
+      ? [join(releaseDir, `lib${CRATE}.dylib`)]
+      : [join(releaseDir, `lib${CRATE}.so`)]
+
+const source = candidates.find((candidate) => existsSync(candidate))
+if (!source) throw new Error(`${TAG} native library not found. Looked for:\n${candidates.map((p) => `- ${p}`).join('\n')}`)
+
+const target = join(root, `index.${suffix}.node`)
+copyFileSync(source, target)
+console.log(`${TAG} copied ${source} -> ${target}`)

package/scripts/generate-metrics.py

@@ -0,0 +1,150 @@
+"""Derive the standard-font advance widths in crates/vellum-engine/src/metrics.rs.
+
+A standard font is referenced without being embedded, so the reader lays the
+text out with the published Adobe metrics. The URW base-35 fonts are the
+metric-compatible clones of those 14, which is what makes them usable as a
+source. The result is cross-checked here against published Adobe values, and
+again by the tests in metrics.rs — so a table that drifted would not compile
+its way into a release.
+
+Run it only to regenerate the table; the build does not need it. It wants the
+AFM files (Fedora: urw-base35-fonts-legacy, Debian: fonts-urw-base35) and
+fonttools, for the Adobe Glyph List.
+
+    python3 scripts/generate-metrics.py /tmp/widths.py
+"""
+import re
+import sys
+from pathlib import Path
+
+from fontTools.agl import AGL2UV
+
+AFM = Path("/usr/share/fonts/urw-base35")
+
+FONTS = [
+    ("Helvetica", "NimbusSans-Regular"),
+    ("HelveticaBold", "NimbusSans-Bold"),
+    ("HelveticaOblique", "NimbusSans-Italic"),
+    ("TimesRoman", "NimbusRoman-Regular"),
+    ("TimesBold", "NimbusRoman-Bold"),
+    ("TimesItalic", "NimbusRoman-Italic"),
+    ("Courier", "NimbusMonoPS-Regular"),
+    ("CourierBold", "NimbusMonoPS-Bold"),
+]
+
+# Unicode -> AGL glyph name, inverted from the AGL itself rather than typed.
+UV2NAME = {}
+for name, uv in AGL2UV.items():
+    UV2NAME.setdefault(uv, name)
+
+# WinAnsi is Latin-1 except over 0x80-0x9F. This block is the ONLY hand-written
+# data here, and it is cross-checked against the Rust encoder below.
+HIGH = {
+    0x80: 0x20AC, 0x82: 0x201A, 0x83: 0x0192, 0x84: 0x201E, 0x85: 0x2026,
+    0x86: 0x2020, 0x87: 0x2021, 0x88: 0x02C6, 0x89: 0x2030, 0x8A: 0x0160,
+    0x8B: 0x2039, 0x8C: 0x0152, 0x8E: 0x017D, 0x91: 0x2018, 0x92: 0x2019,
+    0x93: 0x201C, 0x94: 0x201D, 0x95: 0x2022, 0x96: 0x2013, 0x97: 0x2014,
+    0x98: 0x02DC, 0x99: 0x2122, 0x9A: 0x0161, 0x9B: 0x203A, 0x9C: 0x0153,
+    0x9E: 0x017E, 0x9F: 0x0178,
+}
+
+
+def win_ansi_names():
+    """WinAnsi byte -> AFM glyph name."""
+    names = {}
+    for code in range(0x20, 0x7F):
+        names[code] = UV2NAME[code]
+    for code, uv in HIGH.items():
+        names[code] = UV2NAME[uv]
+    for code in range(0xA0, 0x100):
+        if code in UV2NAME:
+            names[code] = UV2NAME[code]
+    # Adobe's WinAnsiEncoding gives these the width of the glyph they stand in
+    # for: a no-break space is a space, a soft hyphen is a hyphen.
+    names[0xA0] = "space"
+    names[0xAD] = "hyphen"
+    # AGLFN drops the superscript digits as deprecated, but WinAnsi has them
+    # and every AFM names them the old way.
+    names[0xB2] = "twosuperior"
+    names[0xB3] = "threesuperior"
+    names[0xB9] = "onesuperior"
+    return names
+
+
+def widths_of(afm_name):
+    """Glyph name -> advance width, in 1/1000 of an em."""
+    widths = {}
+    text = (AFM / f"{afm_name}.afm").read_text(encoding="latin-1")
+    for line in text.splitlines():
+        if not line.startswith("C "):
+            continue
+        width = re.search(r"WX\s+(-?\d+)\s*;", line)
+        name = re.search(r"N\s+(\S+)\s*;", line)
+        if width and name:
+            widths[name.group(1)] = int(width.group(1))
+    return widths
+
+
+def main():
+    names = win_ansi_names()
+    tables = {}
+    missing = []
+    for font, afm in FONTS:
+        widths = widths_of(afm)
+        table = [0] * 256
+        for code, name in names.items():
+            if name in widths:
+                table[code] = widths[name]
+            else:
+                missing.append((font, code, name))
+        tables[font] = table
+
+    if missing:
+        print(f"MISSING {len(missing)} glyphs, first 10: {missing[:10]}", file=sys.stderr)
+
+    # Cross-check against the published Adobe AFM values. If the URW clones had
+    # drifted, or the glyph-name mapping were wrong, these would not line up.
+    known = {
+        ("Helvetica", " "): 278, ("Helvetica", "A"): 667, ("Helvetica", "W"): 944,
+        ("Helvetica", "i"): 222, ("Helvetica", "M"): 833, ("Helvetica", "a"): 556,
+        ("Helvetica", "."): 278, ("Helvetica", "0"): 556,
+        ("HelveticaBold", " "): 278, ("HelveticaBold", "A"): 722,
+        ("HelveticaBold", "a"): 556, ("HelveticaBold", "i"): 278,
+        ("TimesRoman", " "): 250, ("TimesRoman", "A"): 722, ("TimesRoman", "a"): 444,
+        ("TimesRoman", "W"): 944, ("TimesRoman", "i"): 278, ("TimesRoman", "."): 250,
+        ("TimesBold", "A"): 722, ("TimesBold", "a"): 500,
+        ("TimesItalic", "A"): 611, ("TimesItalic", "a"): 500,
+        ("Courier", "A"): 600, ("Courier", "i"): 600, ("Courier", " "): 600,
+        ("CourierBold", "W"): 600,
+    }
+    bad = []
+    for (font, char), expected in known.items():
+        got = tables[font][ord(char)]
+        if got != expected:
+            bad.append((font, char, expected, got))
+    if bad:
+        print(f"MISMATCH: {bad}", file=sys.stderr)
+        return 1
+
+    # Helvetica-Oblique must share Helvetica's widths; that is what makes it a
+    # slanted Helvetica rather than a different font.
+    assert tables["HelveticaOblique"] == tables["Helvetica"], "oblique drifted"
+    assert all(w in (0, 600) for w in tables["Courier"]), "Courier is not monospace"
+    # Every WinAnsi code except the control range, DEL and the five the
+    # encoding leaves undefined.
+    undefined = {0x7F, 0x81, 0x8D, 0x8F, 0x90, 0x9D}
+    for font, _ in FONTS:
+        for code in range(0x20, 0x100):
+            has = tables[font][code] != 0
+            assert has == (code not in undefined), f"{font} code {code:#x}"
+
+    print(f"OK — {len(known)} known values matched, {len(names)} codes covered")
+    for font, _ in FONTS:
+        defined = sum(1 for w in tables[font] if w)
+        print(f"  {font}: {defined} codes")
+    Path(sys.argv[1]).write_text(repr(tables))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/generate-napi-types.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * Generate the TypeScript surface of the native module FROM the Rust.
+ *
+ * `napi-derive`'s `type-def` feature emits one JSON line per exported item
+ * while cargo compiles. Those lines are the source of truth: they are derived
+ * from the `#[napi]` items themselves, so a signature cannot drift from the
+ * Rust without this file changing.
+ *
+ * Hand-written interfaces are what this replaces, and they do drift — nothing
+ * on the TypeScript side notices when a `pub fn` gains a parameter or stops
+ * being `async`.
+ *
+ * One thing napi-rs cannot infer: the shape of a `JsFunction` callback. It
+ * emits `(...args: any[]) => any`. Any such parameter is refined below, by
+ * name, and the script fails if a refinement no longer matches anything — so
+ * the table cannot rot either.
+ *
+ *   TYPE_DEF_TMP_PATH=<file> cargo build -p <crate>
+ *   node scripts/generate-napi-types.mjs <file> <out.d.ts>
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+
+/**
+ * Callback signatures napi-rs erases to `any`, restored here.
+ *
+ * Keyed by `<owner>.<method>`; the value replaces the whole parameter. Every
+ * entry must match, or the script fails: a stale refinement is how a hand
+ * annotation quietly stops describing the Rust.
+ *
+ * Empty while this crate exposes no `JsFunction` parameter — add an entry the
+ * day one appears, rather than letting an `any` through.
+ */
+const CALLBACK_REFINEMENTS = {}
+
+const [input, output] = process.argv.slice(2)
+if (!input || !output) {
+  console.error('usage: generate-napi-types.mjs <type-def file> <out.d.ts>')
+  process.exit(2)
+}
+
+const entries = readFileSync(input, 'utf8')
+  .split('\n')
+  .map((l) => l.trim())
+  .filter(Boolean)
+  .map((l) => JSON.parse(l))
+
+const used = new Set()
+
+/** Apply the refinements that belong to `owner`, tracking which ones matched. */
+function refine(owner, body) {
+  let out = body
+  for (const [key, { from, to }] of Object.entries(CALLBACK_REFINEMENTS)) {
+    const [entryOwner] = key.split('.')
+    if (entryOwner !== owner) continue
+    if (out.includes(from)) {
+      out = out.replace(from, to)
+      used.add(key)
+    }
+  }
+  return out
+}
+
+/**
+ * JSDoc as emitted by napi-derive, indented to sit above its member.
+ *
+ * `*` followed by `/` inside the text closes the comment early — a Rust doc
+ * example holding a cron expression (`0 *​/5 * * *`) is enough to do it, and
+ * the generated file then fails to parse. Escaped rather than stripped, so the
+ * example still reads correctly.
+ */
+function docBlock(doc, indent = '') {
+  if (!doc) return ''
+  // Escape every `*/` EXCEPT the one that closes the block. A Rust doc example
+  // holding a cron expression (`0 */5 * * *`) closes the comment early
+  // otherwise, and the generated file stops parsing — but escaping the closer
+  // too breaks it just as thoroughly, whether the block spans one line or many.
+  const closer = doc.lastIndexOf('*/')
+  const escaped =
+    closer === -1
+      ? doc
+      : doc.slice(0, closer).replaceAll('*/', '*\\/') + doc.slice(closer)
+  return (
+    escaped
+      .split('\n')
+      .filter((l) => l.length > 0)
+      .map((l) => `${indent}${l}`)
+      .join('\n') + '\n'
+  )
+}
+
+const interfaces = entries.filter((e) => e.kind === 'interface')
+const structs = entries.filter((e) => e.kind === 'struct')
+const impls = new Map(entries.filter((e) => e.kind === 'impl').map((e) => [e.name, e]))
+const fns = entries.filter((e) => e.kind === 'fn')
+
+const out = [
+  '// GENERATED FROM THE RUST — do not edit.',
+  '//',
+  "// Produced by scripts/generate-napi-types.mjs from napi-derive's type-def",
+  '// output. Editing this file by hand puts it back where it started: a',
+  '// description that can disagree with the code it describes.',
+  '',
+]
+
+for (const iface of interfaces) {
+  out.push(docBlock(iface.js_doc))
+  out.push(`export interface ${iface.name} {`)
+  for (const line of iface.def.split('\n')) {
+    out.push(line ? `  ${line.trim()}` : '')
+  }
+  out.push('}', '')
+}
+
+for (const struct of structs) {
+  const impl = impls.get(struct.name)
+  out.push(docBlock(struct.js_doc))
+  out.push(`export declare class ${struct.name} {`)
+  if (impl) {
+    for (const line of refine(struct.name, impl.def).split('\n')) {
+      out.push(line ? `  ${line.trim()}` : '')
+    }
+  }
+  out.push('}', '')
+}
+
+for (const fn of fns) {
+  out.push(docBlock(fn.js_doc))
+  // napi-derive emits the whole declaration for a function, unlike a struct
+  // where `def` holds only the members.
+  const declaration = fn.def.trim()
+  // napi-derive 3 emits a bare `function name(...)` where 2 emitted the
+  // signature after the name; concatenating onto the former produced
+  // `function xfunction x(...)`.
+  const rendered = declaration.startsWith('export declare function')
+    ? declaration
+    : declaration.startsWith('function ')
+      ? `export declare ${declaration}`
+      : `export declare function ${fn.name}${declaration}`
+  out.push(`${rendered};`, '')
+}
+
+const stale = Object.keys(CALLBACK_REFINEMENTS).filter((k) => !used.has(k))
+if (stale.length > 0) {
+  console.error(
+    `[napi-types] refinement(s) that matched nothing: ${stale.join(', ')}\n` +
+      '[napi-types] the Rust changed under them — update or remove the entry.',
+  )
+  process.exit(1)
+}
+
+writeFileSync(output, out.join('\n'))
+console.log(
+  `[napi-types] ${output} — ${interfaces.length} interface(s), ${structs.length} class(es), ${fns.length} function(s)`,
+)