@c9up/inker 0.1.3

package/src/helpers.ts

@@ -0,0 +1,57 @@
+import type { SafeString } from "./SafeString.js";
+
+/**
+ * A caller-registered template helper. Receives the in-scope-evaluated
+ * argument values and returns a string (HTML-escaped by the renderer) or a
+ * `SafeString` (emitted verbatim). Re-homed here from the deleted `render.ts`
+ * when the lex/parse/render hot path moved to the Rust engine (Story 55.1).
+ *
+ * NOTE (55.1): argument values are evaluated in the Rust engine and cross the
+ * NAPI boundary as JSON, so they are JSON-coerced before reaching the helper:
+ * a `Date` arrives as a string, a `bigint` as a (possibly lossy) number, and
+ * `NaN` / `±Infinity` as `null`. Pass pre-stringified values for any type that
+ * does not survive JSON if the helper needs the original form.
+ */
+export type HelperFn = (...args: readonly unknown[]) => string | SafeString;
+
+/**
+ * Signature for the canonical `t(key, params?)` helper.
+ *
+ * Inker ships ZERO body for this helper — implementations come from
+ * the caller via `TemplatesOptions.helpers`. The Ream provider (Story
+ * 53.5) wires this signature to `@c9up/rosetta`'s `Rosetta#t(key,
+ * params?, options?)`.
+ */
+export type THelper = (key: string, params?: Record<string, unknown>) => string;
+
+/**
+ * Signature for the canonical `csrfField()` helper.
+ *
+ * Returns a `SafeString` containing the `<input type="hidden"
+ * name="_csrf" value="…">` element. Returning a `SafeString` is
+ * mandatory — a plain string would be HTML-escaped by the renderer
+ * and the resulting `&lt;input …&gt;` would not be a usable form
+ * field. Implementation is provided by the Ream provider (Story 53.5)
+ * wiring the session's CSRF token.
+ */
+export type CsrfFieldHelper = () => SafeString;
+
+/**
+ * Signature for the canonical `url(name, params?)` helper.
+ *
+ * Resolves a named route + interpolates path params. Implementation
+ * is provided by the Ream provider (Story 53.5) wiring the router.
+ */
+export type UrlHelper = (
+	name: string,
+	params?: Record<string, unknown>,
+) => string;
+
+/**
+ * Signature for the canonical `asset(name)` helper.
+ *
+ * Resolves an asset manifest entry to its hashed public URL.
+ * Implementation is provided by the Ream provider (Story 53.5) wiring
+ * the asset manifest.
+ */
+export type AssetHelper = (name: string) => string;

package/src/identifierGuards.ts

@@ -0,0 +1,49 @@
+/**
+ * Identifier denylists shared between `parseBlockTag.ts` (each-binding +
+ * component-arg-key validation) and `parseExpression.ts` (object-literal
+ * key validation).
+ *
+ * `PROTOTYPE_POLLUTION_KEYS` blocks the three keys whose own-property
+ * assignment can shadow `Object.prototype` methods or invoke
+ * `Object.create` semantics in surprising ways. The gate is
+ * defence-in-depth: JavaScript's `obj[key] = value` semantics make
+ * `__proto__` non-exploitable when used via square brackets on a
+ * non-frozen object built via `Object.create(null)`, but template
+ * authors cannot reason about the renderer's storage shape and the
+ * cost of the guard is one Set membership check per object key.
+ *
+ * `RESERVED_BINDING_NAMES` blocks identifiers that would collide with
+ * Inker grammar keywords (e.g. `as`) or JavaScript reserved words when
+ * used as `{% each items as <name> %}` bindings or `{% each items as
+ * [<a>, <b>] %}` destructured names. The block is per-position rather
+ * than universal — Inker permits these names inside path expressions
+ * since paths cannot collide with the grammar.
+ */
+export const PROTOTYPE_POLLUTION_KEYS: ReadonlySet<string> = new Set([
+	"__proto__",
+	"constructor",
+	"prototype",
+]);
+
+export const RESERVED_BINDING_NAMES: ReadonlySet<string> = new Set([
+	"as",
+	"if",
+	"else",
+	"each",
+	"do",
+	"for",
+	"while",
+	"let",
+	"const",
+	"var",
+	"return",
+	"function",
+	"class",
+	"new",
+	"this",
+	"super",
+	"null",
+	"undefined",
+	"true",
+	"false",
+]);

package/src/index.ts

@@ -0,0 +1,14 @@
+export type {
+	AssetHelper,
+	CsrfFieldHelper,
+	HelperFn,
+	THelper,
+	UrlHelper,
+} from "./helpers.js";
+export {
+	type InkerErrorCode,
+	type InkerErrorContext,
+	InkerRenderError,
+} from "./InkerRenderError.js";
+export { SafeString } from "./SafeString.js";
+export { Templates, type TemplatesOptions } from "./Templates.js";

