@blokjs/shared 0.2.2 → 0.6.0

package/dist/NodeBase.js

@@ -1,6 +1,7 @@
 import _ from "lodash";
 import GlobalError from "./GlobalError";
 import mapper from "./utils/Mapper";
+import { MapperResolutionError } from "./utils/MapperResolutionError";
 export default class NodeBase {
     flow = false;
     name = "";
@@ -8,17 +9,6 @@ export default class NodeBase {
     active = true;
     stop = false;
     originalConfig = {};
-    /**
-     * @deprecated v2 default-stores every step's output. `set_var: true` is
-     * a no-op (default behaviour); `set_var: false` is normalized to
-     * `ephemeral: true` at workflow load time. Reading this field is still
-     * supported for legacy code paths but new code should rely on `ephemeral`.
-     *
-     * Default is `undefined` (NOT `false`) — `false` here would short-circuit
-     * `PersistenceHelper.applyStepOutput` and disable the v2 default-store
-     * rule for every step that didn't explicitly set the field.
-     */
-    set_var;
     // =========================================================================
     // V2 persistence knobs — populated by Configuration.getSteps from the
     // step definition. Read by PersistenceHelper.applyStepOutput.
@@ -39,6 +29,75 @@ export default class NodeBase {
      * Only `ctx.prev` carries the result to the immediately next step.
      */
     ephemeral = false;
+    // =========================================================================
+    // V2 idempotency cache + retry knobs — populated by Configuration.getSteps
+    // from the step definition. Read by RunnerSteps before delegating to
+    // `step.process()`. Caching layers ABOVE PersistenceHelper.applyStepOutput;
+    // retry wraps the same call site.
+    //
+    // Mirrors the Zod schema in `@blokjs/helper/src/types/StepOpts.ts`. Kept
+    // as a structural interface here to avoid a runtime dep from shared on
+    // helper.
+    // =========================================================================
+    /**
+     * Optional cache key for this step's result. When set, the runner consults
+     * the idempotency cache before executing — a hit returns the cached result
+     * (and emits a NODE_CACHED event); a miss runs the step and caches its
+     * result on success. Cache namespace is (workflowName, name, idempotencyKey).
+     *
+     * Author-facing values may be a literal string ("user-123") or a $ proxy
+     * expression compiled to `js/ctx....`. The runner resolves the expression
+     * against the live ctx at run time before consulting the cache.
+     */
+    idempotencyKey;
+    /**
+     * Optional cache lifetime in milliseconds. Defaults to 24 hours
+     * (86_400_000) when undefined. Pass 0 to mark a stored result as
+     * immediately expired (effectively disables caching for this step).
+     */
+    idempotencyKeyTTL;
+    /**
+     * Optional retry configuration with capped exponential backoff. When
+     * undefined, the step runs at most once (matches pre-v0.3.x behaviour).
+     * Per-attempt failures emit `NODE_ATTEMPT_FAILED` trace events.
+     */
+    retry;
+    /**
+     * Tier 2 quick-wins — per-attempt execution timeout in milliseconds.
+     * When set, `RunnerSteps` wraps each `step.process()` in a setTimeout-
+     * based Promise.race. On timeout, throws `StepTimeoutError` (which the
+     * retry loop treats as any other error). On final-attempt timeout,
+     * the run auto-flips to `"timedOut"` status. When undefined, the
+     * step runs without a per-attempt cap (matches pre-quick-wins
+     * behaviour).
+     *
+     * Originally set as a duration string or number on the step schema;
+     * `Configuration.getSteps` converts to milliseconds via
+     * `parseDuration` before assigning here.
+     */
+    maxDurationMs;
+    // =========================================================================
+    // V2 sub-workflow knobs — populated by Configuration.getSteps for steps
+    // that invoke another workflow (`subworkflow: "<name>"` shape). Read by
+    // `SubworkflowNode.run()` to look up the child workflow in the
+    // WorkflowRegistry. Mirrors the Zod schema in `@blokjs/helper`.
+    // =========================================================================
+    /**
+     * Name of the workflow to invoke when this step runs. When set, the
+     * step's `node` ref is `"@blokjs/subworkflow"` (a sentinel) and the
+     * runner resolves it to a `SubworkflowNode` that looks up the child
+     * by this name in the `WorkflowRegistry` singleton.
+     */
+    subworkflow;
+    /**
+     * If true (default), the parent step blocks until the child workflow
+     * completes. The child's `ctx.response` becomes the parent step's
+     * output (lands on `state[<id>]` like any other step).
+     *
+     * `wait: false` (fire-and-forget) is rejected at workflow load time
+     * in v0.3.x — the schema includes a deferred-feature error message.
+     */
+    wait;
     async process(ctx, step) {
         let response = {
             success: true,
@@ -106,7 +165,15 @@ export default class NodeBase {
                 mapper.replaceObjectStrings(newObj, ctx, data);
         }
         catch (e) {
-            console.log("MAPPER ERROR", e);
+            // `MapperResolutionError` (strict mode) carries full diagnostic
+            // context — let it escape so the step's error envelope surfaces
+            // the workflow / step / expression that failed.
+            if (e instanceof MapperResolutionError)
+                throw e;
+            // Anything else here is an UNEXPECTED bug in the mapper itself
+            // (recursion fault, OOM, logger crash). Surface loudly via
+            // stderr WITH the stack trace — never silently swallow.
+            console.error("[blok][mapper] unexpected error during input resolution:", e);
         }
         return newObj;
     };

package/dist/NodeBase.js.map

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

package/dist/index.d.ts

@@ -5,7 +5,9 @@ import { Metrics, type MetricsType } from "./Metrics";
 import NodeBase from "./NodeBase";
 import Trigger from "./Trigger";
 import ConfigContext from "./types/ConfigContext";
+import type ConnectionContext from "./types/ConnectionContext";
 import Context from "./types/Context";
+import EnvContext from "./types/EnvContext";
 import ErrorContext from "./types/ErrorContext";
 import FunctionContext from "./types/FunctionContext";
 import LoggerContext from "./types/LoggerContext";
@@ -14,6 +16,8 @@ import RequestContext from "./types/RequestContext";
 import ResponseContext from "./types/ResponseContext";
 import StateContext from "./types/StateContext";
 import Step from "./types/Step";
+import type StreamContext from "./types/StreamContext";
 import VarsContext from "./types/VarsContext";
+import mapper from "./utils/Mapper";
 import MemoryUsage from "./utils/MemoryUsage";
-export { NodeBase, Context, RequestContext, ResponseContext, ErrorContext, LoggerContext, ConfigContext, Trigger, NodeConfigContext, FunctionContext, StateContext, VarsContext, Step, GlobalLogger, GlobalError, BlokError, type BlokErrorOpts, type NodeErrorPayload, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, Metrics, MemoryUsage, type MetricsType, };
+export { NodeBase, Context, RequestContext, ResponseContext, EnvContext, ErrorContext, LoggerContext, ConfigContext, type ConnectionContext, type StreamContext, Trigger, NodeConfigContext, FunctionContext, StateContext, VarsContext, Step, GlobalLogger, GlobalError, BlokError, type BlokErrorOpts, type NodeErrorPayload, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, Metrics, MemoryUsage, type MetricsType, mapper, };

package/dist/index.js

@@ -4,6 +4,7 @@ import GlobalLogger from "./GlobalLogger";
 import { Metrics } from "./Metrics";
 import NodeBase from "./NodeBase";
 import Trigger from "./Trigger";
+import mapper from "./utils/Mapper";
 import MemoryUsage from "./utils/MemoryUsage";
-export { NodeBase, Trigger, GlobalLogger, GlobalError, BlokError, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, Metrics, MemoryUsage, };
+export { NodeBase, Trigger, GlobalLogger, GlobalError, BlokError, ErrorCategory, ErrorSeverity, DEFAULT_HTTP_STATUS, DEFAULT_RETRYABLE, Metrics, MemoryUsage, mapper, };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,EAAE,EAEjB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,aAAa,GAEb,MAAM,aAAa,CAAC;AACrB,OAAO,WAAW,MAAM,eAAe,CAAC;AACxC,OAAO,YAAY,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AACtD,OAAO,QAAQ,MAAM,YAAY,CAAC;AAClC,OAAO,OAAO,MAAM,WAAW,CAAC;AAYhC,OAAO,WAAW,MAAM,qBAAqB,CAAC;AAE9C,OAAO,EACN,QAAQ,EAOR,OAAO,EAMP,YAAY,EACZ,WAAW,EACX,SAAS,EAGT,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,OAAO,EACP,WAAW,GAEX,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,EAAE,EAEjB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,aAAa,GAEb,MAAM,aAAa,CAAC;AACrB,OAAO,WAAW,MAAM,eAAe,CAAC;AACxC,OAAO,YAAY,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AACtD,OAAO,QAAQ,MAAM,YAAY,CAAC;AAClC,OAAO,OAAO,MAAM,WAAW,CAAC;AAehC,OAAO,MAAM,MAAM,gBAAgB,CAAC;AACpC,OAAO,WAAW,MAAM,qBAAqB,CAAC;AAE9C,OAAO,EACN,QAAQ,EAUR,OAAO,EAMP,YAAY,EACZ,WAAW,EACX,SAAS,EAGT,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,OAAO,EACP,WAAW,EAEX,MAAM,GACN,CAAC"}

package/dist/types/ConnectionContext.d.ts

@@ -0,0 +1,79 @@
+/**
+ * v0.7 — per-connection API exposed on `ctx.connection` for triggers
+ * that hold long-lived bidirectional channels (WebSocket today; SSE
+ * gets a streaming variant in PR 3).
+ *
+ * Authors interact with the connection through this object — the
+ * trigger wraps the underlying transport's send/close primitives and
+ * tracks per-connection state. Lifecycle:
+ *
+ *   - On `connect`: trigger creates the connection, runs the workflow
+ *     once with `ctx.connection` bound. Author can call
+ *     `setAttachment()` to store per-connection state.
+ *   - On `message`: trigger runs the workflow again with the same
+ *     `ctx.connection` instance — author reads `attachment` to recover
+ *     the per-connection state.
+ *   - On `disconnect`: same connection, last run. Cleanup happens here.
+ *
+ * Absent on contexts built for HTTP / Worker / Cron triggers.
+ */
+export interface ConnectionContext {
+    /** Stable connection identifier (uuid). Set once at connect. */
+    readonly id: string;
+    /**
+     * Send data to THIS connection.
+     * - Text payloads: send a string (typically `JSON.stringify(...)`).
+     * - Binary payloads: send a `Uint8Array` or `ArrayBuffer`.
+     *
+     * Buffered if the underlying socket is busy; backpressure visible
+     * via the trigger's `messageRateLimit` and Studio trace metrics.
+     */
+    send(data: string | ArrayBuffer | Uint8Array): void;
+    /**
+     * Close THIS connection cleanly. Subsequent `send` calls are no-ops.
+     * Triggers the `disconnect` workflow run as a final step.
+     *
+     * @param code   Close code per RFC 6455 (default 1000 — normal).
+     * @param reason Human-readable reason (max 123 bytes per RFC).
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Store per-connection state. Survives across message-event workflow
+     * runs on the same connection — the "userId + joinedAt + cursor"
+     * pattern. Reset by every call (no merge).
+     *
+     * Inspired by Cloudflare Durable Objects'
+     * `state.serializeAttachment()` API. Capped at 2 KB serialized JSON;
+     * larger values are rejected with a warning log (the connection
+     * stays open).
+     */
+    setAttachment(value: unknown): void;
+    /**
+     * Retrieve per-connection state set by `setAttachment()`. Returns
+     * `undefined` if nothing was set on this connection.
+     */
+    readonly attachment: unknown;
+    /**
+     * Channel/room membership for fan-out broadcasts. Multiple
+     * connections can join the same room; `@blokjs/ws-broadcast`
+     * targets every member.
+     */
+    joinRoom(name: string): void;
+    leaveRoom(name: string): void;
+    readonly rooms: ReadonlySet<string>;
+    /**
+     * v0.7 — broadcast a message to every connection in the named
+     * room (workflow-scoped). Returns the number of recipients
+     * the trigger successfully sent to.
+     *
+     * Set `exceptSelf: true` to skip the connection that triggered
+     * the current workflow run (the "send to everyone except me"
+     * pattern). Bound by the trigger via this `ctx.connection`
+     * accessor so helper nodes (`@blokjs/ws-broadcast`) don't need
+     * to import the trigger package directly.
+     */
+    broadcast(room: string, data: string | ArrayBuffer | Uint8Array, opts?: {
+        exceptSelf?: boolean;
+    }): number;
+}
+export default ConnectionContext;

package/dist/types/ConnectionContext.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ConnectionContext.js.map

package/dist/types/ConnectionContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectionContext.js","sourceRoot":"","sources":["../../src/types/ConnectionContext.ts"],"names":[],"mappings":""}

package/dist/types/Context.d.ts

@@ -1,5 +1,6 @@
 import type GlobalLogger from "../GlobalLogger";
 import type ConfigContext from "./ConfigContext";
+import type ConnectionContext from "./ConnectionContext";
 import type EnvContext from "./EnvContext";
 import type ErrorContext from "./ErrorContext";
 import type FunctionContext from "./FunctionContext";
@@ -7,6 +8,7 @@ import type LoggerContext from "./LoggerContext";
 import type RequestContext from "./RequestContext";
 import type ResponseContext from "./ResponseContext";
 import type StateContext from "./StateContext";
+import type StreamContext from "./StreamContext";
 import type VarsContext from "./VarsContext";
 /**
  * The runtime context for a single workflow execution. One Context object
@@ -94,6 +96,55 @@ type Context = {
      * publish something other than its return value (most nodes don't).
      */
     publish?: (name: string, value: unknown) => void;
+    /**
+     * Tier 2 follow-up · cooperative cancellation. AbortSignal whose
+     * `aborted` flips to true when an operator cancels the run via
+     * `POST /__blok/runs/:runId/cancel` while it's in `running` status.
+     *
+     * Nodes that perform long-running work (loops, fetch, db queries)
+     * should consult `ctx.signal.aborted` periodically and abort early
+     * — or pass the signal to fetch/abort-aware APIs:
+     *
+     *     await fetch(url, { signal: ctx.signal });
+     *     if (ctx.signal?.aborted) throw new Error("aborted");
+     *
+     * Always present on contexts created by `TriggerBase.createContext`.
+     * Optional on the type for back-compat with hand-built contexts in
+     * tests.
+     */
+    signal?: AbortSignal;
+    /**
+     * v0.7 — per-connection API for long-lived bidirectional triggers
+     * (WebSocket). Present on contexts dispatched by `WebSocketTrigger`;
+     * absent on HTTP / Worker / Cron contexts.
+     *
+     * Authors call `ctx.connection.send(...)` to push to the specific
+     * connection that fired the event, `ctx.connection.close(...)` to
+     * terminate it, or `ctx.connection.setAttachment(...)` to store
+     * per-connection state that survives across the connect → N×message
+     * → disconnect lifecycle.
+     *
+     * Helper nodes (`@blokjs/ws-reply`, `@blokjs/ws-broadcast`,
+     * `@blokjs/ws-close`) read this field to interact with the
+     * connection without authors having to thread the ws handle through
+     * step inputs.
+     */
+    connection?: ConnectionContext;
+    /**
+     * v0.7 — per-stream API for server-push HTTP triggers (SSE).
+     * Present on contexts dispatched by `SSETrigger` once per stream
+     * open; absent on HTTP / WebSocket / Worker / Cron contexts.
+     *
+     * Authors call `ctx.stream.writeSSE({ event, data, id, retry })`
+     * to emit frames, `ctx.stream.close()` to end the stream, and
+     * read `ctx.stream.signal.aborted` to detect client disconnects
+     * inside long-running loops.
+     *
+     * Helper nodes (`@blokjs/sse-stream`) read this field so workflow
+     * authors don't have to thread the stream handle through step
+     * inputs.
+     */
+    stream?: StreamContext;
     _PRIVATE_: unknown;
 };
 export default Context;

package/dist/types/StreamContext.d.ts

@@ -0,0 +1,92 @@
+/**
+ * v0.7 — per-stream API exposed on `ctx.stream` for triggers that hold
+ * a long-lived, server-push HTTP channel (SSE today; the `streaming`
+ * Hono helper underneath). Authors emit events through this object;
+ * the trigger owns the underlying `c.writeSSE` / drain handling.
+ *
+ * Lifecycle (Pattern A — one workflow run per stream open):
+ *
+ *   - The SSE trigger opens the HTTP stream via Hono's `streamSSE`,
+ *     creates this object, attaches it to `ctx.stream`, and dispatches
+ *     the workflow once.
+ *   - The workflow body writes zero or more events via
+ *     `writeSSE(...)`, typically via `@blokjs/sse-stream` consuming an
+ *     async iterator from `@blokjs/sse-subscribe`.
+ *   - The workflow returns when its iterator ends OR when
+ *     `ctx.stream.signal.aborted` flips (client closed). The trigger
+ *     ends the run with status `completed`.
+ *
+ * Absent on contexts built for HTTP (request/response), Worker, Cron,
+ * or WebSocket triggers.
+ */
+export interface StreamContext {
+    /** Stable stream/connection identifier (uuid). Set once at open. */
+    readonly id: string;
+    /**
+     * Write one SSE-framed event to the client. Each call produces a
+     * `data:` (and optional `event:`, `id:`, `retry:`) frame followed
+     * by a blank line.
+     *
+     * `data` is JSON-stringified when it's not a string. Pass a string
+     * to write the payload verbatim. Returns once the chunk has been
+     * accepted by Node's stream (honors backpressure via `drain`).
+     */
+    writeSSE(opts: {
+        event?: string;
+        data: unknown;
+        id?: string;
+        retry?: number;
+    }): Promise<void>;
+    /**
+     * Write an SSE comment line (`: <text>\n\n`). Used internally for
+     * heartbeats; authors rarely need this directly. Comments are
+     * ignored by `EventSource` clients but keep proxies from idling
+     * the connection.
+     */
+    writeComment(text: string): Promise<void>;
+    /**
+     * Close the stream cleanly. Subsequent `writeSSE` calls are no-ops.
+     * The workflow run ends at the next yield point.
+     */
+    close(): void;
+    /** True after `close()` is called or the client disconnects. */
+    readonly closed: boolean;
+    /**
+     * `AbortSignal` that fires when the client disconnects (browser tab
+     * closed, network drop, manual `EventSource.close()`). Long-running
+     * iterators / fetches should be bound to this signal so they unwind
+     * promptly:
+     *
+     *     for await (const evt of source) {
+     *       if (ctx.stream.signal.aborted) break;
+     *       await ctx.stream.writeSSE({ data: evt });
+     *     }
+     */
+    readonly signal: AbortSignal;
+    /**
+     * `Last-Event-Id` HTTP header value from the inbound request, if
+     * the client is reconnecting. Helper nodes (`@blokjs/sse-subscribe`)
+     * read this to resume from the indicated cursor.
+     */
+    readonly lastEventId: string | null;
+    /**
+     * v0.7 — subscribe to the in-process SSE event bus. Returns an
+     * async iterator that yields events published to any of the named
+     * channels. When `lastEventId` is provided (or omitted — defaults
+     * to `ctx.stream.lastEventId`), buffered events with `seq > lastEventId`
+     * are replayed before live events begin. Caller stops the
+     * subscription by exiting the for-await loop or calling
+     * `iterator.return()`.
+     *
+     * Bound by the trigger so helper nodes (`@blokjs/sse-subscribe`,
+     * `@blokjs/sse-stream`) don't have to import the trigger directly.
+     */
+    subscribe(channels: string[], lastEventId?: string | null): AsyncIterableIterator<{
+        channel: string;
+        id: string;
+        event?: string;
+        data: unknown;
+        timestamp: number;
+    }>;
+}
+export default StreamContext;

package/dist/types/StreamContext.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=StreamContext.js.map

package/dist/types/StreamContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamContext.js","sourceRoot":"","sources":["../../src/types/StreamContext.ts"],"names":[],"mappings":""}

package/dist/utils/Mapper.d.ts

@@ -1,10 +1,119 @@
 import type Context from "../types/Context";
 import type ParamsDictionary from "../types/ParamsDictionary";
+/**
+ * Mapper — the workflow input resolver.
+ *
+ * Every step's `inputs` object is walked by `replaceObjectStrings`
+ * before the step runs (see `NodeBase.process` → `blueprintMapper`).
+ * Two template syntaxes are recognised:
+ *
+ * 1. **`${path.to.value}`** — interpolated string placeholder.
+ *    Resolved via lodash `_.get(data, key)` first, with a JS-eval
+ *    fallback when the key is not in `data`. Multiple placeholders
+ *    in one string are concatenated.
+ *
+ * 2. **`"js/..."`** — full-string JS expression. The string is
+ *    replaced ENTIRELY by the result of evaluating the expression
+ *    (after stripping the `js/` prefix) against the live `ctx`.
+ *    Returns whatever value the expression produces (string, number,
+ *    object, array, etc.) — preserves type fidelity end-to-end.
+ *
+ * Both syntaxes evaluate inside a sandboxed `Function` with these
+ * names in scope: `ctx`, `data`, `func`, `vars`. (Symmetric scope
+ * across both syntaxes since v0.3.x — pre-v0.3.x `${...}` evaluator
+ * lacked `func`+`vars`, leading to surprising scope mismatches.)
+ *
+ * ## Failure modes — see {@link MapperResolutionError}
+ *
+ * Resolution failures (typo, undefined access, syntax error) used to
+ * be swallowed silently with a noisy `console.log("Mapper Error N", e)`
+ * — and worse, the unresolved expression string passed through to the
+ * node, producing silent miscompiles downstream. Since v0.3.x the
+ * Mapper packages every failure in a `MapperResolutionError` with full
+ * context (workflow, step, expression, underlying cause + heuristic
+ * hint) and routes it according to `BLOK_MAPPER_MODE`:
+ *
+ * - `"warn"` (default) — log via `ctx.logger.logLevel("warn", ...)`,
+ *   pass through the original string. Backward-compatible diagnostics.
+ * - `"strict"` — throw the error, fail the step fast. **Recommended
+ *   for production.**
+ * - `"silent"` — full suppression. Tests / opt-out only.
+ *
+ * ## Bug fixes shipped alongside the diagnostic upgrade (v0.3.x)
+ *
+ * - **Falsy values now preserved** — `_.get(data, key) || runJs(...)`
+ *   used to fall through to `runJs` when the lookup returned `0`,
+ *   `false`, `null`, or `""` (all valid values incorrectly treated
+ *   as missing). Now uses an explicit `=== undefined` check.
+ * - **Object interpolation now JSON-encodes** — `value as string`
+ *   used to produce `"[object Object]"` for object values. Now
+ *   round-trips via `JSON.stringify`.
+ * - **`js/` prefix stripping** uses `slice(3)` instead of
+ *   `replace("js/", "")` (the latter only strips the FIRST
+ *   occurrence — fragile if the expression itself contained `js/`).
+ */
+/**
+ * How the Mapper reacts to expression resolution failures. Read from
+ * the `BLOK_MAPPER_MODE` env var at every call (no caching) so unit
+ * tests can flip the mode between cases.
+ */
+export type MapperMode = "warn" | "strict" | "silent";
 declare class Mapper {
+    /**
+     * Walk an object recursively, resolving every string value via
+     * `replaceString`. Mutates in place. Used by `NodeBase.process` to
+     * resolve a step's `inputs` against the live `ctx` before the
+     * step runs.
+     *
+     * Object/array values are recursed into; primitive non-string
+     * values are left untouched. Null values are NOT recursed (avoids
+     * a TypeError on `for (const k in null)`).
+     */
     replaceObjectStrings(obj: ParamsDictionary, ctx: Context, data: ParamsDictionary): void;
-    replaceString: (strData: string, ctx: Context, data: ParamsDictionary) => string;
-    private runJs;
+    /**
+     * Resolve a single string. Returns `unknown` because a `js/...`
+     * expression may yield any value (number, object, array, etc.) —
+     * type fidelity is preserved across the resolver boundary.
+     *
+     * Pre-v0.3.x return was typed as `string` via `as string` cast
+     * which was a type lie; downstream consumers received the actual
+     * runtime value but couldn't see it through the type system.
+     */
+    replaceString: (strData: string, ctx: Context, data: ParamsDictionary) => unknown;
+    /**
+     * Resolve a `${path}` expression. Lodash lookup first; JS-eval
+     * fallback when the path is not in `data`. Returns the resolved
+     * value OR the failure sentinel.
+     */
+    private resolveTemplateExpression;
+    /**
+     * Evaluate a `js/...` full-string expression. Returns whatever the
+     * expression produces (any type), or — in warn/silent mode on
+     * failure — the original literal `js/...` string.
+     *
+     * Strict-mode failures throw `MapperResolutionError`.
+     */
     private jsMapper;
+    /**
+     * Apply the configured mode (`BLOK_MAPPER_MODE`) to a resolution
+     * failure. In strict mode, the error escapes here and propagates
+     * up through `replaceString` → `NodeBase.blueprintMapper` →
+     * `NodeBase.process` → step error envelope.
+     */
+    private handleResolutionError;
+    /**
+     * Sandboxed JS evaluation. Compiles the expression as a function
+     * body returning the expression value; binds `ctx`, `data`, `func`,
+     * `vars` as positional arguments; runs in `"use strict"` mode.
+     *
+     * Throws on any evaluation error (typo, undefined access, syntax,
+     * unknown identifier). Callers wrap in try/catch and translate to
+     * `MapperResolutionError`.
+     *
+     * Public via the prototype but documented as internal — the only
+     * supported call sites are inside this class.
+     */
+    private runJs;
 }
 declare const _default: Mapper;
 export default _default;