@c9up/rover 0.1.11 → 0.1.12

package/dist/native/generated.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Opaque handle to a compiled template IR. The TS-side `cache` keeps these
+ * instances alive; when the JS GC collects the wrapper, napi-rs drops the
+ * inner `Arc` automatically (Arc + GC bridge — no manual dispose API).
+ */
+export declare class RoverIr {
+    /**
+     * Every referenced partial name, in document order (descends into
+     * `{{#if}}` bodies). Drives the TS facade's transitive partial map build.
+     */
+    get partialNames(): Array<string>;
+}
+/** Compile a template source string into an opaque `RoverIr` handle. */
+export declare function compile(source: string): RoverIr;
+/**
+ * Render a compiled IR against `data` (a JSON string), resolving `{{> name}}`
+ * partials from the pre-resolved `partials` map. Render-time recursion ->
+ * `MAIL_TEMPLATE_RECURSION`.
+ *
+ * `data` crosses as a JSON STRING (the TS facade calls `JSON.stringify`), not
+ * as an object graph: `JSON.stringify` is own-enumerable-only, which preserves
+ * the engine's `Object.hasOwn` dot-path contract (inherited prototype-chain
+ * props must NOT be visible — `simple-template.test.ts:195-201`). It is also a
+ * single native stringify + one Rust parse, instead of napi walking the whole
+ * object graph (which would additionally surface inherited enumerable props).
+ */
+export declare function renderIr(ir: RoverIr, dataJson: string, partials: Record<string, RoverIr>): string;
+/** Crate version — useful for the TS-side `loadNapi.ts` startup diagnostic. */
+export declare function engineVersion(): string;
+//# sourceMappingURL=generated.d.ts.map

package/dist/native/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../src/native/generated.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AAEH,MAAM,CAAC,OAAO,OAAO,OAAO;IAC3B;;;OAGG;IACH,IAAI,YAAY,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;CAClC;AAED,wEAAwE;AAExE,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;AAEzD;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAC/B,EAAE,EAAE,OAAO,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAAC;AAEV,+EAA+E;AAE/E,MAAM,CAAC,OAAO,UAAU,aAAa,IAAI,MAAM,CAAC"}

package/dist/native/generated.js

@@ -0,0 +1,7 @@
+// 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.
+export {};
+//# sourceMappingURL=generated.js.map

package/dist/native/generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.js","sourceRoot":"","sources":["../../src/native/generated.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,0EAA0E;AAC1E,qEAAqE;AACrE,4DAA4D"}

package/dist/templating/loadNapi.d.ts

@@ -1,14 +1,16 @@
 import { RoverError } from "../RoverError.js";
 /** Opaque handle to a compiled template IR (Rust `RoverIr`). */
