@c9up/inker 0.1.6 → 0.1.7

package/dist/Templates.js

@@ -1,10 +1,11 @@
 import * as fs from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import * as path from "node:path";
+import { EDGE_GLOBAL_NAMES } from "./globals.js";
 import { InkerRenderError } from "./InkerRenderError.js";
 import { PROTOTYPE_POLLUTION_KEYS, RESERVED_BINDING_NAMES, } from "./identifierGuards.js";
 import { getNative, napiThrowToInker, } from "./loadNapi.js";
-import { SafeString } from "./SafeString.js";
+import { collectSections, renderNodeTree, } from "./renderNode.js";
 const HELPER_NAME_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 // P13 — Windows-reserved device basenames. Refused on every platform for
 // portability: a template named `con.inker` would resolve to the Windows
@@ -38,6 +39,36 @@ const VALID_CACHE_MODES = new Set([
     "mtime",
     "never",
 ]);
+// Built-in block/directive keywords a custom tag may not shadow (registerTag).
+// The parser already ignores these as custom tags; rejecting them here makes the
+// collision loud instead of silently inert.
+// MUST mirror the lexer's `is_block_keyword` set (crates/inker-engine/src/lex.rs)
+// exactly — a name the lexer treats as a built-in but that is missing here would
+// pass registration and then sit silently inert (its `@name` never becomes a
+// CustomTag node), the very failure this blocklist exists to make loud.
+const RESERVED_TAG_NAMES = new Set([
+    "if",
+    "elseif",
+    "else",
+    "endif",
+    "unless",
+    "endunless",
+    "each",
+    "endeach",
+    "let",
+    "layout",
+    "include",
+    "includeIf",
+    "component",
+    "endcomponent",
+    "slot",
+    "endslot",
+    "section",
+    "endsection",
+    "super",
+    "eval",
+    "dump",
+]);
 function isErrnoException(value) {
     return (value instanceof Error && typeof Reflect.get(value, "code") === "string");
 }