package/src/loadNapi.ts

@@ -0,0 +1,270 @@
+// PATTERN: copy-and-rename for 55.2/55.3/55.4 — Rust hot-path packages.
+//
+// Loads the native `inker-engine-napi` binary built by `scripts/copy-napi.mjs`
+// and re-throws load failures as `E_INKER_NAPI_REQUIRED` per cerebrum
+// NAPI-loader pattern (2026-04-27) — actionable hint points at
+// `pnpm --filter @c9up/inker build:napi`.
+//
+// Per cerebrum 2026-04-15 there is NO JS fallback. If the binary fails to
+// load, consumers get a typed error. Zero `as` / `any` per cerebrum 2026-05-04.
+
+import { createRequire } from "node:module";
+import { arch, platform } from "node:process";
+import { fileURLToPath } from "node:url";
+import { type InkerErrorCode, InkerRenderError } from "./InkerRenderError.js";
+
+const SUFFIX_MAP: Readonly<Record<string, string>> = {
+	"linux-x64": "linux-x64-gnu",
+	"linux-arm64": "linux-arm64-gnu",
+	"darwin-x64": "darwin-x64",
+	"darwin-arm64": "darwin-arm64",
+	"win32-x64": "win32-x64-msvc",
+};
+
+function platformSuffix(): string {
+	const key = `${platform}-${arch}`;
+	const suffix = SUFFIX_MAP[key];
+	if (typeof suffix !== "string") {
+		throw new InkerRenderError(
+			"E_INKER_NAPI_REQUIRED",
+			`Unsupported platform/arch '${key}' for @c9up/inker native binary. Supported: ${Object.keys(SUFFIX_MAP).join(", ")}.`,
+		);
+	}
+	return suffix;
+}
+
+/** A `{% include %}` / `{% component %}` reference with source position. */
+export interface NapiNodeRef {
+	readonly name: string;
+	readonly line: number;
+	readonly column: number;
+}
+
+/** A `{{> name }}` slot reference. */
+export interface NapiSlotRef {
+	readonly name: string;
+	readonly line: number;
+	readonly column: number;
+}
+
+/** First disk-requiring node (`renderString` E_INKER_DISK_REQUIRED guard). */
+export interface NapiDiskNodeRef {
+	readonly kind: string;
+	readonly name: string;
+}
+
+/** All composition metadata for one parsed AST (one NAPI call). */
+export interface NapiComposeInfo {
+	readonly hasLayout: boolean;
+	readonly layoutName: string | null;
+	readonly layoutLine: number | null;
+	readonly layoutColumn: number | null;
+	readonly slots: readonly NapiSlotRef[];
+	readonly partials: readonly NapiNodeRef[];
+	readonly components: readonly NapiNodeRef[];
+	readonly hasContent: boolean;
+	readonly firstDiskNode: NapiDiskNodeRef | null;
+}
+
+/** Opaque handle to a parsed Rust AST. */
+export interface NapiInkerAst {
+	readonly composeInfo: NapiComposeInfo;
+}
+
+/** One in-scope-evaluated helper invocation request (collect pass). */
+export interface NapiInvocation {
+	readonly id: number;
+	readonly name: string;
+	/** JSON array of the evaluated argument values. */
+	readonly args: readonly unknown[];
+}
+
+/** One pre-resolved helper result (consumed in tape order by the renderer). */
+export interface NapiHelperResult {
+	readonly value: string;
+	readonly isSafe: boolean;
+}
+
+export interface NapiRenderContext {
+	readonly partials: Record<string, NapiInkerAst>;
+	readonly components: Record<string, NapiInkerAst>;
+	readonly bodyHtml: string | undefined;
+	readonly templateName: string | undefined;
+	readonly templatePath: string | undefined;
+}
+
+interface NativeExports {
+	readonly engineVersion: () => string;
+	readonly parseTemplate: (
+		source: string,
+		helpers: readonly string[],
+	) => NapiInkerAst;
+	readonly collectInvocations: (
+		ast: NapiInkerAst,
+		data: unknown,
+		ctx: NapiRenderContext,
+	) => NapiInvocation[];
+	readonly renderAst: (
+		ast: NapiInkerAst,
+		data: unknown,
+		resolved: readonly NapiHelperResult[],
+		ctx: NapiRenderContext,
+	) => string;
+}
+
+function isNativeExports(value: unknown): value is NativeExports {
+	if (value === null || typeof value !== "object") return false;
+	return (
+		typeof Reflect.get(value, "engineVersion") === "function" &&
+		typeof Reflect.get(value, "parseTemplate") === "function" &&
+		typeof Reflect.get(value, "collectInvocations") === "function" &&
+		typeof Reflect.get(value, "renderAst") === "function"
+	);
+}
+
+let cachedNative: NativeExports | undefined;
+
+export function getNative(): NativeExports {
+	if (cachedNative !== undefined) return cachedNative;
+
+	const require = createRequire(import.meta.url);
+	const here = fileURLToPath(import.meta.url);
+	// `here` is `…/packages/inker/{src,dist}/loadNapi.ts|js`. The `.node` lives
+	// one level up at `…/packages/inker/index.<suffix>.node`. `..` traversal
+	// resolved via require (handles both dev `src/` and publish `dist/`).
+	const suffix = platformSuffix();
+	const candidates: readonly string[] = [`../index.${suffix}.node`];
+	let loaded: unknown;
+	let lastErr: unknown;
+	for (const candidate of candidates) {
+		try {
+			loaded = require(candidate);
+			break;
+		} catch (err) {
+			lastErr = err;
+		}
+	}
+	if (loaded === undefined) {
+		const causeMessage =
+			lastErr instanceof Error ? lastErr.message : String(lastErr);
+		// The prebuilt linux binaries target glibc (`-gnu`). On musl hosts (Alpine
+		// containers) the `-gnu` binary fails to dlopen with a libc symbol error —
+		// surface that explicitly rather than only pointing at the build step.
+		const muslHint = suffix.endsWith("-gnu")
+			? " If you are on Alpine/musl, note the prebuilt binaries target glibc (musl is not a supported target)."
+			: "";
+		throw new InkerRenderError(
+			"E_INKER_NAPI_REQUIRED",
+			`@c9up/inker native binary 'index.${suffix}.node' not found or failed to load near ${here} — run 'pnpm --filter @c9up/inker build:napi' to build it.${muslHint} Cause: ${causeMessage}`,
+			undefined,
+			{ cause: lastErr },
+		);
+	}
+	if (!isNativeExports(loaded)) {
+		throw new InkerRenderError(
+			"E_INKER_NAPI_REQUIRED",
+			`@c9up/inker native binary loaded but missing expected exports (engineVersion / parseTemplate / renderAst). Rebuild with 'pnpm --filter @c9up/inker build:napi'.`,
+		);
+	}
+	cachedNative = loaded;
+	return cachedNative;
+}
+
+/**
+ * Shape of the JSON payload Rust packs into `napi::Error::from_reason`. Rust
+ * guarantees `code` / `message` present; positional fields optional.
+ */
+interface NapiErrorPayload {
+	readonly code: string;
+	readonly message: string;
+	readonly line?: number;
+	readonly column?: number;
+	readonly templateName?: string;
+}
+
+function readString(target: unknown, key: string): string | undefined {
+	const v = Reflect.get(Object(target), key);
+	return typeof v === "string" ? v : undefined;
+}
+
+function readNumber(target: unknown, key: string): number | undefined {
+	const v = Reflect.get(Object(target), key);
+	return typeof v === "number" ? v : undefined;
+}
+
+function isNapiErrorPayload(value: unknown): value is NapiErrorPayload {
+	if (value === null || typeof value !== "object") return false;
+	return (
+		typeof Reflect.get(value, "code") === "string" &&
+		typeof Reflect.get(value, "message") === "string"
+	);
+}
+
+const CODE_MAP: Readonly<Record<string, InkerErrorCode>> = {
+	E_INKER_TEMPLATE_NOT_FOUND: "E_INKER_TEMPLATE_NOT_FOUND",
+	E_INKER_PARSE_ERROR: "E_INKER_PARSE_ERROR",
+	E_INKER_UNKNOWN_IDENTIFIER: "E_INKER_UNKNOWN_IDENTIFIER",
+	E_INKER_INVALID_PATH: "E_INKER_INVALID_PATH",
+	E_INKER_UNCLOSED_INTERPOLATION: "E_INKER_UNCLOSED_INTERPOLATION",
+	E_INKER_UNCLOSED_BLOCK_TAG: "E_INKER_UNCLOSED_BLOCK_TAG",
+	E_INKER_UNKNOWN_DIRECTIVE: "E_INKER_UNKNOWN_DIRECTIVE",
+	E_INKER_INVALID_LAYOUT_POSITION: "E_INKER_INVALID_LAYOUT_POSITION",
+	E_INKER_DUPLICATE_LAYOUT: "E_INKER_DUPLICATE_LAYOUT",
+	E_INKER_NESTED_LAYOUT_UNSUPPORTED: "E_INKER_NESTED_LAYOUT_UNSUPPORTED",
+	E_INKER_LAYOUT_IN_PARTIAL: "E_INKER_LAYOUT_IN_PARTIAL",
+	E_INKER_CIRCULAR_INCLUDE: "E_INKER_CIRCULAR_INCLUDE",
+	E_INKER_MISSING_SLOT: "E_INKER_MISSING_SLOT",
+	E_INKER_UNKNOWN_SLOT: "E_INKER_UNKNOWN_SLOT",
+	E_INKER_DISK_REQUIRED: "E_INKER_DISK_REQUIRED",
+	E_INKER_UNCLOSED_BLOCK: "E_INKER_UNCLOSED_BLOCK",
+	E_INKER_UNMATCHED_BLOCK_END: "E_INKER_UNMATCHED_BLOCK_END",
+	E_INKER_MISMATCHED_BLOCK_END: "E_INKER_MISMATCHED_BLOCK_END",
+	E_INKER_INVALID_EXPRESSION: "E_INKER_INVALID_EXPRESSION",
+	E_INKER_INVALID_ITERABLE: "E_INKER_INVALID_ITERABLE",
+	E_INKER_UNKNOWN_HELPER: "E_INKER_UNKNOWN_HELPER",
+	E_INKER_HELPER_THROW: "E_INKER_HELPER_THROW",
+	E_INKER_NAPI_REQUIRED: "E_INKER_NAPI_REQUIRED",
+};
+
+/**
+ * Translate a thrown value from a NAPI call into an `InkerRenderError`.
+ * If it's already an `InkerRenderError` (helper threw and propagated), pass through.
+ * If it's a `napi::Error` carrying our JSON envelope, reconstruct typed.
+ * Otherwise wrap as parse error.
+ */
+export function napiThrowToInker(err: unknown): InkerRenderError {
+	if (err instanceof InkerRenderError) return err;
+	if (err instanceof Error) {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(err.message);
+		} catch {
+			parsed = undefined;
+		}
+		if (isNapiErrorPayload(parsed)) {
+			const code = CODE_MAP[parsed.code];
+			if (code !== undefined) {
+				return new InkerRenderError(
+					code,
+					parsed.message,
+					{
+						line: readNumber(parsed, "line"),
+						column: readNumber(parsed, "column"),
+						templateName: readString(parsed, "templateName"),
+					},
+					{ cause: err },
+				);
+			}
+		}
+		return new InkerRenderError(
+			"E_INKER_PARSE_ERROR",
+			`Native call failed: ${err.message}`,
+			undefined,
+			{ cause: err },
+		);
+	}
+	return new InkerRenderError(
+		"E_INKER_PARSE_ERROR",
+		`Native call failed with non-Error: ${String(err)}`,
+	);
+}

