@c9up/inker 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+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,48 @@
+# @c9up/inker
+
+Server-side templating module for the Ream framework. Loads `.inker` files from disk, parses them with a hand-rolled lexer + AST, and renders against a plain data object. HTML-escape by default; raw output via the explicit triple-brace form. Strict-by-default: unknown identifiers throw rather than render blank.
+
+## File convention
+
+Templates live as `<root>/<name>.inker` files. Resolve the root yourself (absolute path) and pass it once at construction:
+
+```ts
+import { Templates } from "@c9up/inker";
+
+const templates = new Templates({ root: "/abs/path/to/templates" });
+const html = await templates.render("invoice", { customer: { name: "Alice" }, total: 42 });
+```
+
+Interpolation is `{{ expr }}` (HTML-escaped) or `{{{ expr }}}` (raw). The `expr` is a member-access path (`customer.name`, `items[0].title`, `items["weird key"]`); arithmetic, calls, ternaries, and template literals go through registered helpers.
+
+## Strict by default
+
+- Missing templates throw `InkerRenderError` with `code: "E_INKER_TEMPLATE_NOT_FOUND"`.
+- Unknown identifiers throw `code: "E_INKER_UNKNOWN_IDENTIFIER"` with the consumed path and the line + column of the offending interpolation.
+- Parse errors throw `code: "E_INKER_PARSE_ERROR"` with a precise reason.
+
+The full reference (file layout, cache semantics, error surface) lives at <https://ream.dev/modules/inker>.
+
+## Testing
+
+```sh
+pnpm --filter @c9up/inker test            # full suite
+pnpm --filter @c9up/inker test:coverage   # enforces v8 coverage gate
+```
+
+The coverage gate (v8 provider) is wired in `vitest.config.ts` with thresholds at `statements: 88 / functions: 96 / branches: 78 / lines: 89` (re-baselined for the Rust-migration src/ surface — the lex/parse/render modules moved to Rust, covered by 105 `cargo test` cases). A regression that drops below any of those floors fails CI.
+
+## Native binary
+
+The lex / parse / render hot path runs in Rust via napi-rs (Story 55.1). The TypeScript surface (`Templates`, `InkerProvider`, `SafeString`, `InkerRenderError`) is unchanged — the engine is loaded transparently from a prebuilt `.node` binary.
+
+- **Build locally:** `pnpm --filter @c9up/inker build:napi` compiles the `inker-engine-napi` crate (release) and copies `index.<platform>.node` into the package root. The 5-platform NAPI CI matrix (`linux-x64-gnu`, `linux-arm64-gnu`, `darwin-x64`, `darwin-arm64`, `win32-x64-msvc`) builds these on native runners.
+- **No JS fallback.** If the binary is missing or fails to load, every render throws `E_INKER_NAPI_REQUIRED` with an actionable hint pointing at `pnpm --filter @c9up/inker build:napi`. Run that after a fresh checkout or a platform change.
+- **Helpers stay in TypeScript.** Custom helpers registered via `TemplatesOptions.helpers` (or `InkerProvider`) are plain TS functions. The renderer resolves them TS-side before the native render pass (collect → invoke → render — no V8 callback), so no Rust knowledge is required to write one. Helpers must appear as a whole interpolation (`{{ helper(args) }}`) or a component-arg value; they are not supported inside `{% if %}` conditions, `{% each %}` iterables, operator expressions, or as nested-call arguments. Helper **arguments** are evaluated in the Rust engine and cross the NAPI boundary as JSON, so they are JSON-coerced before the helper runs: 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.
+
+## Standalone use
+
+`@c9up/inker` is a leaf package — it has zero runtime dependencies and works in any Node.js app without `@c9up/ream` or `@c9up/rosetta` installed. The `tests/integration/standalone-smoke.test.ts` test proves this by packing the workspace tarball, installing it into a synthetic consumer (no ream, no rosetta), and rendering a composite template.
+
+The `@c9up/inker/provider` sub-path (the `InkerProvider` class) is importable without those peers as well — its `InkerAppContext` is duck-typed, so structural import never reaches the ream runtime. Wiring the provider into a real container still requires a Ream host at boot time.
+

package/dist/InkerProvider.d.ts