@@ -45,7 +76,7 @@ function normalizePartialKey(name) {
     let key = name;
     while (key.startsWith("./"))
         key = key.slice(2);
-    // T2: refuse an empty key — `{% include './' %}` would otherwise collide
+    // T2: refuse an empty key — `@include('./')` would otherwise collide
     // with the synthetic `<root>/.inker` dotfile path and silently include
     // (or misreport) an unrelated file. validateName lets a literal `./`
     // through (no `..`, no NUL, no backslash, length > 0), so the assertion
@@ -98,7 +129,7 @@ function assertSafeCharacters(name) {
 /**
  * Reject absolute paths, `..` segments, backslashes, and Windows drive-letter
  * prefixes — each would bypass the lexical `path.join(root, …)` containment.
- * Mirrors parseBlockTag.validatePathName so `{% include %}` and the public
+ * Mirrors parseBlockTag.validatePathName so `@include()` and the public
  * Templates#render entrypoint agree.
  */
 function assertSafePathShape(name) {
@@ -114,6 +145,15 @@ function assertSafePathShape(name) {
     if (/^[A-Za-z]:/.test(name)) {
         throw new InkerRenderError("E_INKER_INVALID_PATH", `Template name cannot start with a Windows drive-letter prefix; got ${JSON.stringify(name)}`, { templateName: name });
     }
+    // A bare (post-`#splitDisk`) template name never legitimately contains `:`.
+    // The drive-letter guard above only catches a leading `[A-Za-z]:`; a residual
+    // separator such as `1::b` (digit-led, so it slips that guard) would otherwise
+    // reach `path.join` and, on Windows NTFS, be reinterpreted as an alternate-
+    // data-stream reference — a cross-platform resolution divergence. `:` is
+    // already reserved as the `::` disk separator, so forbid it outright here.
+    if (name.includes(":")) {
+        throw new InkerRenderError("E_INKER_INVALID_PATH", `Template name cannot contain ':' characters; got ${JSON.stringify(name)}`, { templateName: name });
+    }
 }
 /**
  * Refuse Windows-reserved basenames (`con`, `prn`, `aux`, `nul`, `com1`-`com9`,
@@ -129,6 +169,19 @@ function assertNotReservedDeviceName(name) {
         }
     }
 }
+/**
+ * Validate a mount disk name (AdonisJS/Edge `edge.mount(name, …)` parity).
+ * A disk name is an identifier-shaped label, NOT a path: it must be non-empty
+ * and contain only `[A-Za-z0-9_-]`. This forbids `::` (the disk separator),
+ * `/` and `\` (path segments), `.`/`..` traversal, and control bytes — a disk
+ * name can never itself become a path component that widens containment.
+ */
+const DISK_NAME_RE = /^[A-Za-z0-9_-]+$/;
+function assertDiskName(diskName) {
+    if (typeof diskName !== "string" || !DISK_NAME_RE.test(diskName)) {
+        throw new InkerRenderError("E_INKER_INVALID_PATH", `Mount disk name must match ${DISK_NAME_RE} (identifier-shaped, no path separators); got ${JSON.stringify(diskName)}`, { templateName: typeof diskName === "string" ? diskName : undefined });
+    }
+}
 function assertContained(root, absPath, name) {
     // P12: case-sensitive `startsWith` breaks on APFS/HFS+/NTFS where
     // `realpath` canonicalises segment casing — a root like
@@ -356,7 +409,7 @@ function validateHelpers(rawHelpers) {
     if (!(helpers instanceof Map)) {
         throw new InkerRenderError("E_INKER_INVALID_PATH", `Templates.helpers must be a Map; got ${Object.prototype.toString.call(helpers).slice(8, -1)}`);
     }
-    const helperNames = new Set();
+    const helperNames = new Set(EDGE_GLOBAL_NAMES);
     for (const [key, value] of helpers) {
         // T3: validate the key is a string BEFORE handing it to
         // HELPER_NAME_RE.test(), which ToString-coerces and throws a raw
@@ -397,6 +450,18 @@ export class Templates {
     #cacheGeneration = 0;
     #helpers;
     #helperNames;
+    // Runtime-registered custom tags (Edge `registerTag`). Names here make the
+    // parser recognise `@<tagName>(jsArg)` as a `CustomTag` node; the tag's
+    // `compile` runs at render time. A LIVE map, like `#helpers` — but because
+    // tag names change how a template PARSES, registerTag() invalidates the cache.
+    #tags = new Map();
+    // Named template "disks" (AdonisJS/Edge `edge.mount(name, dir)` parity).
+    // The DEFAULT disk is `#root` (the constructor `root`), addressed by a bare
+    // `template` name; a NAMED disk is addressed as `name::template`. Each value
+    // is a canonicalised absolute root — containment (assertContained + the
+    // #loadAst symlink guard) is enforced against the disk's OWN root, never a
+    // shared one, so mounting a package's templates cannot widen traversal.
+    #disks = new Map();
     constructor(options) {
         this.#root = canonicalizeTemplatesRoot(options.root);
         const requested = options.cacheMode ?? "auto";
@@ -419,52 +484,160 @@ export class Templates {
         this.#helpers = helpers;
         this.#helperNames = helperNames;
     }
+    /**
+     * Mount a named templates "disk" (AdonisJS/Edge `edge.mount(name, dir)`
+     * parity). Templates in a mounted disk are addressed as `name::template`
+     * (including from `@layout()` / `@include()` / `@component()`
+     * references); a BARE `template` name always resolves against the default
+     * root, exactly like Edge. `dir` is canonicalised (absolute + realpath) the
+     * same way the constructor root is, so each disk carries its own containment
+     * boundary.
+     *
+     * Re-mounting a name to the SAME canonicalised root is an idempotent no-op;
+     * re-mounting to a DIFFERENT root throws `E_INKER_DISK_COLLISION` (call
+     * `unmount` first for an intentional replacement). This is a NAMED deviation
+     * from Edge's silent overwrite: this engine is shared process-wide and
+     * consumed by multiple integration packages, so an accidental disk-name
+     * clash must fail loud rather than silently clobber another package's
+     * containment boundary.
+     */
+    mount(diskName, dir) {
+        assertDiskName(diskName);
+        const root = canonicalizeTemplatesRoot(dir);
+        const existing = this.#disks.get(diskName);
+        if (existing !== undefined && existing !== root) {
+            throw new InkerRenderError("E_INKER_DISK_COLLISION", `Disk "${diskName}" is already mounted to "${existing}"; refusing to overwrite it with "${root}". Call unmount(${JSON.stringify(diskName)}) first to replace it.`);
+        }
+        this.#disks.set(diskName, root);
+    }
+    /**
+     * Unmount a named disk (AdonisJS/Edge `edge.unmount(name)` parity). No-op if
+     * the disk was never mounted. Does NOT clear the AST cache — cache keys are
+     * `(root, absPath)` pairs, so a later re-mount of a different directory
+     * resolves under a different root and cannot serve a stale entry, even when
+     * two directories canonicalise to overlapping absolute paths.
+     */
+    unmount(diskName) {
+        this.#disks.delete(diskName);
+    }
+    /**
+     * Register a custom tag (AdonisJS/Edge `edge.registerTag` parity). The `tag`
+     * definition — `{ tagName, block, seekable, compile(parser, buffer, token) }` —
+     * makes the parser recognise `@<tagName>(jsArg)` in every template and emit a
+     * `CustomTag` node. At render time inker calls `compile`, whose `buffer`
+     * writes the output (`writeRaw` for verbatim markup, `outputExpression` to
+     * evaluate a template expression) and whose `token.properties.jsArg` is the
+     * verbatim argument source, e.g. an `@svg('icon')` or `@time()` tag.
+     *
+     * INKER DEVIATION (named): Edge runs `compile` once at compilation (it emits
+     * JS); inker parses in Rust and renders by walking the JSON AST, so `compile`
+     * runs at RENDER time. Only inline tags (`block: false`) are supported for now.
+     *
+     * Because tag names change how a template PARSES, registering (or overwriting)
+     * a tag clears the AST cache — call `registerTag` during boot, before rendering.
+     */
+    registerTag(tag) {
+        const name = tag?.tagName;
+        if (typeof name !== "string" || !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+            throw new InkerRenderError("E_INKER_INVALID_PATH", `registerTag — tagName must be a valid identifier (letters, digits, underscore; not starting with a digit); got ${JSON.stringify(name)}`);
+        }
+        if (RESERVED_TAG_NAMES.has(name)) {
+            throw new InkerRenderError("E_INKER_INVALID_PATH", `registerTag({ tagName: '${name}' }) — '${name}' is a built-in inker directive and cannot be overridden`);
+        }
+        if (typeof tag.compile !== "function") {
+            throw new InkerRenderError("E_INKER_INVALID_PATH", `registerTag({ tagName: '${name}' }) — compile must be a function`);
+        }
+        if (tag.block === true) {
+            throw new InkerRenderError("E_INKER_INVALID_PATH", `registerTag({ tagName: '${name}' }) — block custom tags (@${name}…@end${name}) are not supported yet; register an inline tag (block: false)`);
+        }
+        this.#tags.set(name, tag);
+        // A new tag name changes parse output; drop any AST parsed without it.
+        this.clearCache();
+    }
+    /**
+     * Split an optionally-namespaced template name into its resolution root and
+     * bare (disk-relative) name. `name::path` → the mounted disk's root; a bare
+     * `path` → the default root. Unknown disk → loud E_INKER_INVALID_PATH.
+     */
+    #splitDisk(name) {
+        const sep = name.indexOf("::");
+        if (sep === -1)
+            return { root: this.#root, bare: name };
+        const disk = name.slice(0, sep);
+        const bare = name.slice(sep + 2);
+        const root = this.#disks.get(disk);
+        if (root === undefined) {
+            throw new InkerRenderError("E_INKER_INVALID_PATH", `Unknown templates disk '${disk}' in '${name}' — mount it with Templates#mount('${disk}', dir) first`, { templateName: name });
+        }
+        return { root, bare };
+    }
+    /**
+     * Resolve an (optionally `disk::`-prefixed) template name to its disk root,
+     * validated bare name, and absolute `.inker` path — with per-disk
+     * containment. `prefix` is prepended to the bare name AFTER the disk split
+     * (used for `components/` so `disk::button` → `<disk>/components/button`).
+     */
+    #resolveTemplateFile(name, prefix = "") {
+        const { root, bare } = this.#splitDisk(name);
+        const validated = validateName(`${prefix}${bare}`);
+        const absPath = path.join(root, `${validated}.inker`);
+        assertContained(root, absPath, validated);
+        return { root, validated, absPath };
+    }
     async render(name, data) {
-        const validated = validateName(name);
-        const absPath = path.join(this.#root, `${validated}.inker`);
-        assertContained(this.#root, absPath, validated);
-        const entryAst = await this.#loadAst(absPath, validated);
+        const { root, validated, absPath } = this.#resolveTemplateFile(name);
+        // Validate the data tree (rejects NaN / ±Infinity / out-of-range bigint /
+        // sparse holes / circular refs) — the Node renderer evaluates the ORIGINAL
+        // data in V8 (Maps/Sets intact), so `encodeData`'s result is discarded and
+        // only its guard side-effects are kept.
+        encodeData(data);
+        const entryAst = await this.#loadAst(absPath, validated, root);
         const composed = await this.#compose(entryAst, validated, absPath, new Set([absPath]));
-        const native = getNative();
-        const encoded = encodeData(data);
-        const partials = Object.fromEntries(composed.partialAsts);
-        const components = Object.fromEntries(composed.componentAsts);
-        // Body pass — collect helper invocations in render order, invoke them
-        // TS-side, then render consuming the resolved tape (ADR-007 as adapted
-        // for 55.1: collect→invoke→render, no V8 callback).
-        const bodyCtx = {
-            partials,
-            components,
-            bodyHtml: undefined,
-            templateName: validated,
-            templatePath: absPath,
-        };
-        const bodyTape = callNative(() => native.collectInvocations(composed.bodyAst, encoded, bodyCtx));
-        const bodyResolved = this.#invokeHelpers(bodyTape, validated, absPath);
-        const bodyHtml = callNative(() => native.renderAst(composed.bodyAst, encoded, bodyResolved, bodyCtx));
+        // Node renderer (62-2 pivot): convert the loaded AST handles to JSON node
+        // lists and evaluate every expression in Node's own V8 with the helpers in
+        // scope (Edge model — no tape, no QuickJS, no FFI).
+        const partials = new Map();
+        for (const [key, handle] of composed.partialAsts) {
+            partials.set(key, this.#astNodes(handle));
+        }
+        const components = new Map();
+        for (const [key, handle] of composed.componentAsts) {
+            components.set(key, this.#astNodes(handle));
+        }
+        const childNodes = this.#astNodes(composed.bodyAst);
+        const baseCtx = { partials, components, tags: this.#tags };
+        // No layout → render the child directly (`@section`s render inline).
         if (composed.layoutAst === undefined) {
-            return bodyHtml;
-        }
-        const layoutAst = composed.layoutAst;
-        const layoutName = composed.layoutName ?? validated;
-        const layoutPath = composed.layoutAbsPath ?? absPath;
-        // Layout collect ctx omits bodyHtml (slots carry no helpers); render ctx
-        // injects it. Both walk identically so the tape aligns.
-        const layoutTape = callNative(() => native.collectInvocations(layoutAst, encoded, {
-            partials,
-            components,
-            bodyHtml: undefined,
-            templateName: layoutName,
-            templatePath: layoutPath,
-        }));
-        const layoutResolved = this.#invokeHelpers(layoutTape, layoutName, layoutPath);
-        return callNative(() => native.renderAst(layoutAst, encoded, layoutResolved, {
-            partials,
-            components,
+            return renderNodeTree(childNodes, data, this.#helpers, baseCtx);
+        }
+        // With a layout: separate the child's `@section` fills from the default
+        // body, render each section (with `@super` = the layout's default for it),
+        // and inject them at the layout's matching yields (62-3).
+        const { sections: childSections, body: childBody } = collectSections(childNodes);
+        const bodyHtml = renderNodeTree(childBody, data, this.#helpers, baseCtx);
+        const layoutNodes = this.#astNodes(composed.layoutAst);
+        const { sections: layoutDefaults } = collectSections(layoutNodes);
+        const sections = new Map();
+        for (const [name, sectionNodes] of childSections) {
+            const layoutDefault = layoutDefaults.get(name);
+            const superHtml = layoutDefault !== undefined
+                ? renderNodeTree(layoutDefault, data, this.#helpers, baseCtx)
+                : "";
+            sections.set(name, renderNodeTree(sectionNodes, data, this.#helpers, {
+                ...baseCtx,
+                superHtml,
+            }));
+        }
+        return renderNodeTree(layoutNodes, data, this.#helpers, {
+            ...baseCtx,
             bodyHtml,
-            templateName: layoutName,
-            templatePath: layoutPath,
-        }));
+            sections,
+        });
+    }
+    /** Convert a parsed AST handle to its JSON node list (62-2 Node renderer). */
+    #astNodes(handle) {
+        const parsed = JSON.parse(getNative().astToJson(handle));
+        return parsed.nodes;
     }
     renderString(source, data) {
         // T4 + P15: strip ALL U+FEFF (BOM) characters, not just a leading one.
@@ -477,82 +650,34 @@ export class Templates {
             ? source.replace(//g, "")
             : source;
         const native = getNative();
-        const ast = callNative(() => native.parseTemplate(normalisedSource, [...this.#helperNames]));
+        const ast = callNative(() => native.parseTemplate(normalisedSource, [...this.#helperNames], [...this.#tags.keys()]));
         const info = ast.composeInfo;
-        // The Rust parser separates a leading `{% layout %}` into `ast.layout`
+        // The Rust parser separates a leading `@layout()` into `ast.layout`
         // (not a body node), so `firstDiskNode` won't surface it — check
         // `hasLayout` explicitly to preserve the renderString disk-required guard.
         if (info.hasLayout) {
-            throw new InkerRenderError("E_INKER_DISK_REQUIRED", `Templates#renderString cannot resolve {% layout '${info.layoutName ?? ""}' %} — use Templates#render(name, data) instead`);
+            throw new InkerRenderError("E_INKER_DISK_REQUIRED", `Templates#renderString cannot resolve @layout('${info.layoutName ?? ""}') — use Templates#render(name, data) instead`);
         }
         const disk = info.firstDiskNode;
         if (disk !== null && disk !== undefined) {
             if (disk.kind === "Layout") {
-                throw new InkerRenderError("E_INKER_DISK_REQUIRED", `Templates#renderString cannot resolve {% layout '${disk.name}' %} — use Templates#render(name, data) instead`);
+                throw new InkerRenderError("E_INKER_DISK_REQUIRED", `Templates#renderString cannot resolve @layout('${disk.name}') — use Templates#render(name, data) instead`);
             }
             if (disk.kind === "Partial") {
-                throw new InkerRenderError("E_INKER_DISK_REQUIRED", `Templates#renderString cannot resolve {% include '${disk.name}' %} — use Templates#render(name, data) instead`);
+                throw new InkerRenderError("E_INKER_DISK_REQUIRED", `Templates#renderString cannot resolve @include('${disk.name}') — use Templates#render(name, data) instead`);
             }
             if (disk.kind === "Component") {
-                throw new InkerRenderError("E_INKER_DISK_REQUIRED", `Templates#renderString cannot resolve {% component '${disk.name}' %} — use Templates#render(name, data) instead`);
+                throw new InkerRenderError("E_INKER_DISK_REQUIRED", `Templates#renderString cannot resolve @component('${disk.name}') — use Templates#render(name, data) instead`);
             }
             throw new InkerRenderError("E_INKER_DISK_REQUIRED", `Templates#renderString cannot use {{> ${disk.name} }} outside of a layout — the slot has no parent layout to inject into`);
         }
-        const ctx = {
-            partials: {},
-            components: {},
-            bodyHtml: undefined,
-            templateName: undefined,
-            templatePath: undefined,
-        };
-        const encoded = encodeData(data);
-        const tape = callNative(() => native.collectInvocations(ast, encoded, ctx));
-        const resolved = this.#invokeHelpers(tape, undefined, undefined);
-        return callNative(() => native.renderAst(ast, encoded, resolved, ctx));
-    }
-    // Invoke each collected helper TS-side in tape order, producing the resolved
-    // values the renderer consumes. Mirrors the old `render.ts` Call-arm
-    // contract: SafeString → raw; null/undefined → ""; non-string/SafeString or
-    // a throw / thenable → E_INKER_HELPER_THROW (preserving InkerRenderError
-    // passthrough + cause chain).
-    #invokeHelpers(tape, templateName, templatePath) {
-        const out = [];
-        for (const inv of tape) {
-            const helper = this.#helpers.get(inv.name);
-            if (helper === undefined) {
-                throw new InkerRenderError("E_INKER_UNKNOWN_HELPER", `Helper '${inv.name}' is not registered in this Templates instance`, { templatePath, templateName, expression: inv.name });
-            }
-            let result;
-            let thenProp;
-            try {
-                result = helper(...inv.args);
-                if (result !== null && typeof result === "object") {
-                    thenProp = Reflect.get(result, "then");
-                }
-            }
-            catch (cause) {
-                if (cause instanceof InkerRenderError)
-                    throw cause;
-                const message = cause instanceof Error ? cause.message : String(cause);
-                throw new InkerRenderError("E_INKER_HELPER_THROW", `Helper '${inv.name}' threw: ${message}`, { templatePath, templateName, expression: inv.name }, { cause });
-            }
-            if (typeof thenProp === "function") {
-                throw new InkerRenderError("E_INKER_HELPER_THROW", `Helper '${inv.name}' returned a Promise/thenable — Inker renderers are synchronous (D2)`, { templatePath, templateName, expression: inv.name });
-            }
-            if (result instanceof SafeString) {
-                out.push({ value: result.value, isSafe: true });
-            }
-            else if (result === null || result === undefined) {
-                out.push({ value: "", isSafe: false });
-            }
-            else if (typeof result === "string") {
-                out.push({ value: result, isSafe: false });
-            }
-            else {
-                throw new InkerRenderError("E_INKER_HELPER_THROW", `Helper '${inv.name}' returned ${typeof result} — Inker helpers must return string | SafeString | null | undefined (D2)`, { templatePath, templateName, expression: inv.name });
-            }
-        }
-        return out;
+        // No disk directives here (rejected above), so a bare node list renders
+        // through the Node renderer (62-2 pivot) with the helpers in scope.
+        // Validate the data tree (guard side-effects only; render the original).
+        encodeData(data);
+        return renderNodeTree(this.#astNodes(ast), data, this.#helpers, {
+            tags: this.#tags,
+        });
     }
     clearCache() {
         this.#cacheGeneration += 1;
@@ -564,26 +689,35 @@ export class Templates {
         // #cacheGeneration counter discards that write — see #loadAstUncached.
         this.#inflight.clear();
     }
-    async #loadAst(absPath, validatedName) {
-        const inflight = this.#inflight.get(absPath);
+    async #loadAst(absPath, validatedName, root) {
+        // Key the cache/inflight maps by the resolving disk's root AND the
+        // absolute path, not the path alone. Two disks with overlapping roots
+        // can resolve the SAME absPath; keying by path alone would let disk A's
+        // entry (which passed containment against A's root) be served to disk B
+        // on a cache hit — bypassing B's symlink-containment check, which only
+        // runs on a cache MISS. The compound key isolates each disk's cache.
+        const cacheKey = `${root}\u0000${absPath}`;
+        const inflight = this.#inflight.get(cacheKey);
         if (inflight !== undefined)
             return inflight;
-        const promise = this.#loadAstUncached(absPath, validatedName);
-        this.#inflight.set(absPath, promise);
+        const promise = this.#loadAstUncached(absPath, validatedName, root);
+        this.#inflight.set(cacheKey, promise);
         try {
             return await promise;
         }
         finally {
-            this.#inflight.delete(absPath);
+            this.#inflight.delete(cacheKey);
         }
     }
-    async #loadAstUncached(absPath, validatedName) {
+    async #loadAstUncached(absPath, validatedName, root) {
         // T7: snapshot the cache generation. If clearCache() runs while this
         // load is in flight, the snapshot will diverge from #cacheGeneration
         // at write-back time, and we'll skip the cache.set() to avoid
         // silently restoring a stale AST after operator invalidation.
         const loadGeneration = this.#cacheGeneration;
-        const cached = this.#cache.get(absPath);
+        // Same compound (root, absPath) key as #loadAst — see the note there.
+        const cacheKey = `${root}\u0000${absPath}`;
+        const cached = this.#cache.get(cacheKey);
         if (this.#cacheMode === "never" && cached !== undefined) {
             return cached.ast;
         }
@@ -639,9 +773,9 @@ export class Templates {
                 throw wrapFsError(cause, absPath, validatedName);
             }
             if (realPath !== absPath) {
-                const rel = path.relative(this.#root, realPath);
+                const rel = path.relative(root, realPath);
                 if (rel !== "" && (rel.startsWith("..") || path.isAbsolute(rel))) {
-                    throw new InkerRenderError("E_INKER_INVALID_PATH", `Resolved template path escapes the templates root via symlink: ${realPath} is outside ${this.#root}`, { templatePath: realPath, templateName: validatedName });
+                    throw new InkerRenderError("E_INKER_INVALID_PATH", `Resolved template path escapes the templates root via symlink: ${realPath} is outside ${root}`, { templatePath: realPath, templateName: validatedName });
                 }
             }
             try {
@@ -657,23 +791,23 @@ export class Templates {
         // T4: strip leading UTF-8 BOM if present. Windows editors (Notepad)
         // commonly insert it; lex sees it as a Text token, defeating the
         // "first non-stripped node must be Layout" composition rule and
-        // silently treating `{% layout %}` as body content.
+        // silently treating `@layout()` as body content.
         if (source.charCodeAt(0) === 0xfeff) {
             source = source.slice(1);
         }
-        const ast = callNative(() => getNative().parseTemplate(source, [...this.#helperNames]));
+        const ast = callNative(() => getNative().parseTemplate(source, [...this.#helperNames], [...this.#tags.keys()]));
         // T7: only populate the cache if the generation is unchanged. If
         // clearCache() was called during the await chain above, the new
         // generation discards this write — the next render() starts fresh.
         if (this.#cacheGeneration === loadGeneration) {
-            this.#cache.set(absPath, { ast, mtimeMs: currentMtime });
+            this.#cache.set(cacheKey, { ast, mtimeMs: currentMtime });
         }
         return ast;
     }
     async #compose(entryAst, entryName, entryAbsPath, includeStack) {
         const partialAsts = new Map();
         const componentAsts = new Map();
-        // The Rust parser already separates the leading `{% layout %}` into
+        // The Rust parser already separates the leading `@layout()` into
         // `ast.layout` and excludes it from `ast.nodes`, so `entryAst` IS the
         // body AST (no slice). Duplicate / mis-placed layout directives are
         // rejected at parse time (parseTemplate throws E_INKER_DUPLICATE_LAYOUT /
@@ -709,9 +843,7 @@ export class Templates {
         }
         const layoutLine = entryInfo.layoutLine ?? undefined;
         const layoutColumn = entryInfo.layoutColumn ?? undefined;
-        const layoutValidated = validateName(layoutName);
-        const layoutAbsPath = path.join(this.#root, `${layoutValidated}.inker`);
-        assertContained(this.#root, layoutAbsPath, layoutValidated);
+        const { root: layoutRoot, validated: layoutValidated, absPath: layoutAbsPath, } = this.#resolveTemplateFile(layoutName);
         if (includeStack.has(layoutAbsPath)) {
             throw new InkerRenderError("E_INKER_CIRCULAR_INCLUDE", `Circular include: ${this.#cycleString(includeStack, layoutAbsPath)} (started at ${entryAbsPath})`, {
                 templatePath: layoutAbsPath,
@@ -723,7 +855,7 @@ export class Templates {
         includeStack.add(layoutAbsPath);
         let layoutAst;
         try {
-            layoutAst = await this.#loadAst(layoutAbsPath, layoutValidated);
+            layoutAst = await this.#loadAst(layoutAbsPath, layoutValidated, layoutRoot);
         }
         catch (e) {
             includeStack.delete(layoutAbsPath);
@@ -733,7 +865,7 @@ export class Templates {
             const layoutInfo = layoutAst.composeInfo;
             // Nested-layout rejection.
             if (layoutInfo.hasLayout) {
-                throw new InkerRenderError("E_INKER_NESTED_LAYOUT_UNSUPPORTED", `Layout file '${layoutValidated}' itself contains {% layout %} — nested layouts are not supported`, {
+                throw new InkerRenderError("E_INKER_NESTED_LAYOUT_UNSUPPORTED", `Layout file '${layoutValidated}' itself contains @layout() — nested layouts are not supported`, {
                     templatePath: layoutAbsPath,
                     templateName: layoutValidated,
                     line: layoutInfo.layoutLine ?? undefined,
@@ -777,9 +909,7 @@ export class Templates {
     }
     async #resolvePartialsIn(refs, partialAsts, componentAsts, includeStack, hostAbsPath) {
         for (const node of refs) {
-            const partialValidated = validateName(node.name);
-            const partialAbsPath = path.join(this.#root, `${partialValidated}.inker`);
-            assertContained(this.#root, partialAbsPath, partialValidated);
+            const { root: partialRoot, validated: partialValidated, absPath: partialAbsPath, } = this.#resolveTemplateFile(node.name);
             const partialKey = normalizePartialKey(node.name);
             if (includeStack.has(partialAbsPath)) {
                 throw new InkerRenderError("E_INKER_CIRCULAR_INCLUDE", `Circular include: ${this.#cycleString(includeStack, partialAbsPath)} (referenced from ${hostAbsPath})`, {
@@ -796,7 +926,7 @@ export class Templates {
             includeStack.add(partialAbsPath);
             let partialAst;
             try {
-                partialAst = await this.#loadAst(partialAbsPath, partialValidated);
+                partialAst = await this.#loadAst(partialAbsPath, partialValidated, partialRoot);
             }
             catch (e) {
                 includeStack.delete(partialAbsPath);
@@ -806,7 +936,7 @@ export class Templates {
                 const info = partialAst.composeInfo;
                 // Layout-in-partial rejection.
                 if (info.hasLayout) {
-                    throw new InkerRenderError("E_INKER_LAYOUT_IN_PARTIAL", `Partial file '${partialValidated}' contains {% layout %} — partials cannot declare layouts`, {
+                    throw new InkerRenderError("E_INKER_LAYOUT_IN_PARTIAL", `Partial file '${partialValidated}' contains @layout() — partials cannot declare layouts`, {
                         templatePath: partialAbsPath,
                         templateName: partialValidated,
                         line: info.layoutLine ?? undefined,
@@ -835,10 +965,10 @@ export class Templates {
     }
     async #resolveComponentsIn(refs, partialAsts, componentAsts, includeStack, hostAbsPath) {
         for (const node of refs) {
-            const componentName = `components/${node.name}`;
-            const componentValidated = validateName(componentName);
-            const componentAbsPath = path.join(this.#root, `${componentValidated}.inker`);
-            assertContained(this.#root, componentAbsPath, componentValidated);
+            // Split the optional `disk::` prefix off FIRST, then prepend the
+            // `components/` directory to the bare name so `disk::button` resolves
+            // to `<disk>/components/button.inker`, not `<default>/components/disk::button`.
+            const { root: componentRoot, validated: componentValidated, absPath: componentAbsPath, } = this.#resolveTemplateFile(node.name, "components/");
             const componentKey = normalizePartialKey(node.name);
             if (includeStack.has(componentAbsPath)) {
                 throw new InkerRenderError("E_INKER_CIRCULAR_INCLUDE", `Circular include: ${this.#cycleString(includeStack, componentAbsPath)} (referenced from ${hostAbsPath})`, {
@@ -854,7 +984,7 @@ export class Templates {
             includeStack.add(componentAbsPath);
             let componentAst;
             try {
-                componentAst = await this.#loadAst(componentAbsPath, componentValidated);
+                componentAst = await this.#loadAst(componentAbsPath, componentValidated, componentRoot);
             }
             catch (e) {
                 includeStack.delete(componentAbsPath);
@@ -865,26 +995,20 @@ export class Templates {
                 // Layout-in-component rejection (reuse E_INKER_LAYOUT_IN_PARTIAL
                 // per AC5: same axis "layout in non-entry file").
                 if (info.hasLayout) {
-                    throw new InkerRenderError("E_INKER_LAYOUT_IN_PARTIAL", `Component file '${componentValidated}' contains {% layout %} — components cannot declare layouts`, {
+                    throw new InkerRenderError("E_INKER_LAYOUT_IN_PARTIAL", `Component file '${componentValidated}' contains @layout() — components cannot declare layouts`, {
                         templatePath: componentAbsPath,
                         templateName: componentValidated,
                         line: info.layoutLine ?? undefined,
                         column: info.layoutColumn ?? undefined,
                     });
                 }
-                // Slot-leak rejection: components MUST NOT contain {{> body }}.
-                const slot = info.slots[0];
-                if (slot !== undefined) {
-                    throw new InkerRenderError("E_INKER_UNKNOWN_SLOT", `Component '${componentValidated}' contains {{> ${slot.name} }} — slot placeholders are only valid inside layout files (line ${slot.line}, column ${slot.column})`, {
-                        templatePath: componentAbsPath,
-                        templateName: componentValidated,
-                        line: slot.line,
-                        column: slot.column,
-                    });
-                }
+                // A component template MAY contain slot placeholders: `{{> body }}`
+                // yields the default (block-body) slot and `{{> name }}` a named
+                // `@slot('name')` provided by the caller. Placeholders with no
+                // matching slot render empty (Edge parity), so no validation here.
                 componentAsts.set(componentKey, componentAst);
                 // Recurse into nested components AND partials included inside this
-                // component (mutual recursion → a {% include %} in a component is
+                // component (mutual recursion → a @include() in a component is
                 // pre-loaded, fixing E_INKER_DISK_REQUIRED at render time).
                 await this.#resolveComponentsIn(info.components, partialAsts, componentAsts, includeStack, componentAbsPath);
                 await this.#resolvePartialsIn(info.partials, partialAsts, componentAsts, includeStack, componentAbsPath);