package/src/services/main.ts

@@ -0,0 +1,56 @@
+/**
+ * Default `InkerRenderer` singleton — Adonis-style:
+ *
+ *   import inker from '@c9up/inker/provider/services/main'
+ *
+ *   await inker.render(ctx, 'invoice', { user })
+ *
+ * Populated by `InkerProvider.start()` (registered via reamrc.ts) or by the
+ * app itself via `setInker(myRenderer)`.
+ */
+
+import type { InkerRenderer } from "../InkerRenderer.js";
+
+let instance: InkerRenderer | undefined;
+
+/**
+ * @internal Bind (or clear) the singleton. Called by InkerProvider.start() to
+ * wire the renderer, or by tests passing `undefined` to reset between cases
+ * (the type field already permits `undefined`, so the signature mirrors it
+ * honestly rather than requiring a `bypassTypeCheck` cast at every call site).
+ */
+export function setInker(renderer: InkerRenderer | undefined): void {
+	instance = renderer;
+}
+
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getInker(): InkerRenderer | undefined {
+	return instance;
+}
+
+// Sanctioned `as InkerRenderer` site — typed-Proxy idiom shared by
+// station/rosetta/aurora/inker `services/main.ts`. Every property access is
+// guarded by the `instance` check below, so the cast is structural and
+// bounded. DNR `feedback_no_any_types` documents this as one of two
+// permitted `as` patterns alongside `loadBearingCast` in `InkerProvider.ts`.
+const inker: InkerRenderer = new Proxy({} as InkerRenderer, {
+	get(_target, prop) {
+		// Short-circuit the thenable probe: an accidental `await mod.default`
+		// (or `Promise.resolve(mod.default)`) would otherwise trigger our
+		// pre-boot throw inside the await machinery and surface a confusing
+		// rejected Promise. Returning `undefined` makes the value plainly
+		// non-thenable, so the caller's await resolves immediately to the
+		// Proxy itself — subsequent real property access still throws.
+		if (prop === "then") return undefined;
+		if (!instance) {
+			throw new Error(
+				"[inker] InkerRenderer singleton accessed before InkerProvider.start() ran " +
+					"or `setInker(myRenderer)` was called. Wire one of them first.",
+			);
+		}
+		const value = Reflect.get(instance, prop, instance);
+		return typeof value === "function" ? value.bind(instance) : value;
+	},
+});
+
+export default inker;