@c9up/inker 0.1.7 → 0.1.9

package/dist/renderNode.js

@@ -1,4 +1,4 @@
-import { EDGE_GLOBALS, htmlAttrs } from "./globals.js";
+import { htmlAttrs, INKER_GLOBALS } from "./globals.js";
 import { InkerRenderError } from "./InkerRenderError.js";
 import { SafeString } from "./SafeString.js";
 // ---- HTML escaping — the 8 characters inker escapes in `{{ }}` (Rust escape.rs) ----
@@ -40,6 +40,14 @@ const SANDBOX_SHADOW = Object.freeze({
 // Compile-once cache: expression source → a JS fn evaluating it with helpers +
 // scope in scope (`with` — a `new Function` body is non-strict).
 const exprCache = new Map();
+/** `await` as a keyword, not as part of an identifier (`awaited`, `myAwait`). */
+const AWAIT_RE = /(^|[^\w$.])await[\s(]/;
+const AsyncFunction = Object.getPrototypeOf(async () => { }).constructor;
+function isThenable(value) {
+    return ((typeof value === "object" || typeof value === "function") &&
+        value !== null &&
+        typeof Reflect.get(value, "then") === "function");
+}
 function compileExpr(source) {
     const cached = exprCache.get(source);
     if (cached !== undefined)
@@ -50,7 +58,12 @@ function compileExpr(source) {
         // V8 closure (Edge model); the source comes from `.inker` files, not user
         // input, so this is the same trust level as the rest of the app's code.
         // `$g` (the global shadow) is outermost, then helpers `$h`, then scope `$s`.
-        const compiled = new Function("$g", "$h", "$s", `with($g){ with($h){ with($s){ return (${source}); } } }`);
+        // An expression using `await` has to be compiled as an ASYNC function —
+        // `await` is a syntax error anywhere else — and then returns a promise
+        // the walker suspends on. `with` is legal in both (a `new Function` body
+        // is non-strict), so the scope chain is identical either way.
+        const Ctor = AWAIT_RE.test(source) ? AsyncFunction : Function;
+        const compiled = new Ctor("$g", "$h", "$s", `with($g){ with($h){ with($s){ return (${source}); } } }`);
         fn = (s, h) => compiled(SANDBOX_SHADOW, h, s);
     }
     catch (cause) {
@@ -78,6 +91,51 @@ function evalExpr(source, scope, helpers, pos) {
         throw new InkerRenderError(code, msg, { line: pos?.line, column: pos?.column }, { cause });
     }
 }
+/** Evaluate an expression, suspending the walk if it produced a promise. */
+function* evalStep(source, scope, helpers, pos) {
+    const value = evalExpr(source, scope, helpers, pos);
+    return isThenable(value) ? yield value : value;
+}
+/**
+ * Run a walk to completion.
+ *
+ * Returns the rendered string when the template never suspended, and a promise
+ * when it did — which is what lets one walker serve both `renderString` (sync)
+ * and `render` (async) without a second copy to keep in step. Adonis reaches
+ * the same place with two compilers; parsing in Rust and walking the AST, this
+ * is the shape that fits.
+ */
+/**
+ * Run a walk that must finish synchronously — a custom tag's `compile` and the
+ * sync render entry points are plain callbacks with nowhere to await. Suspending
+ * there is an authoring error, reported as one rather than leaking a promise
+ * into the output.
+ */
+function driveSync(step, out, what) {
+    const next = step.next();
+    while (!next.done) {
+        step.return(undefined);
+        throw new InkerRenderError("E_INKER_ASYNC_NOT_SUPPORTED", `${what} cannot use \`await\` — it renders synchronously`);
+    }
+    return out.join("");
+}
+function drive(step, out) {
+    let next = step.next();
+    while (!next.done) {
+        const pending = next.value;
+        if (!isThenable(pending)) {
+            next = step.next(pending);
+            continue;
+        }
+        return (async () => {
+            let cur = step.next(await pending);
+            while (!cur.done)
+                cur = step.next(await cur.value);
+            return out.join("");
+        })();
+    }
+    return out.join("");
+}
 // ---- @let destructuring (62-2 Edge parity): `@let({ a, b } = obj)` ----
 //
 // Like Edge (which compiles the pattern with a real JS parser), the Rust parser
@@ -163,34 +221,97 @@ export function normalizePartialKey(name) {
 function isRecord(v) {
     return v !== null && typeof v === "object" && !Array.isArray(v);
 }
+/**
+ * Derive a nested scope frame from `parent`. Frames CHAIN through the prototype
+ * rather than flattening with a spread, which is what lets `@assign` reach the
+ * frame that actually owns a binding: `@let(total = 0)` outside a loop and
+ * `@assign(total = total + 1)` inside it must hit the same slot, and a spread
+ * copy would strand the write on a per-iteration duplicate. `with()` reads walk
+ * the chain, so lookup is unchanged.
+ *
+ * `defineProperty` rather than assignment: a `__proto__` key would otherwise
+ * invoke the setter and re-point the chain instead of adding a binding. Binding
+ * names are validated in Rust, so this is depth, not the only guard.
+ */
+function childScope(parent, bindings) {
+    const frame = Object.create(parent);
+    for (const key of Object.keys(bindings)) {
+        Object.defineProperty(frame, key, {
+            value: bindings[key],
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    return frame;
+}
+/** A plain identifier target for `@assign`, as opposed to a member path. */
+const BARE_IDENT_RE = /^[A-Za-z_$][\w$]*$/;
+/** Keys `@inject` refuses to copy into `$context`. */
+const PROTO_KEYS = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/**
+ * The stack store for this render. It is created by the composer (one per
+ * `render()`, shared by body, sections and layout) — a missing one means a
+ * stack tag was reached through a code path that never set one up, which is a
+ * wiring bug, not an authoring mistake.
+ */
+function requireStacks(ctx, tag, pos) {
+    if (ctx.stacks === undefined) {
+        throw new InkerRenderError("E_INKER_INVALID_EXPRESSION", `${tag} used in a render with no stack store`, { line: pos.line, column: pos.column });
+    }
+    return ctx.stacks;
+}
+/** Find the frame in the scope chain that OWNS `name`, or null if none does. */
+function ownerFrame(scope, name) {
+    let frame = scope;
+    while (frame !== null) {
+        if (Object.hasOwn(frame, name))
+            return frame;
+        const parent = Object.getPrototypeOf(frame);
+        frame = parent;
+    }
+    return null;
+}
 // ---- The walker ----
 /** Render a list of sibling nodes, threading `@let` bindings forward. */
-function renderNodes(nodes, data, helpers, ctx, out) {
+function* renderNodes(nodes, data, helpers, ctx, out) {
     let scope = data;
     for (const node of nodes) {
         if (node.type === "Let") {
+            // `@let` short-circuits `renderNode`, so its own line has to be
+            // stamped here or the binding would evaluate under the previous
+            // node's `$lineNumber`.
+            if (node.line !== undefined)
+                helpers.$lineNumber = node.line;
             if (node.destructure) {
-                scope = {
-                    ...scope,
-                    ...evalLetDestructure(node.name, node.source, node.names ?? [], scope, helpers, node),
-                };
+                scope = childScope(scope, evalLetDestructure(node.name, node.source, node.names ?? [], scope, helpers, node));
             }
             else {
-                const value = evalExpr(node.source, scope, helpers, node);
-                scope = { ...scope, [node.name]: value };
+                const value = yield* evalStep(node.source, scope, helpers, node);
+                scope = childScope(scope, { [node.name]: value });
             }
             continue;
         }
-        renderNode(node, scope, helpers, ctx, out);
+        yield* renderNode(node, scope, helpers, ctx, out);
     }
 }
-function renderNode(node, scope, helpers, ctx, out) {
+function* renderNode(node, scope, helpers, ctx, out) {
+    // Edge emits line tracking into the compiled template, which is what makes
+    // `$lineNumber` readable from a template. Walking instead, the walker is the
+    // only place that knows — one write per node, in the layer under the render
+    // data so a caller's own `$lineNumber` key still wins.
+    if ("line" in node)
+        helpers.$lineNumber = node.line;
     switch (node.type) {
         case "Text":
             out.push(node.value);
             return;
         case "Interpolation": {
-            const v = evalExpr(node.source, scope, helpers, node);
+            const v = yield* evalStep(node.source, scope, helpers, node);
             if (v instanceof SafeString) {
                 out.push(v.value);
             }
@@ -206,23 +327,23 @@ function renderNode(node, scope, helpers, ctx, out) {
             return;
         }
         case "If": {
-            const v = evalExpr(node.condition.source, scope, helpers, node);
+            const v = yield* evalStep(node.condition.source, scope, helpers, node);
             if (v) {
-                renderNodes(node.then_nodes, scope, helpers, ctx, out);
+                yield* renderNodes(node.then_nodes, scope, helpers, ctx, out);
             }
             else if (node.else_nodes) {
-                renderNodes(node.else_nodes, scope, helpers, ctx, out);
+                yield* renderNodes(node.else_nodes, scope, helpers, ctx, out);
             }
             return;
         }
         case "Each":
-            renderEach(node, scope, helpers, ctx, out);
+            yield* renderEach(node, scope, helpers, ctx, out);
             return;
         case "Slot": {
-            if (ctx.slots?.has(node.name)) {
-                const html = ctx.slots.get(node.name);
-                if (html !== undefined)
-                    out.push(html);
+            const slot = ctx.slots?.get(node.name);
+            if (slot !== undefined) {
+                const html = slot();
+                out.push(isThenable(html) ? String(yield html) : html);
             }
             else if (node.name === "body" && ctx.bodyHtml !== undefined) {
                 out.push(ctx.bodyHtml);
@@ -236,11 +357,11 @@ function renderNode(node, scope, helpers, ctx, out) {
             if (partial === undefined) {
                 throw new InkerRenderError("E_INKER_DISK_REQUIRED", `@include('${node.name}') — partial not loaded (composer must preload it)`);
             }
-            renderNodes(partial, scope, helpers, ctx, out);
+            yield* renderNodes(partial, scope, helpers, ctx, out);
             return;
         }
         case "Component":
-            renderComponent(node, scope, helpers, ctx, out);
+            yield* renderComponent(node, scope, helpers, ctx, out);
             return;
         case "Section": {
             // In a layout, a `@section('name')` is a yield: inject the child's
@@ -251,7 +372,7 @@ function renderNode(node, scope, helpers, ctx, out) {
                 out.push(filled);
             }
             else {
-                renderNodes(node.body_nodes, scope, helpers, ctx, out);
+                yield* renderNodes(node.body_nodes, scope, helpers, ctx, out);
             }
             return;
         }
@@ -262,11 +383,11 @@ function renderNode(node, scope, helpers, ctx, out) {
             return;
         case "Eval":
             // Evaluate for side effects (e.g. a helper call); emit nothing.
-            evalExpr(node.source, scope, helpers, node);
+            yield* evalStep(node.source, scope, helpers, node);
             return;
         case "Dump": {
             // Pretty-print the value for debugging (Edge `@dump`).
-            const value = evalExpr(node.source, scope, helpers, node);
+            const value = yield* evalStep(node.source, scope, helpers, node);
             let json;
             try {
                 json = JSON.stringify(value, null, 2) ?? String(value);
@@ -275,6 +396,111 @@ function renderNode(node, scope, helpers, ctx, out) {
                 json = String(value);
             }
             out.push(`<pre class="inker-dump">${escapeHtml(json)}</pre>`);
+            // `@dd` — dump and die. The dump is already in `out`, but the render
+            // is abandoned, so it is carried on the error for the caller to show.
+            if (node.die) {
+                throw new InkerRenderError("E_INKER_DUMP_DIE", `@dd(${node.source}) stopped the render:\n${json}`, { line: node.line, column: node.column, expression: node.source });
+            }
+            return;
+        }
+        case "Assign": {
+            // `target` is `<lhs> <operator>`; splitting them in Rust is what lets a
+            // bare identifier be written back to the frame that owns it.
+            const opStart = node.target.lastIndexOf(" ");
+            const lhs = node.target.slice(0, opStart);
+            const operator = node.target.slice(opStart + 1);
+            if (BARE_IDENT_RE.test(lhs)) {
+                // Compute in the reading scope, then store in the OWNING frame —
+                // `with(){ x = … }` would create a shadowing copy on the innermost
+                // frame instead, so a loop's writes would vanish at each iteration.
+                const owner = ownerFrame(scope, lhs);
+                if (owner === null) {
+                    throw new InkerRenderError("E_INKER_UNKNOWN_IDENTIFIER", `@assign cannot assign to '${lhs}' — no such binding in scope (use @let to declare it)`, { line: node.line, column: node.column });
+                }
+                const rhs = operator === "="
+                    ? node.source
+                    : `(${lhs}) ${operator.slice(0, -1)} (${node.source})`;
+                const value = yield* evalStep(rhs, scope, helpers, node);
+                Object.defineProperty(owner, lhs, {
+                    value,
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+            else {
+                // A member path (`user.name`, `rows[0].qty`) mutates the object it
+                // points at, so evaluating the assignment is the assignment.
+                yield* evalStep(`${lhs} ${operator} (${node.source})`, scope, helpers, node);
+            }
+            return;
+        }
+        case "Inject": {
+            if (ctx.context === undefined) {
+                throw new InkerRenderError("E_INKER_INVALID_EXPRESSION", "@inject can only be used inside a component — there is no $context to write to at the top level", { line: node.line, column: node.column });
+            }
+            const value = yield* evalStep(node.source, scope, helpers, node);
+            if (!isRecord(value)) {
+                throw new InkerRenderError("E_INKER_INVALID_EXPRESSION", `@inject(${node.source}) expects an object, got ${value === null ? "null" : typeof value}`, { line: node.line, column: node.column });
+            }
+            for (const key of Object.keys(value)) {
+                if (PROTO_KEYS.has(key))
+                    continue;
+                ctx.context[key] = value[key];
+            }
+            return;
+        }
+        case "Debugger":
+            // Edge compiles `@debugger` to a `debugger` statement; with the AST
+            // walked rather than compiled, the breakpoint lands here — still under
+            // `node --inspect`, and `node` / `scope` / `ctx` are the template's own
+            // state at that point, which is what the author wants to inspect.
+            // biome-ignore lint/suspicious/noDebugger: the statement IS the feature — `@debugger` has no other implementation.
+            debugger;
+            return;
+        case "NewError": {
+            // `@newError(message, filename?, line?, col?)` — the position args let a
+            // component blame its CALLER (`$caller.line`) rather than itself.
+            const parts = yield* evalStep(`[${node.source}]`, scope, helpers, node);
+            const [message, filename, line, column] = Array.isArray(parts)
+                ? parts
+                : [parts];
+            throw new InkerRenderError("E_INKER_TEMPLATE_ERROR", typeof message === "string" ? message : String(message), {
+                line: typeof line === "number" ? line : node.line,
+                column: typeof column === "number" ? column : node.column,
+                templateName: typeof filename === "string" ? filename : ctx.templateName,
+            });
+        }
+        case "Stack": {
+            const name = yield* evalStep(node.source, scope, helpers, node);
+            if (typeof name !== "string") {
+                throw new InkerRenderError("E_INKER_INVALID_EXPRESSION", `@stack(${node.source}) expects a string name, got ${typeof name}`, { line: node.line, column: node.column });
+            }
+            out.push(requireStacks(ctx, "@stack", node).create(name));
+            return;
+        }
+        case "PushTo": {
+            const name = yield* evalStep(node.source, scope, helpers, node);
+            if (typeof name !== "string") {
+                throw new InkerRenderError("E_INKER_INVALID_EXPRESSION", `@${node.once ? "pushOnceTo" : "pushTo"}(${node.source}) expects a string name, got ${typeof name}`, { line: node.line, column: node.column });
+            }
+            const stacks = requireStacks(ctx, `@${node.once ? "pushOnceTo" : "pushTo"}`, node);
+            if (node.once) {
+                // The source id is the CALL SITE, so a component used ten times
+                // contributes its script tag once — which is the tag's whole point.
+                // Rendering the body is skipped entirely on a repeat.
+                const sourceId = `${ctx.templateName ?? "?"}:${node.line}:${node.column}`;
+                if (stacks.hasSource(name, sourceId))
+                    return;
+                const body = [];
+                yield* renderNodes(node.body_nodes, scope, helpers, ctx, body);
+                stacks.pushOnceTo(name, sourceId, body.join(""));
+            }
+            else {
+                const body = [];
+                yield* renderNodes(node.body_nodes, scope, helpers, ctx, body);
+                stacks.pushTo(name, body.join(""));
+            }
             return;
         }
         case "CustomTag": {
@@ -289,8 +515,23 @@ function renderNode(node, scope, helpers, ctx, out) {
             }
             const token = {
                 properties: { jsArg },
-                filename: "",
+                filename: ctx.templateName ?? "",
                 loc: { start: { line: node.line ?? 0, col: node.column ?? 0 } },
+                // Rendered on demand, in the tag's own scope. A block tag that
+                // discards its body (a `@cache` miss, a permission check) never
+                // pays for it, and one that wraps its body calls this once.
+                // Like a slot: a string when the body finished synchronously, a
+                // promise when it suspended — so a tag that awaits its own check
+                // can `await token.renderBody()`.
+                renderBody: (locals) => {
+                    const bodyOut = [];
+                    const bodyScope = locals === undefined ? scope : childScope(scope, { ...locals });
+                    return drive(renderNodes(node.body_nodes, bodyScope, helpers, ctx, bodyOut), bodyOut);
+                },
+                evaluate: (expression) => evalExpr(expression, scope, helpers, {
+                    line: node.line,
+                    column: node.column,
+                }),
             };
             const buffer = {
                 writeRaw: (text) => {
@@ -301,6 +542,9 @@ function renderNode(node, scope, helpers, ctx, out) {
                         line,
                         column: node.column,
                     });
+                    if (isThenable(v)) {
+                        throw new InkerRenderError("E_INKER_ASYNC_NOT_SUPPORTED", `@${node.name} cannot output an awaited expression — a tag renders synchronously`, { line, column: node.column });
+                    }
                     if (v instanceof SafeString) {
                         out.push(v.value);
                     }
@@ -315,7 +559,11 @@ function renderNode(node, scope, helpers, ctx, out) {
                     }
                 },
             };
-            tag.compile(TAG_PARSER, buffer, token);
+            const compiled = tag.compile(TAG_PARSER, buffer, token);
+            // An async tag suspends the walk here, so everything it wrote lands
+            // in order and nothing else renders in between.
+            if (isThenable(compiled))
+                yield compiled;
             return;
         }
         case "Layout":
@@ -326,8 +574,8 @@ function renderNode(node, scope, helpers, ctx, out) {
             throw new InkerRenderError("E_INKER_INVALID_EXPRESSION", `node type '${node.type}' is not yet handled by the Node renderer`);
     }
 }
-function renderEach(node, scope, helpers, ctx, out) {
-    const iterable = evalExpr(node.iterable_source, scope, helpers, node);
+function* renderEach(node, scope, helpers, ctx, out) {
+    const iterable = yield* evalStep(node.iterable_source, scope, helpers, node);
     // A `[k, v]` destructured binding means "each element is a pair" ONLY when
     // iterating an array of pairs; over an object/Map/Set it binds key + value.
     // Decide by the ITERABLE kind, never by the element shape (an object whose
@@ -365,31 +613,30 @@ function renderEach(node, scope, helpers, ctx, out) {
     }
     if (entries.length === 0) {
         if (node.else_nodes)
-            renderNodes(node.else_nodes, scope, helpers, ctx, out);
+            yield* renderNodes(node.else_nodes, scope, helpers, ctx, out);
         return;
     }
     const binding = node.binding;
     for (const [value, key] of entries) {
-        let childScope;
+        let bindings;
         if ("Single" in binding) {
-            childScope = { ...scope, [binding.Single]: value };
+            bindings = { [binding.Single]: value };
         }
         else if ("Destructured" in binding) {
             const [kName, vName] = binding.Destructured;
             // array-of-pairs: `value` is `[k, v]`; object/Map/Set: key + value.
-            childScope =
+            bindings =
                 arrayOfPairs && Array.isArray(value)
-                    ? { ...scope, [kName]: value[0], [vName]: value[1] }
-                    : { ...scope, [kName]: key, [vName]: value };
+                    ? { [kName]: value[0], [vName]: value[1] }
+                    : { [kName]: key, [vName]: value };
         }
         else {
-            childScope = {
-                ...scope,
+            bindings = {
                 [binding.Indexed.item]: value,
                 [binding.Indexed.index]: key,
             };
         }
-        renderNodes(node.body_nodes, childScope, helpers, ctx, out);
+        yield* renderNodes(node.body_nodes, childScope(scope, bindings), helpers, ctx, out);
     }
 }
 function mergeProps(values, defaults) {
@@ -416,10 +663,16 @@ function makeProps(values) {
             .map((k) => [k, values[k]]))),
         except: (keys) => makeProps(Object.fromEntries(Object.entries(values).filter(([k]) => !keys.includes(k)))),
         merge: (defaults) => makeProps(mergeProps(values, defaults)),
+        // Conditional merges (Edge `mergeIf` / `mergeUnless`). The condition is
+        // whatever the template hands over, so it is read for truthiness rather
+        // than required to be a boolean — `$props.mergeIf($props.get('x'), …)`
+        // is the documented usage and `get` returns `unknown`.
+        mergeIf: (condition, defaults) => condition ? makeProps(mergeProps(values, defaults)) : makeProps(values),
+        mergeUnless: (condition, defaults) => condition ? makeProps(values) : makeProps(mergeProps(values, defaults)),
         toAttrs: () => htmlAttrs(values),
     };
 }
-function renderComponent(node, scope, helpers, ctx, out) {
+function* renderComponent(node, scope, helpers, ctx, out) {
     const template = ctx.components?.get(normalizePartialKey(node.name));
     if (template === undefined) {
         throw new InkerRenderError("E_INKER_DISK_REQUIRED", `@component('${node.name}') — component not loaded (composer must preload it)`);
@@ -428,17 +681,35 @@ function renderComponent(node, scope, helpers, ctx, out) {
     // (props); the component does not inherit the caller's data.
     const props = {};
     for (const arg of node.args)
-        props[arg.key] = evalExpr(arg.source, scope, helpers);
+        props[arg.key] = yield* evalStep(arg.source, scope, helpers);
+    // `$context` — state an enclosing component provided via `@inject`, which
+    // this component may extend for its own descendants. Each level gets its OWN
+    // copy (Edge does the same), so a nested `@inject` never leaks back up to a
+    // sibling subtree. Null-proto: context keys come from template authors.
+    const $context = Object.assign(Object.create(null), ctx.context);
     // Slot content renders in the CALLER scope; `{{> name }}` in the component
     // injects it. The default (`body`) slot is the block body outside `@slot()`.
+    //
+    // Rendering is DEFERRED to first use: the component's own body runs first,
+    // and only then does a slot render — which is the whole point of `@inject`,
+    // since the values it publishes must exist before the slot's nested
+    // components look them up. The slot sees this component's `$context` while
+    // keeping the caller's scope, exactly Edge's `state.$slots.$context`.
+    const slotCtx = { ...ctx, context: $context };
+    // A slot renders on use, and its body may itself await — so the thunk hands
+    // back a string when it finished synchronously and a promise when it did
+    // not. `{{{ $slots.main() }}}` keeps working for the ordinary case, and an
+    // awaiting body is reached with `{{{ await $slots.main() }}}`, as in Adonis.
+    const renderSlot = (nodes) => {
+        return () => {
+            const slotOut = [];
+            return drive(renderNodes(nodes, scope, helpers, slotCtx, slotOut), slotOut);
+        };
+    };
     const slots = new Map();
-    const bodyOut = [];
-    renderNodes(node.body_nodes, scope, helpers, ctx, bodyOut);
-    slots.set("body", bodyOut.join(""));
+    slots.set("body", renderSlot(node.body_nodes));
     for (const named of node.named_slots) {
-        const slotOut = [];
-        renderNodes(named.nodes, scope, helpers, ctx, slotOut);
-        slots.set(named.name, slotOut.join(""));
+        slots.set(named.name, renderSlot(named.nodes));
     }
     // `$slots.main()` renders the default (body) slot; `$slots.<name>()` a named
     // slot; `$slots.<name>` is undefined when absent (so `@if($slots.footer)`
@@ -448,32 +719,79 @@ function renderComponent(node, scope, helpers, ctx, out) {
     // then assigns an OWN `__proto__` key instead of mutating the object's
     // prototype — no prototype pollution.
     const $slots = Object.create(null);
-    $slots.main = () => new SafeString(slots.get("body") ?? "");
-    for (const [name, html] of slots) {
+    const asSafe = (html) => isThenable(html)
+        ? Promise.resolve(html).then((v) => new SafeString(v))
+        : new SafeString(html);
+    $slots.main = () => asSafe(slots.get("body")?.() ?? "");
+    for (const [name, render] of slots) {
         if (name === "body")
             continue;
-        $slots[name] = () => new SafeString(html);
+        $slots[name] = () => asSafe(render());
     }
-    const componentScope = { ...props, $props: makeProps(props), $slots };
+    // `$caller` describes where the component was invoked from (Edge parity).
+    // Inker carries line/column on every node; `template` is the caller's name
+    // when the composer knew it. Frozen — it is diagnostic data, not a channel
+    // back into the caller.
+    const $caller = Object.freeze({
+        line: node.line,
+        col: node.column,
+        // Edge names this `filename` and puts the resolved absolute path in it.
+        // INKER DEVIATION (named): the LOGICAL template name goes here instead —
+        // it is what `render()` was called with and what an error should quote.
+        // The key keeps Edge's name so `@newError(msg, $caller.filename, …)`,
+        // straight out of the Edge docs, works unchanged.
+        filename: ctx.templateName,
+    });
+    const componentScope = {
+        ...props,
+        $props: makeProps(props),
+        $slots,
+        $caller,
+        $context,
+        // The component's OWN name (Edge `$filename`), as `$caller.filename` is
+        // the invoking template's.
+        $filename: node.name,
+    };
     const subCtx = {
         partials: ctx.partials,
         components: ctx.components,
         tags: ctx.tags,
+        stacks: ctx.stacks,
         slots,
+        context: $context,
+        // A component nested in THIS one must see this component as its caller;
+        // without it `$caller.filename` was undefined one level down.
+        templateName: node.name,
     };
-    renderNodes(template, componentScope, helpers, subCtx, out);
+    yield* renderNodes(template, componentScope, helpers, subCtx, out);
+}
+/** Build the helper layer and start a walk over `nodes`. */
+function startWalk(nodes, data, helpers, ctx, out) {
+    // Inker's built-in globals are always in scope; registered helpers overlay them.
+    const helperObj = { ...INKER_GLOBALS };
+    for (const [name, fn] of helpers)
+        helperObj[name] = fn;
+    // `$filename` sits in the helper layer, UNDER the render data, so a template
+    // can read the name it is being rendered as without shadowing a caller's
+    // own `$filename` key (Adonis scopes it the same way, as a function local).
+    helperObj.$filename = ctx.templateName;
+    return renderNodes(nodes, isRecord(data) ? data : {}, helperObj, ctx, out);
 }
 /**
  * Render a parsed template's node list against `data`, with `helpers` in scope.
  * Layout / partial / component composition is layered on top by the caller.
+ *
+ * SYNCHRONOUS: an expression using `await` raises rather than leaking a promise
+ * into the output. `renderNodeTreeAsync` is the awaiting counterpart, which is
+ * the split Adonis draws between `renderSync` and `render`.
  */
 export function renderNodeTree(nodes, data, helpers, ctx = {}) {
-    // Edge-core globals are always in scope; registered helpers overlay them.
-    const helperObj = { ...EDGE_GLOBALS };
-    for (const [name, fn] of helpers)
-        helperObj[name] = fn;
     const out = [];
-    renderNodes(nodes, isRecord(data) ? data : {}, helperObj, ctx, out);
-    return out.join("");
+    return driveSync(startWalk(nodes, data, helpers, ctx, out), out, "a synchronous render");
+}
+/** Render a node list, awaiting any expression that needs it. */
+export async function renderNodeTreeAsync(nodes, data, helpers, ctx = {}) {
+    const out = [];
+    return drive(startWalk(nodes, data, helpers, ctx, out), out);
 }
 //# sourceMappingURL=renderNode.js.map