-export interface NativeRoverIr {
-    /** Referenced partial names, in document order (descends into if-bodies). */
-    readonly partialNames: readonly string[];
-}
-interface NativeExports {
-    readonly engineVersion: () => string;
-    readonly compile: (source: string) => NativeRoverIr;
-    readonly renderIr: (ir: NativeRoverIr, dataJson: string, partials: Record<string, NativeRoverIr>) => string;
-}
+export type NativeRoverIr = import("../native/generated.js").RoverIr;
+/**
+ * The engine's surface, as the Rust declares it.
+ *
+ * Derived from `../native/generated.js` — written by `pnpm build:napi-types`
+ * from napi-derive's own `type-def` output — rather than restated here, where
+ * nothing would notice a `pub fn` gaining a parameter or changing its return.
+ * The runtime guard below still checks the three exports are actually there:
+ * a declaration says what the Rust promises, not what a stale binary shipped.
+ */
+type NativeExports = typeof import("../native/generated.js");
 export declare function getNative(): NativeExports;
 /**
  * Translate a thrown value from a native call into a `RoverError`.

package/dist/templating/loadNapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loadNapi.d.ts","sourceRoot":"","sources":["../../src/templating/loadNapi.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAyB9C,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,UAAU,aAAa;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,MAAM,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,CAClB,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,KACnC,MAAM,CAAC;CACZ;AAaD,wBAAgB,SAAS,IAAI,aAAa,CA6CzC;AA6BD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAwBpD"}
+{"version":3,"file":"loadNapi.d.ts","sourceRoot":"","sources":["../../src/templating/loadNapi.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAyB9C,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG,OAAO,wBAAwB,EAAE,OAAO,CAAC;AAErE;;;;;;;;GAQG;AACH,KAAK,aAAa,GAAG,cAAc,wBAAwB,CAAC,CAAC;AAa7D,wBAAgB,SAAS,IAAI,aAAa,CA6CzC;AA6BD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAwBpD"}

package/dist/templating/loadNapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadNapi.js","sourceRoot":"","sources":["../../src/templating/loadNapi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loadNapi.js","sourceRoot":"","sources":["../../src/templating/loadNapi.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,yDAAyD;AACzD,sEAAsE;AACtE,0CAA0C;AAC1C,EAAE;AACF,gFAAgF;AAChF,oFAAoF;AACpF,gEAAgE;AAEhE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,UAAU,GAAqC;IACpD,WAAW,EAAE,eAAe;IAC5B,aAAa,EAAE,iBAAiB;IAChC,YAAY,EAAE,YAAY;IAC1B,cAAc,EAAE,cAAc;IAC9B,WAAW,EAAE,gBAAgB;CAC7B,CAAC;AAEF,SAAS,cAAc;IACtB,MAAM,GAAG,GAAG,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAC;IAClC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,UAAU,CACnB,6BAA6B,EAC7B,8BAA8B,GAAG,+CAA+C,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EACrH;YACC,IAAI,EAAE,8FAA8F;SACpG,CACD,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAgBD,SAAS,eAAe,CAAC,KAAc;IACtC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,CACN,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,eAAe,CAAC,KAAK,UAAU;QACzD,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,UAAU;QACnD,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,UAAU,CACpD,CAAC;AACH,CAAC;AAED,IAAI,YAAuC,CAAC;AAE5C,MAAM,UAAU,SAAS;IACxB,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAEpD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5C,6EAA6E;IAC7E,4EAA4E;IAC5E,2DAA2D;IAC3D,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;IAChC,MAAM,SAAS,GAAG,eAAe,MAAM,OAAO,CAAC;IAC/C,IAAI,MAAe,CAAC;IACpB,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACJ,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,OAAO,GAAG,GAAG,CAAC;IACf,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,YAAY,GACjB,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9D,2EAA2E;QAC3E,2EAA2E;QAC3E,uEAAuE;QACvE,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YACvC,CAAC,CAAC,uGAAuG;YACzG,CAAC,CAAC,EAAE,CAAC;QACN,MAAM,IAAI,UAAU,CACnB,6BAA6B,EAC7B,oCAAoC,MAAM,2CAA2C,IAAI,6DAA6D,QAAQ,WAAW,YAAY,EAAE,EACvL;YACC,IAAI,EAAE,mFAAmF;SACzF,CACD,CAAC;IACH,CAAC;IACD,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,UAAU,CACnB,6BAA6B,EAC7B,0JAA0J,EAC1J;YACC,IAAI,EAAE,mFAAmF;SACzF,CACD,CAAC;IACH,CAAC;IACD,YAAY,GAAG,MAAM,CAAC;IACtB,OAAO,YAAY,CAAC;AACrB,CAAC;AAWD,SAAS,kBAAkB,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,CACN,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,QAAQ;QAC9C,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,QAAQ,CACjD,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,GAAqC;IACpD,oBAAoB,EACnB,yFAAyF;IAC1F,uBAAuB,EACtB,gFAAgF;IACjF,uBAAuB,EACtB,wEAAwE;CACzE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY;IACvC,IAAI,GAAG,YAAY,UAAU;QAAE,OAAO,GAAG,CAAC;IAC1C,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QAC1B,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACR,MAAM,GAAG,SAAS,CAAC;QACpB,CAAC;QACD,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACxB,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9D,CAAC;QACF,CAAC;QACD,OAAO,IAAI,UAAU,CACpB,sBAAsB,EACtB,gCAAgC,GAAG,CAAC,OAAO,EAAE,CAC7C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,UAAU,CACpB,sBAAsB,EACtB,+CAA+C,MAAM,CAAC,GAAG,CAAC,EAAE,CAC5D,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/rover",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Mail transport for Ream — SMTP, log, and pluggable transports",
   "type": "module",
   "main": "./dist/index.js",
@@ -102,7 +102,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "build:napi": "cargo build --release -p rover-template-engine-napi && node scripts/copy-napi.mjs",
+    "build:napi": "cargo build --release -p rover-template-engine-napi && pnpm build:napi-types && node scripts/copy-napi.mjs",
+    "build:napi-types": "node scripts/build-napi-types.mjs",
     "test": "vitest run",
     "lint": "biome check src/",
     "test:coverage": "vitest run --coverage",

package/scripts/build-napi-types.mjs

@@ -0,0 +1,68 @@
+#!/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: napi-derive APPENDS to `TYPE_DEF_TMP_PATH`
+ * 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 = ['rover-template-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}.jsonl`)
+    writeFileSync(perCrate, '')
+    execFileSync('cargo', ['build', '-p', crate], {
+      cwd: packageRoot,
+      env: { ...process.env, TYPE_DEF_TMP_PATH: perCrate },
+      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/generate-napi-types.mjs

@@ -0,0 +1,153 @@
+#!/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()
+  out.push(
+    declaration.startsWith('export declare function')
+      ? `${declaration};`
+      : `export declare function ${fn.name}${declaration};`,
+    '',
+  )
+}
+
+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)`,
+)

package/src/native/generated.ts

@@ -0,0 +1,46 @@
+// 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.
+
+/**
+ * Opaque handle to a compiled template IR. The TS-side `cache` keeps these
+ * instances alive; when the JS GC collects the wrapper, napi-rs drops the
+ * inner `Arc` automatically (Arc + GC bridge — no manual dispose API).
+ */
+
+export declare class RoverIr {
+	/**
+	 * Every referenced partial name, in document order (descends into
+	 * `{{#if}}` bodies). Drives the TS facade's transitive partial map build.
+	 */
+	get partialNames(): Array<string>;
+}
+
+/** Compile a template source string into an opaque `RoverIr` handle. */
+
+export declare function compile(source: string): RoverIr;
+
+/**
+ * Render a compiled IR against `data` (a JSON string), resolving `{{> name}}`
+ * partials from the pre-resolved `partials` map. Render-time recursion ->
+ * `MAIL_TEMPLATE_RECURSION`.
+ *
+ * `data` crosses as a JSON STRING (the TS facade calls `JSON.stringify`), not
+ * as an object graph: `JSON.stringify` is own-enumerable-only, which preserves
+ * the engine's `Object.hasOwn` dot-path contract (inherited prototype-chain
+ * props must NOT be visible — `simple-template.test.ts:195-201`). It is also a
+ * single native stringify + one Rust parse, instead of napi walking the whole
+ * object graph (which would additionally surface inherited enumerable props).
+ */
+
+export declare function renderIr(
+	ir: RoverIr,
+	dataJson: string,
+	partials: Record<string, RoverIr>,
+): string;
+
+/** Crate version — useful for the TS-side `loadNapi.ts` startup diagnostic. */
+
+export declare function engineVersion(): string;