@@ -0,0 +1,120 @@
+/**
+ * InkerProvider — Ream provider that wires `@c9up/inker` into a Ream host.
+ *
+ * `register()` binds an `InkerRenderer` singleton + the `"inker"` alias via
+ * factories that throw pre-`start()` (so an accidental preload-time resolve
+ * surfaces immediately instead of silently rendering with an unconfigured
+ * Templates instance).
+ *
+ * `start()` lazily imports `@c9up/ream/services/router` + `@c9up/rosetta`
+ * (both declared as `peerDependenciesMeta.optional`), builds the four
+ * canonical helper bodies (`t` / `csrfField` / `url` / `asset`) closing
+ * over a single `AsyncLocalStorage<InkerHttpContext>`, constructs the
+ * `Templates` instance + `InkerRenderer`, and primes `services/main`'s
+ * Proxy via `setInker`.
+ *
+ * Mirrors the StationProvider / AuroraProvider shape — duck-typed
+ * container / config / app-context interfaces, `loadBearingCast<T>` as the
+ * single sanctioned cross-package narrowing site, `isModuleNotFound`
+ * silent-degradation in Phase 1, `#started` idempotency.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { HelperFn } from "./helpers.js";
+import type { InkerHttpContext } from "./InkerRenderer.js";
+import { type CacheMode } from "./Templates.js";
+interface InkerContainer {
+    singleton<T>(token: unknown, factory: () => T): void;
+    resolve<T = unknown>(token: unknown): T;
+}
+interface InkerConfigStore {
+    get<T = unknown>(key: string): T | undefined;
+}
+export interface InkerAppContext {
+    container: InkerContainer;
+    config: InkerConfigStore;
+}
+export interface InkerProviderConfig {
+    /** Absolute path or relative-to-appRoot. Default: <appRoot>/resources/templates. */
+    templatesRoot?: string;
+    /** "auto" (default) | "mtime" | "never". */
+    cacheMode?: CacheMode;
+    /** Optional manifest source for asset(). Direct injection beats <appRoot>/public/manifest.json. */
+    assetManifest?: Readonly<Record<string, string>>;
+    /** App-supplied helpers merged with canonical. Override warns once per name per process. */
+    additionalHelpers?: Readonly<Record<string, HelperFn>>;
+}
+interface ReamRouter {
+    makeUrl(name: string, params?: Record<string, string>): string;
+}
+interface RosettaTranslator {
+    t(key: string, params?: Record<string, string | number | boolean | Date | null | undefined>, options?: {
+        locale?: string;
+        defaultValue?: string;
+    }): string;
+}
+/** @internal Reset module-level flags between tests. */
+export declare function resetInkerProviderFlags(): void;
+export default class InkerProvider {
+    #private;
+    protected app: InkerAppContext;
+    constructor(app: InkerAppContext);
+    register(): void;
+    boot(): Promise<void>;
+    start(): Promise<void>;
+    ready(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Resolve the templates root directory:
+ *   - missing / empty → `<appRoot>/resources/templates`
+ *   - absolute path → pass through
+ *   - relative path → joined to `appRoot`
+ */
+export declare function resolveTemplatesRoot(userPath: string | undefined, appRoot: string): string;
+/**
+ * Resolve the cache mode:
+ *   - explicit "mtime" / "never" → pass through
+ *   - "auto" / undefined → "never" in production, "mtime" otherwise
+ *   - anything else → throw (typo'd modes like `"Production"` or `"NEVER"`
+ *     should not silently downgrade to dev caching)
+ */
+export declare function resolveCacheMode(userMode: CacheMode | string | undefined): "mtime" | "never";
+/**
+ * Load the asset manifest:
+ *   - injected value wins (returned verbatim — the caller's freezing applies)
+ *   - else read `<appRoot>/public/manifest.json` synchronously at boot
+ *   - else `undefined`
+ *
+ * Malformed manifests (non-object root, array, JSON parse error) → `undefined`.
+ * Non-string entries inside a valid object are silently dropped (D8).
+ */
+export declare function loadAssetManifest(injected: Readonly<Record<string, string>> | undefined, appRoot: string): Readonly<Record<string, string>> | undefined;
+/**
+ * Merge canonical + app-supplied helpers into one Map. Override warns once
+ * per name per process. Function-type validation is local; helper-key
+ * validation (identifier shape / reserved words / prototype-pollution
+ * denylists) is delegated to the `Templates` constructor (53.4 AC1).
+ */
+export declare function mergeHelpers(canonical: ReadonlyMap<string, HelperFn>, additional: Readonly<Record<string, HelperFn>> | undefined, warnedNames?: Set<string>): Map<string, HelperFn>;
+/**
+ * Coerce `url()` params: every value becomes a string via `String(v)`. Nullish
+ * roots return `undefined` (no replacement map needed). Non-object roots and
+ * arrays throw. Null / undefined / Symbol values throw rather than emit
+ * silently-broken URLs like `/users/undefined`.
+ */
+export declare function coerceUrlParams(raw: unknown): Record<string, string> | undefined;
+/**
+ * 5-char HTML attribute-value escaper. Distinct from `escapeHtml` (text-node
+ * use): attribute values need BOTH `"` and `'` escape so `value="…"` and
+ * `value='…'` cannot be broken, while text-nodes don't need quote escapes
+ * but do need `&` first to avoid double-escape.
+ */
+export declare function escapeAttr(value: string): string;
+/**
+ * Build the four canonical helper bodies. Each closes over `als` + its
+ * resolved peer + the (frozen) asset manifest. Helpers are SYNC — crossing
+ * an async boundary would drop the ALS frame (53.4 D2).
+ */
+export declare function buildCanonicalHelpers(als: AsyncLocalStorage<InkerHttpContext>, rosetta: RosettaTranslator, router: ReamRouter, assetManifest: Readonly<Record<string, string>> | undefined): Map<string, HelperFn>;
+export {};
+//# sourceMappingURL=InkerProvider.d.ts.map

package/dist/InkerProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InkerProvider.d.ts","sourceRoot":"","sources":["../src/InkerProvider.ts"],"names":[],"mappings":"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"}

package/dist/InkerProvider.js

@@ -0,0 +1,448 @@
+/**
+ * InkerProvider — Ream provider that wires `@c9up/inker` into a Ream host.
+ *
+ * `register()` binds an `InkerRenderer` singleton + the `"inker"` alias via
+ * factories that throw pre-`start()` (so an accidental preload-time resolve
+ * surfaces immediately instead of silently rendering with an unconfigured
+ * Templates instance).
+ *
+ * `start()` lazily imports `@c9up/ream/services/router` + `@c9up/rosetta`
+ * (both declared as `peerDependenciesMeta.optional`), builds the four
+ * canonical helper bodies (`t` / `csrfField` / `url` / `asset`) closing
+ * over a single `AsyncLocalStorage<InkerHttpContext>`, constructs the
+ * `Templates` instance + `InkerRenderer`, and primes `services/main`'s
+ * Proxy via `setInker`.
+ *
+ * Mirrors the StationProvider / AuroraProvider shape — duck-typed
+ * container / config / app-context interfaces, `loadBearingCast<T>` as the
+ * single sanctioned cross-package narrowing site, `isModuleNotFound`
+ * silent-degradation in Phase 1, `#started` idempotency.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as fs from "node:fs";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { InkerRenderer } from "./InkerRenderer.js";
+import { SafeString } from "./SafeString.js";
+import { setInker } from "./services/main.js";
+import { Templates } from "./Templates.js";
+// ─── Module-scoped flags (process-level, not instance-level) ─────────
+let peerWarnEmitted = false;
+let appRootFallbackWarned = false;
+const overrideWarnEmittedNames = new Set();
+/** @internal Reset module-level flags between tests. */
+export function resetInkerProviderFlags() {
+    peerWarnEmitted = false;
+    appRootFallbackWarned = false;
+    overrideWarnEmittedNames.clear();
+}
+// ─── Provider class ──────────────────────────────────────────────
+export default class InkerProvider {
+    app;
+    #als;
+    #renderer;
+    #started = false;
+    // P17: per-instance override-warn dedup. Was a module-level Set shared
+    // across every provider instance in the process — broke test isolation
+    // and multi-tenant scenarios where each tenant has its own provider with
+    // its own additionalHelpers map.
+    #overrideWarnedNames = new Set();
+    constructor(app) {
+        this.app = app;
+    }
+    register() {
+        this.app.container.singleton(InkerRenderer, () => this.#getRendererOrThrow());
+        this.app.container.singleton("inker", () => this.app.container.resolve(InkerRenderer));
+    }
+    async boot() {
+        // No-op. Peers (Rosetta, Router) are resolved at start() — earlier
+        // phases run before Ignitor finishes wiring the router proxy and
+        // before RosettaProvider's boot loads catalogs.
+    }
+    async start() {
+        if (this.#started)
+            return;
+        // Phase 1 — lazy peer imports. Both `@c9up/ream/services/router` and
+        // `@c9up/rosetta` are optional peers. Module-not-found is the
+        // degraded-host signal: silently return + warn-once. Anything else
+        // re-throws.
+        let router;
+        let rosetta;
+        try {
+            // Variable specifier so tsc does not statically resolve the optional
+            // `@c9up/ream` peer at build time (keeps inker standalone-buildable).
+            const routerSpecifier = "@c9up/ream/services/router";
+            const routerMod = await import(routerSpecifier);
+            router = routerMod.default;
+            const rosettaContainer = this.#resolveRosetta();
+            if (rosettaContainer === undefined) {
+                this.#warnPeerMissingOnce("`@c9up/rosetta` is available as a module but no Rosetta instance is registered in the container. The `t()` helper will throw at first render.");
+                return;
+            }
+            rosetta = rosettaContainer;
+        }
+        catch (err) {
+            if (isModuleNotFound(err)) {
+                this.#warnPeerMissingOnce("`@c9up/ream/services/router` or `@c9up/rosetta` is not installed. Inker rendering is disabled until both peers are present.");
+                return;
+            }
+            throw err;
+        }
+        // Phase 2 — resolve config.
+        const config = this.app.config.get("inker") ?? {};
+        const appRoot = this.#readAppRoot();
+        const templatesRoot = resolveTemplatesRoot(config.templatesRoot, appRoot);
+        const cacheMode = resolveCacheMode(config.cacheMode);
+        const assetManifest = loadAssetManifest(config.assetManifest, appRoot);
+        // Phase 3 — build canonical helpers Map.
+        const als = new AsyncLocalStorage();
+        this.#als = als;
+        const canonical = buildCanonicalHelpers(als, rosetta, router, assetManifest);
+        // Phase 4 — merge additional helpers (override-warn-once per instance).
+        const merged = mergeHelpers(canonical, config.additionalHelpers, this.#overrideWarnedNames);
+        // Phase 5 — construct Templates + InkerRenderer + bind into proxy.
+        const templates = new Templates({
+            root: templatesRoot,
+            cacheMode,
+            helpers: merged,
+        });
+        const renderer = new InkerRenderer(templates, als);
+        this.#renderer = renderer;
+        setInker(renderer);
+        this.#started = true;
+    }
+    async ready() { }
+    async shutdown() {
+        // Intentionally a no-op. `#started` guards `start()` from re-running,
+        // so once the provider has booted, subsequent lifecycle calls have
+        // nothing to undo here: `Templates` owns its own cache, AsyncLocalStorage
+        // has no destroy contract, and the `setInker` singleton intentionally
+        // outlives shutdown so late-arriving handlers don't see a torn-down
+        // proxy. `Templates.clearCache()` is the operator's tool, not ours.
+    }
+    #getRendererOrThrow() {
+        if (this.#renderer === undefined) {
+            throw new Error("[inker] InkerRenderer resolved before InkerProvider.start() ran. " +
+                "Wait for the boot lifecycle to complete, or call `start()` manually.");
+        }
+        return this.#renderer;
+    }
+    #warnPeerMissingOnce(detail) {
+        if (peerWarnEmitted)
+            return;
+        peerWarnEmitted = true;
+        console.warn(`[inker] ${detail} See https://ream.dev/modules/inker.`);
+    }
+    #readAppRoot() {
+        try {
+            const raw = this.app.container.resolve("appRoot");
+            if (raw instanceof URL)
+                return fileURLToPath(raw);
+            if (typeof raw === "string")
+                return raw;
+        }
+        catch (err) {
+            // Only swallow the "no binding" path — re-throw factory errors so
+            // host misconfiguration surfaces instead of being masked as a
+            // cwd-fallback.
+            if (!isContainerNotFound(err))
+                throw err;
+        }
+        if (!appRootFallbackWarned) {
+            appRootFallbackWarned = true;
+            console.warn("[inker] No `appRoot` binding (URL or string) resolved from the container; falling back to process.cwd(). Templates and the asset manifest will be read relative to the process working directory — bind `appRoot` in the host container if that is not what you want.");
+        }
+        return process.cwd();
+    }
+    #resolveRosetta() {
+        // Try container resolution under both the canonical "rosetta" alias
+        // and the class binding. RosettaProvider binds both (per
+        // `packages/rosetta/src/RosettaProvider.ts`).
+        //
+        // Only the "binding not registered" path is swallowed (host truly
+        // lacks Rosetta — Phase 1 silently degrades). Factory-thrown errors
+        // (catalog load failure, malformed YAML, etc.) re-throw — Station's
+        // `#resolveDb` is loud for the same reason: surfacing operator
+        // misconfiguration beats misdiagnosing it as "rosetta missing".
+        const tokens = ["rosetta", "Rosetta"];
+        for (const token of tokens) {
+            try {
+                const candidate = this.app.container.resolve(token);
+                if (isRosettaShape(candidate)) {
+                    return candidate;
+                }
+            }
+            catch (err) {
+                if (isContainerNotFound(err))
+                    continue;
+                throw err;
+            }
+        }
+        return undefined;
+    }
+}
+// ─── Pure resolvers (exported @internal for unit tests) ──────────────
+/**
+ * Resolve the templates root directory:
+ *   - missing / empty → `<appRoot>/resources/templates`
+ *   - absolute path → pass through
+ *   - relative path → joined to `appRoot`
+ */
+export function resolveTemplatesRoot(userPath, appRoot) {
+    if (typeof userPath !== "string" || userPath.length === 0) {
+        return resolvePath(appRoot, "resources/templates");
+    }
+    return isAbsolute(userPath) ? userPath : resolvePath(appRoot, userPath);
+}
+/**
+ * Resolve the cache mode:
+ *   - explicit "mtime" / "never" → pass through
+ *   - "auto" / undefined → "never" in production, "mtime" otherwise
+ *   - anything else → throw (typo'd modes like `"Production"` or `"NEVER"`
+ *     should not silently downgrade to dev caching)
+ */
+export function resolveCacheMode(userMode) {
+    if (userMode === "mtime" || userMode === "never")
+        return userMode;
+    if (userMode !== undefined && userMode !== "auto") {
+        throw new Error(`[inker] config.inker.cacheMode must be "mtime", "never", "auto", or undefined; got ${JSON.stringify(userMode)}.`);
+    }
+    return process.env.NODE_ENV === "production" ? "never" : "mtime";
+}
+/**
+ * Load the asset manifest:
+ *   - injected value wins (returned verbatim — the caller's freezing applies)
+ *   - else read `<appRoot>/public/manifest.json` synchronously at boot
+ *   - else `undefined`
+ *
+ * Malformed manifests (non-object root, array, JSON parse error) → `undefined`.
+ * Non-string entries inside a valid object are silently dropped (D8).
+ */
+export function loadAssetManifest(injected, appRoot) {
+    if (injected !== undefined)
+        return injected;
+    const manifestPath = resolvePath(appRoot, "public/manifest.json");
+    let raw;
+    try {
+        raw = fs.readFileSync(manifestPath, "utf8");
+    }
+    catch (err) {
+        // P19: ENOENT is "no manifest configured" — silent absence is the
+        // expected dev-without-build state. Any OTHER error (EACCES, EISDIR,
+        // ELOOP, etc.) indicates a real misconfiguration that would otherwise
+        // surface as a silent "every asset URL falls back to /_assets/foo"
+        // degradation in prod. Warn so the operator sees the misconfig.
+        const code = err instanceof Error ? Reflect.get(err, "code") : undefined;
+        if (typeof code === "string" && code !== "ENOENT") {
+            console.warn(`[inker] Failed to read asset manifest at ${manifestPath}: ${code}. asset() helpers will fall back to '/_assets/<path>' until this is resolved.`);
+        }
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return undefined;
+    }
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v === "string")
+            out[k] = v;
+    }
+    return Object.freeze(out);
+}
+/**
+ * Merge canonical + app-supplied helpers into one Map. Override warns once
+ * per name per process. Function-type validation is local; helper-key
+ * validation (identifier shape / reserved words / prototype-pollution
+ * denylists) is delegated to the `Templates` constructor (53.4 AC1).
+ */
+export function mergeHelpers(canonical, additional, 
+// P17: optional per-instance warn-dedup set. Defaults to the module-level
+// set for backward compat with direct callers; InkerProvider now passes
+// its own per-instance `#overrideWarnedNames` so multi-tenant /
+// multi-provider setups don't share warn state. Tests that rely on the
+// module-level set still work via `resetInkerProviderFlags`.
+warnedNames = overrideWarnEmittedNames) {
+    const out = new Map(canonical);
+    if (additional === undefined)
+        return out;
+    for (const [name, fn] of Object.entries(additional)) {
+        if (typeof fn !== "function") {
+            throw new Error(`[inker] additionalHelpers.${name} must be a function; got ${typeof fn}.`);
+        }
+        if (out.has(name) && !warnedNames.has(name)) {
+            warnedNames.add(name);
+            console.warn(`[inker] additionalHelpers.${name} overrides the canonical helper. Suppressing further warnings for this name.`);
+        }
+        out.set(name, fn);
+    }
+    return out;
+}
+/**
+ * Coerce `url()` params: every value becomes a string via `String(v)`. Nullish
+ * roots return `undefined` (no replacement map needed). Non-object roots and
+ * arrays throw. Null / undefined / Symbol values throw rather than emit
+ * silently-broken URLs like `/users/undefined`.
+ */
+export function coerceUrlParams(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`[inker] url() params must be a plain object; got ${Array.isArray(raw) ? "array" : typeof raw}.`);
+    }
+    // P9: Date objects pass the "is object, not array" check but `Object.entries`
+    // returns `[]` for them — silently emitting an empty params Map and a URL
+    // built from no replacements. Refuse explicitly with a hint pointing to
+    // `toISOString()`.
+    if (raw instanceof Date) {
+        throw new Error("[inker] url() params cannot be a Date instance — call `.toISOString()` first or wrap it in a plain object.");
+    }
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(raw)) {
+        if (v === null || v === undefined) {
+            throw new Error(`[inker] url() param '${k}' is ${v === null ? "null" : "undefined"} — omit the key or provide a value.`);
+        }
+        if (typeof v === "symbol") {
+            throw new Error(`[inker] url() param '${k}' is a Symbol — only stringifiable primitives are supported.`);
+        }
+        // P8: NaN / +Infinity / -Infinity all stringify into URL-unfriendly
+        // `"NaN"` / `"Infinity"` literals, producing routes like
+        // `/users/NaN`. Authors usually arrive here via a downstream helper
+        // that returned an unexpected non-finite value; surface it loud.
+        if (typeof v === "number" && !Number.isFinite(v)) {
+            throw new Error(`[inker] url() param '${k}' is ${Number.isNaN(v) ? "NaN" : v > 0 ? "Infinity" : "-Infinity"} — only finite numbers are supported.`);
+        }
+        out[k] = String(v);
+    }
+    return out;
+}
+/**
+ * 5-char HTML attribute-value escaper. Distinct from `escapeHtml` (text-node
+ * use): attribute values need BOTH `"` and `'` escape so `value="…"` and
+ * `value='…'` cannot be broken, while text-nodes don't need quote escapes
+ * but do need `&` first to avoid double-escape.
+ */
+export function escapeAttr(value) {
+    // P10: backtick added for parity with `escapeChar` in render.ts. Legacy
+    // IE and some permissive parsers treat backtick as an attribute-value
+    // delimiter inside unquoted attributes; we still emit quoted attributes
+    // but encode it defensively in case a downstream rewrite drops the
+    // quotes.
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;")
+        .replace(/`/g, "&#96;");
+}
+/**
+ * Build the four canonical helper bodies. Each closes over `als` + its
+ * resolved peer + the (frozen) asset manifest. Helpers are SYNC — crossing
+ * an async boundary would drop the ALS frame (53.4 D2).
+ */
+export function buildCanonicalHelpers(als, rosetta, router, assetManifest) {
+    const requireCtx = (helperName) => {
+        const ctx = als.getStore();
+        if (ctx === undefined) {
+            throw new Error(`[inker] ${helperName}() invoked outside of an inker.render(ctx, …) call — store unavailable.`);
+        }
+        return ctx;
+    };
+    const helpers = new Map();
+    helpers.set("t", (...args) => {
+        const [key, params] = args;
+        if (typeof key !== "string") {
+            throw new Error(`[inker] t() requires a string key; got ${typeof key}.`);
+        }
+        const ctx = requireCtx("t");
+        // Rosetta's TranslationParams is narrower than HelperFn's
+        // `unknown[]` — the load-bearing narrow is the contract boundary;
+        // Rosetta validates value types and throws on unsupported shapes.
+        const rosettaParams = params === undefined
+            ? undefined
+            : loadBearingCast(params);
+        return rosetta.t(key, rosettaParams, { locale: ctx.locale });
+    });
+    helpers.set("csrfField", (..._args) => {
+        const ctx = requireCtx("csrfField");
+        const token = ctx.store.get("csrfToken");
+        if (typeof token !== "string" || token.length === 0) {
+            throw new Error("[inker] csrfField() requires the @c9up/blackhole middleware with csrf enabled (csrfToken not found in ctx.store).");
+        }
+        return new SafeString(`<input type="hidden" name="_csrf" value="${escapeAttr(token)}">`);
+    });
+    helpers.set("csrfMeta", (..._args) => {
+        const ctx = requireCtx("csrfMeta");
+        const token = ctx.store.get("csrfToken");
+        if (typeof token !== "string" || token.length === 0) {
+            throw new Error("[inker] csrfMeta() requires the @c9up/blackhole middleware with csrf enabled (csrfToken not found in ctx.store).");
+        }
+        return new SafeString(`<meta name="csrf-token" content="${escapeAttr(token)}">`);
+    });
+    helpers.set("cspNonce", (..._args) => {
+        const ctx = requireCtx("cspNonce");
+        const nonce = ctx.store.get("cspNonce");
+        // Non-throwing: CSP nonces are opt-in (only present when the CSP uses
+        // `@nonce`), so an absent nonce yields an empty attribute, not an error.
+        return typeof nonce === "string" ? nonce : "";
+    });
+    helpers.set("url", (...args) => {
+        const [name, params] = args;
+        if (typeof name !== "string") {
+            throw new Error(`[inker] url() requires a string route name; got ${typeof name}.`);
+        }
+        const coerced = coerceUrlParams(params);
+        return router.makeUrl(name, coerced);
+    });
+    helpers.set("asset", (...args) => {
+        const [name] = args;
+        if (typeof name !== "string") {
+            throw new Error(`[inker] asset() requires a string asset name; got ${typeof name}.`);
+        }
+        return assetManifest?.[name] ?? `/_assets/${name}`;
+    });
+    return helpers;
+}
+// ─── Internal predicates / casts ──────────────────────────────────
+function isRosettaShape(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        typeof Reflect.get(value, "t") === "function");
+}
+/** Node's ERR_MODULE_NOT_FOUND surfaces on an Error subclass with `code`. */
+function isModuleNotFound(err) {
+    if (err === null || typeof err !== "object" || !("code" in err))
+        return false;
+    const { code } = err;
+    return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+/**
+ * Ream's container throws a `ReamError` with `code === "CONTAINER_NOT_FOUND"`
+ * when a token is unbound. Duck-typed here so `@c9up/ream` stays an optional
+ * peer (no import-time dep on its error class).
+ */
+function isContainerNotFound(err) {
+    if (err === null || typeof err !== "object" || !("code" in err))
+        return false;
+    return err.code === "CONTAINER_NOT_FOUND";
+}
+/**
+ * SANCTIONED CROSS-PACKAGE NARROWING — the ONE production site in
+ * `@c9up/inker/provider` where `as T` is permitted. Memory
+ * `feedback_no_any_types` is honoured by funnelling every load-bearing
+ * narrow (dynamic peer imports, Rosetta params widened to Inker's HelperFn
+ * shape) through this single function. Analogous to 54.2 AC15 / 54.1 AC9 /
+ * `tests/__helpers__/bypass-type-check.ts`. Every call site MUST carry a
+ * rationale comment explaining why static narrowing isn't expressible at
+ * the boundary. NEVER widen this helper beyond `unknown → T`.
+ */
+function loadBearingCast(value) {
+    return value;
+}
+//# sourceMappingURL=InkerProvider.js.map