package/src/templating/loadNapi.ts

@@ -36,20 +36,18 @@ function platformSuffix(): string {
 }
 
 /** Opaque handle to a compiled template IR (Rust `RoverIr`). */
-export interface NativeRoverIr {
-	/** Referenced partial names, in document order (descends into if-bodies). */
-	readonly partialNames: readonly string[];
-}
+export type NativeRoverIr = import("../native/generated.js").RoverIr;
 
-interface NativeExports {
-	readonly engineVersion: () => string;
-	readonly compile: (source: string) => NativeRoverIr;
-	readonly renderIr: (
-		ir: NativeRoverIr,
-		dataJson: string,
-		partials: Record<string, NativeRoverIr>,
-	) => string;
-}
+/**
+ * The engine's surface, as the Rust declares it.
+ *
+ * Derived from `../native/generated.js` — written by `pnpm build:napi-types`
+ * from napi-derive's own `type-def` output — rather than restated here, where
+ * nothing would notice a `pub fn` gaining a parameter or changing its return.
+ * The runtime guard below still checks the three exports are actually there:
+ * a declaration says what the Rust promises, not what a stale binary shipped.
+ */
+type NativeExports = typeof import("../native/generated.js");
 
 function isNativeExports(value: unknown): value is NativeExports {
 	if (value === null || typeof value !== "object") return false;

package/src/testing/FakeMail.ts

@@ -351,7 +351,7 @@ export function mailFake(mailer: FakeableMailer): Plugin {
 }
 
 // Typing side of the plugin — importing `@c9up/rover/testing` augments the
-// helix test context with `mail` (the Japa pattern).
+// helix test context with `mail` (the helix pattern).
 declare module "@c9up/helix" {
 	interface TestContext {
 		mail: FakeMail;