lime-csr-js 0.1.4

package/src/shared.js

@@ -0,0 +1,103 @@
+/**
+ * @module shared
+ * @description Pure utility helper functions for lime-csr.js.
+ * This module is a leaf dependency and must not import any other modules in the codebase.
+ */
+
+/**
+ * Checks if a given node is inside a not-yet-expanded reactive block
+ * (<if data-live> or <for data-live>).
+ * If the node itself is the root of the live block, it returns false
+ * (so that its own attributes can still be processed/bound).
+ *
+ * Used by: index.js, template.js, partials.js, loops.js, conditionals.js,
+ * bindings.js, bindings-model.js, bindings-show.js.
+ *
+ * @param {Node} node
+ * @returns {boolean}
+ */
+export function inLiveBlock(node) {
+  if (!node) return false;
+  if (node.nodeType !== 1) { // Node.ELEMENT_NODE is 1
+    const parent = node.parentElement;
+    return !!(parent?.closest?.('if[data-live]') || parent?.closest?.('for[data-live]'));
+  }
+  const isLiveRoot = node.matches?.('if[data-live]') || node.matches?.('for[data-live]');
+  if (isLiveRoot) return false;
+  return !!(node.closest?.('if[data-live]') || node.closest?.('for[data-live]'));
+}
+
+/**
+ * Checks if a given node is inside the content of a not-yet-expanded ordinary
+ * (non-data-live) <for> block.
+ * If the node itself is the root <for> element, it returns false (so its own
+ * attributes can still be resolved).
+ *
+ * Used by: template.js, partials.js, loops.js.
+ *
+ * @param {Node} node
+ * @returns {boolean}
+ */
+export function inUnexpandedFor(node) {
+  if (!node) return false;
+  if (node.nodeType !== 1) {
+    const parent = node.parentElement;
+    return !!parent?.closest?.('for:not([data-live])');
+  }
+  const isForRoot = node.matches?.('for:not([data-live])');
+  if (isForRoot) return false;
+  return !!node.closest?.('for:not([data-live])');
+}
+
+/**
+ * Longest Increasing Subsequence, via patience sorting — O(n log n).
+ *
+ * Given a sequence of numbers, returns the SET of indices (into `seq`) that
+ * form one valid longest increasing subsequence. Used by the "lcs" diff
+ * strategy: `seq` is the OLD position of each surviving item, listed in NEW
+ * order — the LIS is the maximal set of survivors whose relative order is
+ * unchanged, and can therefore stay physically untouched in the DOM.
+ *
+ * Used by: bindings-loops.js.
+ *
+ * @param {number[]} seq
+ * @returns {Set<number>} indices into `seq`
+ */
+export function longestIncreasingSubsequenceIndices(seq) {
+  const n = seq.length;
+  if (n === 0) return new Set();
+
+  // tails[k] = index (into seq) of the smallest possible tail value for an
+  // increasing subsequence of length k+1 found so far.
+  const tails = [];
+  // predecessors[i] = index (into seq) of the previous element in the
+  // increasing subsequence that ends at i, or -1 if i starts one.
+  const predecessors = new Array(n).fill(-1);
+
+  for (let i = 0; i < n; i++) {
+    const val = seq[i];
+
+    // Binary search: first position in `tails` whose seq-value is >= val.
+    let lo = 0;
+    let hi = tails.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (seq[tails[mid]] < val) lo = mid + 1;
+      else hi = mid;
+    }
+
+    if (lo > 0) predecessors[i] = tails[lo - 1];
+    if (lo === tails.length) tails.push(i);
+    else tails[lo] = i;
+  }
+
+  // Reconstruct the subsequence by walking predecessors backward from the
+  // last element of the longest tail found.
+  const result = new Set();
+  let k = tails[tails.length - 1];
+  while (k !== -1) {
+    result.add(k);
+    k = predecessors[k];
+  }
+  return result;
+}

package/src/store.js

@@ -0,0 +1,265 @@
+/**
+ * @module store
+ * @description Path-based reactive state management.
+ *
+ * Core rules:
+ *   - State access via dot-path: "user.profile.name"
+ *   - When a path changes, all ancestor segments are also notified.
+ *     E.g. changing "a.b.c" triggers subscribers for "a", "a.b", "a.b.c".
+ *   - Downward notification: changing "a.b" also notifies descendants like "a.b.c"
+ *     (subscribers whose path starts with the changed path). This means
+ *     store.set("user", {name:"new"}) correctly updates data-text="user.name" bindings.
+ *   - Object.is change check: setting the same value again does not trigger subscribers.
+ *   - subscribe() returns a cancel function; when the last subscriber for a path is
+ *     removed, that path's Map entry is deleted — leak-free cleanup.
+ *   - __proto__/constructor/prototype are rejected as path segments (prototype
+ *     pollution guard); set/update silently do nothing for such paths.
+ *   - store.computed(path, deps, fn): registers a derived value that auto-updates
+ *     when any dep changes. Returns a dispose function.
+ */
+import { warn } from './errors.js';
+
+/**
+ * @typedef {Object} Store
+ * @property {function(string=): *} get
+ *   Returns the value at path; returns the entire state if no path is given.
+ * @property {function(string, *): boolean} set
+ *   Writes value to path, notifies subscribers; returns whether a change occurred.
+ * @property {function(string, function(*): *): boolean} update
+ *   Passes the current value to the updater function, sets the result.
+ * @property {function(string, function(*, *, string): void): function(): void} subscribe
+ *   Subscribes to path; the returned function cancels the subscription.
+ */
+
+/**
+ * Reads a value from an object via a dotted path.
+ *
+ * @param {Object} source - Source object
+ * @param {string} path   - Dotted path, e.g. "user.profile.name"
+ * @returns {*} The found value; `undefined` if any segment is missing.
+ */
+export function getByPath(source, path) {
+  const keys = String(path).split('.');
+  if (keys.some((key) => UNSAFE_PATH_SEGMENTS.has(key))) return undefined;
+
+  return keys.reduce((value, key) => {
+    if (value == null || !Object.hasOwn(value, key)) return undefined;
+    return value[key];
+  }, source);
+}
+
+// __proto__/constructor/prototype are never accepted as a path segment.
+// Otherwise "obj[key]" would point to an existing (typeof "object") prototype
+// chain, and the next assignment would pollute Object.prototype globally.
+const UNSAFE_PATH_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * Writes a value to an object via a dotted path; mutates the source object.
+ * Intermediate objects are created if missing.
+ *
+ * Security: if any path segment is `__proto__`, `constructor`, or `prototype`,
+ * the write is silently rejected (prototype pollution guard).
+ *
+ * @param {Object} source   - Target object
+ * @param {string} path     - Dotted path
+ * @param {*}      newValue - Value to write
+ * @returns {{ changed: boolean, previousValue: * }}
+ *   `changed`: whether a real change occurred (Object.is comparison).
+ *   `previousValue`: the previous value (`undefined` if no change).
+ */
+export function setByPath(source, path, newValue) {
+  const keys = String(path).split(".");
+  const lastKey = keys.pop();
+
+  if (UNSAFE_PATH_SEGMENTS.has(lastKey) || keys.some((key) => UNSAFE_PATH_SEGMENTS.has(key))) {
+    return { changed: false };
+  }
+
+  // Walk all but the last segment; create intermediate objects if missing
+  const target = keys.reduce((obj, key) => {
+    if (obj[key] == null || typeof obj[key] !== "object") obj[key] = {};
+    return obj[key];
+  }, source);
+
+  const previousValue = target[lastKey];
+  if (Object.is(previousValue, newValue)) return { changed: false };
+
+  target[lastKey] = newValue;
+  return { changed: true, previousValue };
+}
+
+/**
+ * Creates a path-based reactive store.
+ *
+ * @param {Object} [initialState={}] - Initial state object (held by reference, not copied).
+ * @returns {Store}
+ */
+export function createStore(initialState = {}) {
+  // Map holding subscriber functions per path
+  const subscribers = new Map();
+
+  // Set of computed paths — direct store.set() on these warns in dev-mode
+  const computedPaths = new Set();
+
+  // Guard flag to swallow a computed's own re-trigger (loop prevention)
+  const computedUpdating = new Set();
+
+  /**
+   * Notifies subscribers for the changed path, all ancestor segments (upward),
+   * and all descendant paths (downward — keys that start with `path + "."``).
+   *
+   * Upward: "a.b.c" changed → notify "a", "a.b", "a.b.c".
+   * Downward: "user" changed → also notify "user.name", "user.profile.age", etc.
+   * This ensures store.set("user", {...}) updates data-text="user.name" bindings.
+   *
+   * @param {string} path          - The changed full path
+   * @param {*}      previousValue - Value before the change
+   */
+  function notify(path, previousValue) {
+    const segments = String(path).split(".");
+
+    // Upward: "a.b.c" → notify "a", "a.b", "a.b.c"
+    segments.forEach((_, index) => {
+      const currentPath = segments.slice(0, index + 1).join(".");
+      const bucket = subscribers.get(currentPath);
+      if (!bucket) return;
+      const currentValue = getByPath(initialState, currentPath);
+      bucket.forEach((callback) => callback(currentValue, previousValue, path));
+    });
+
+    // Downward: notify all subscribers whose path starts with `path + "."`
+    const prefix = path + ".";
+    for (const [subPath, bucket] of subscribers) {
+      if (!subPath.startsWith(prefix)) continue;
+      const currentValue = getByPath(initialState, subPath);
+      bucket.forEach((callback) => callback(currentValue, previousValue, path));
+    }
+  }
+
+  return {
+    /**
+     * Returns the value at path.
+     *
+     * @param {string} [path=""] - If empty, returns the entire state object.
+     * @returns {*}
+     */
+    get(path = "") {
+      return path ? getByPath(initialState, path) : initialState;
+    },
+
+    /**
+     * Writes value to path; notifies subscribers if the value changed.
+     * Dev-mode warnings:
+     *   - Computed path: warns that computed paths should not be set directly.
+     *   - In-place mutation: if value is an object/array and the reference is
+     *     identical to the stored value, warns about same-reference mutation.
+     *
+     * @param {string} path
+     * @param {*}      value
+     * @returns {boolean} `true` if a change occurred.
+     */
+    set(path, value) {
+      // Dev-mode: warn about direct writes to computed paths
+      if (computedPaths.has(path) && !computedUpdating.has(path)) {
+        warn('COMPUTED_MANUAL_SET',
+          `Path "${path}" is managed by store.computed(). Manual store.set() will be ` +
+          `overwritten on next dep change. Use store.computed() or a different path.`);
+      }
+
+      // Dev-mode: warn about in-place mutation (same object/array reference)
+      const existing = getByPath(initialState, path);
+      if (value !== null && typeof value === 'object' && Object.is(existing, value)) {
+        warn('IN_PLACE_MUTATION',
+          `store.set("${path}", value): value is the SAME reference as the stored object/array. ` +
+          `In-place mutation detected — subscriber will NOT fire. Pass a new reference: ` +
+          `e.g. store.set("${path}", [...arr]) or store.set("${path}", {...obj}).`);
+        return false;
+      }
+
+      const result = setByPath(initialState, path, value);
+      if (result.changed) notify(path, result.previousValue);
+      return result.changed;
+    },
+
+    /**
+     * Passes the current value to `updater`, sets the return value.
+     *
+     * @param {string}            path
+     * @param {function(*): *}    updater
+     * @returns {boolean}
+     */
+    update(path, updater) {
+      return this.set(path, updater(this.get(path)));
+    },
+
+    /**
+     * Subscribes to path. The returned function cancels the subscription.
+     * When the last subscriber for a path is removed, its Map entry is deleted (no leak).
+     *
+     * @param {string}   path
+     * @param {function(currentValue: *, previousValue: *, changedPath: string): void} callback
+     * @returns {function(): void} Cleanup — removes the subscription.
+     */
+    subscribe(path, callback) {
+      if (!subscribers.has(path)) subscribers.set(path, new Set());
+      subscribers.get(path).add(callback);
+      return () => {
+        const bucket = subscribers.get(path);
+        if (!bucket) return;
+        bucket.delete(callback);
+        if (bucket.size === 0) subscribers.delete(path);
+      };
+    },
+
+    /**
+     * Registers a computed (derived) value at `path`.
+     * Immediately computes and sets the initial value, then re-computes
+     * whenever any of the `deps` paths change.
+     *
+     * Chaining: a computed path can itself be a dep of another computed.
+     * Loop prevention: if a dep change triggers the same computed recursively,
+     * the re-entry is swallowed.
+     *
+     * Dev-mode: calling store.set(path) on a computed path warns the developer.
+     *
+     * @param {string}            path   - Destination path in the store (ordinary path).
+     * @param {string[]}          deps   - Array of store paths to watch.
+     * @param {function(): *}     fn     - Pure function; return value is written to path.
+     * @returns {function(): void}        dispose — cancels all dep subscriptions.
+     *
+     * @example
+     * const dispose = store.computed('fullName', ['firstName', 'lastName'],
+     *   () => store.get('firstName') + ' ' + store.get('lastName'));
+     * // later:
+     * dispose();
+     */
+    computed(path, deps, fn) {
+      computedPaths.add(path);
+
+      const recompute = () => {
+        if (computedUpdating.has(path)) return; // loop guard
+        computedUpdating.add(path);
+        try {
+          const newVal = fn();
+          // Bypass the computed-path warning by going through setByPath directly
+          const result = setByPath(initialState, path, newVal);
+          if (result.changed) notify(path, result.previousValue);
+        } finally {
+          computedUpdating.delete(path);
+        }
+      };
+
+      // Initial computation
+      recompute();
+
+      // Subscribe to each dep
+      const unsubs = deps.map((dep) => this.subscribe(dep, recompute));
+
+      return function dispose() {
+        for (const unsub of unsubs) unsub();
+        computedPaths.delete(path);
+      };
+    },
+  };
+}
+

package/src/template.js

@@ -0,0 +1,263 @@
+/**
+ * @module template
+ * @description <template> reading, fragment cache, and static ${path} interpolation.
+ *
+ * Core rules:
+ *   - Source: a standard <template id="tpl-{name}"> element (DOM, not a string).
+ *   - Output: DocumentFragment — not a string innerHTML.
+ *   - ${path}: path resolution only. NO expression evaluation (new Function).
+ *   - Resolved values are written RAW to node.nodeValue / attr.value.
+ *     NOT escaped: neither of these two DOM properties parses HTML (no entity
+ *     decoding), so escapeHtml/safeAttr is unnecessary here — and if used,
+ *     characters like "&" would show up literally as "&amp;" on screen
+ *     (double-encoding). Security already comes from the DOM APIs themselves;
+ *     see the same rationale in bindings.js (the raw-value rule for setAttribute).
+ *   - The cache holds the original; every render takes its own cloneNode(true).
+ *   - <if>, <for>, <partial>, and reactive data-* are NOT processed in this module.
+ *   - resolveStatic does not touch content inside a not-yet-expanded <if
+ *     data-live>/<for data-live> OR an ordinary (non-data-live) <for> —
+ *     preventing early/wrong-context resolution in nested loops (see
+ *     inLiveBlock, inUnexpandedFor).
+ *   - getTemplate detects (dev-mode, one-time) special tags that were written
+ *     inside a <table> but got moved out by the HTML parser's foster-parenting
+ *     when the template was first read, and warns about it — it does NOT fix
+ *     the behavior, only warns actionably (see detectTableFosterParenting).
+ */
+
+import { getByPath } from "./store.js";
+import { errors, isDevMode } from "./errors.js";
+import { inLiveBlock, inUnexpandedFor } from "./shared.js";
+
+/** @type {Map<string, DocumentFragment>} Holds original fragments; used before cloning. */
+const templateCache = new Map();
+
+// Special tags written inside a <table> but moved out by the HTML parser's
+// "foster parenting" algorithm (see detectTableFosterParenting).
+// NOTE: <partial> is DELIBERATELY left out — <partial> is ALWAYS childless BY
+// DESIGN (it's just a reference), so the "is it empty?" signal carries no
+// discriminating power for it (see the function's JSDoc).
+const SPECIAL_TAGS = new Set(['IF', 'FOR', 'ELSE']);
+const TABLE_CHILD_SELECTOR = 'tr, td, th, tbody, thead, tfoot, caption, col, colgroup';
+
+// Regex that matches ${...} placeholders — must contain only a path, not an expression
+const PLACEHOLDER = /\$\{([^}]+)\}/g;
+
+/**
+ * Resolves a dotted path from the context object. Returns an empty string if not found.
+ *
+ * Returns a raw string (NO escaping): the result is only ever written to
+ * node.nodeValue / attr.value, neither of which parses HTML, so escaping
+ * would be both unnecessary and wrong (double-encoding). Security comes from
+ * the DOM APIs themselves.
+ *
+ * @param {string} path    - Dotted path, e.g. "user.name"
+ * @param {Object} context - Plain object to read values from
+ * @returns {string}
+ */
+function resolvePath(path, context) {
+  const value = getByPath(context, path.trim());
+  if (value == null) return "";
+  return String(value);
+}
+
+/**
+ * Resolves every ${path} placeholder in a string from the context.
+ * new Function is NEVER used; only path resolution via getByPath.
+ *
+ * @param {string} str     - Raw string that may contain ${...}
+ * @param {Object} context - Object to read values from
+ * @returns {string}
+ */
+function resolveString(str, context) {
+  return str.replace(PLACEHOLDER, (_match, path) => resolvePath(path, context));
+}
+
+/**
+ * Is the node INSIDE the content of a not-yet-expanded <if data-live> or
+ * <for data-live> block? (Consistent with the same pattern in bindings.js.)
+ *
+ * IMPORTANT DISTINCTION: if an element IS ITSELF a live-root
+ * (if[data-live]/for[data-live]) — even if one of ITS ANCESTORS is ALSO a
+ * live-root — its own attributes like is-.../than/each/as/data-live may
+ * carry a dynamic path via ${...} (e.g. `is-truthy="${likedPath}"`, or
+ * `each="${repliesPath}"` on a nested <for data-live>) and MUST be resolved
+ * this pass: all live-roots within the same partial/render call share the
+ * SAME (correct) context. Only descendants that are NOT themselves a
+ * live-root (text/element CONTENT) are deferred.
+ *
+ * @param {Node} node
+ * @returns {boolean}
+ */
+
+
+/**
+ * Is the node INSIDE the content of a not-yet-expanded ordinary
+ * (non-data-live) <for> block? (Same pattern as inUnexpandedFor in partials.js.)
+ *
+ * WHY THIS IS NEEDED: loops.js calls resolveStatic(frag, itemContext) for the
+ * outer item BEFORE expanding an inner (not-yet-expanded) <for>. A bare
+ * interpolation like ${p.label} inside the inner <for>'s body, if resolved
+ * this pass against the outer context (since p isn't bound yet), would
+ * become an empty/wrong string — AND since the placeholder would be gone,
+ * the inner loop's own (correct-context) pass would have nothing left to
+ * resolve. So such a node is SKIPPED here; the inner <for>'s own
+ * resolveStatic call (via loops.js's recursion in the same pass) resolves it
+ * with the correct itemContext.
+ *
+ * SAME DISTINCTION (consistent with inLiveBlock): if an element IS ITSELF a
+ * not-yet-expanded <for>, its own attributes like each/as/index (e.g.
+ * `each="${x}"`) can still be resolved this pass — only descendants INSIDE
+ * the <for> (text/element content) are deferred.
+ *
+ * @param {Node} node
+ * @returns {boolean}
+ */
+
+
+/**
+ * Are the <table>s in the fragment victims of a special tag that got moved
+ * out by the HTML parser's "foster parenting" algorithm?
+ *
+ * WHY THIS SIGNAL — REAL PARSER BEHAVIOR (verified in headless Chromium):
+ *   When you write `<table><if is-truthy="x"><tr><td>${row}</td></tr></if></table>`,
+ *   the WHATWG HTML "in table" insertion mode's "anything else" rule moves
+ *   <if> to right BEFORE the table DURING PARSING (foster parenting; see
+ *   https://html.spec.whatwg.org/#parsing-main-intable). BUT the <tr>/<td>
+ *   that arrive while <if> is still on the open-elements stack are
+ *   TABLE-VALID tags themselves, so they are NOT foster-parented — they go
+ *   straight into <table><tbody>, not INSIDE <if>. Result: <if> is left as a
+ *   COMPLETELY EMPTY shell before the table; <tr>/<td> end up inside <table>
+ *   but rendered UNCONDITIONALLY (as if <if> never wrapped them at all). So
+ *   LOOKING FOR a table-child INSIDE a fostered special tag is wrong (it will
+ *   never be found) — the actual signature is the tag being left EMPTY.
+ *
+ * REDUCING FALSE-POSITIVE RISK: checking only "is there an empty <if>/<for>
+ * right before a table" alone isn't strong enough either (rarely, a
+ * deliberately empty block could happen to sit right next to an unrelated
+ * table). So TWO signals are required together: (1) the special tag is
+ * COMPLETELY empty (no element or text children) AND (2) the adjacent
+ * <table> ACTUALLY contains row content (tr/td/tbody/...). A block that is
+ * NOT empty — e.g. plain <if>...</if><table>...</table> unrelated to the
+ * table (satisfies condition 2 but not condition 1) — never produces a false positive.
+ *
+ * OUT OF SCOPE (deliberate limits):
+ *   - <partial>: not included in SPECIAL_TAGS — <partial> is ALWAYS childless
+ *     by design, so the "is it empty?" signal carries no discriminating power
+ *     for it (looks the same whether fostered or not). Since there's no
+ *     reliable discriminating signal, it's not checked at all, to avoid
+ *     raising false-positive risk.
+ *   - Not detected if the special tag is NOT the <table>'s immediate previous
+ *     sibling (e.g. nested inside a <div>) — a false negative, acceptable per
+ *     KISS (this is only a dev-mode warning anyway, it doesn't fix the behavior).
+ *
+ * @param {DocumentFragment|Element} fragment
+ * @param {string} templateName
+ * @returns {void}
+ */
+function detectTableFosterParenting(fragment, templateName) {
+  for (const table of fragment.querySelectorAll('table')) {
+    const prev = table.previousElementSibling;
+    if (!prev || !SPECIAL_TAGS.has(prev.tagName)) continue;
+    const isEmptyShell = prev.childElementCount === 0 && prev.textContent.trim() === '';
+    if (isEmptyShell && table.querySelector(TABLE_CHILD_SELECTOR)) {
+      errors.tableFosterParenting(templateName);
+      return; // one warning per template is enough
+    }
+  }
+}
+
+/**
+ * Finds the <template id="tpl-{name}"> element and caches the original fragment.
+ * Every call returns an independent copy via cloneNode(true) from the cache.
+ *
+ * The foster-parenting check (detectTableFosterParenting) runs only ONCE,
+ * when the template is FIRST read (entering the cache) — NOT on every
+ * render, for performance. Doesn't run at all if dev_mode is off.
+ *
+ * @param {string} name - Template name; looked up in the DOM as `id="tpl-{name}"`.
+ * @returns {DocumentFragment|null} Cloned fragment; null if the template isn't found.
+ */
+export function getTemplate(name) {
+  if (!templateCache.has(name)) {
+    const el = document.getElementById(`tpl-${name}`);
+    if (!el || el.tagName !== "TEMPLATE") {
+      errors.templateNotFound(name);
+      return null;
+    }
+    if (isDevMode()) detectTableFosterParenting(el.content, name);
+    // Store the original content; cloning happens on every render
+    templateCache.set(name, el.content);
+  }
+  return templateCache.get(name).cloneNode(true);
+}
+
+/**
+ * Updates every text node and element attribute inside a DocumentFragment via
+ * ${path} resolution. Static (one-time) interpolation only — reactive
+ * updates are bindings.js's responsibility.
+ *
+ * Does NOT touch nodes inside a not-yet-expanded <if data-live>/<for
+ * data-live> — that content is only resolved via setupLiveIfs/setupLiveFors's
+ * renderFn call, with the correct branch/item context (see inLiveBlock). For
+ * the same reason, also does NOT touch nodes INSIDE a not-yet-expanded
+ * ordinary (non-data-live) <for> — in nested static <for>s, the inner loop's
+ * own variable isn't bound yet, so early resolution would be wrong/empty
+ * (see inUnexpandedFor). That content is resolved with the correct
+ * itemContext by loops.js's own recursive resolveStatic call in the same pass.
+ *
+ * @param {DocumentFragment|Element} root - Root node to traverse
+ * @param {Object} context                - Object used for path resolution
+ * @returns {void}
+ */
+export function resolveStatic(root, context) {
+  // TreeWalker: traverses both text nodes (SHOW_TEXT) and elements (SHOW_ELEMENT)
+  const walker = document.createTreeWalker(
+    root,
+    NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT,
+  );
+
+  let node = walker.nextNode();
+  while (node) {
+    if (inLiveBlock(node) || inUnexpandedFor(node)) {
+      node = walker.nextNode();
+      continue;
+    }
+    if (node.nodeType === Node.TEXT_NODE) {
+      // ${} in the middle of a text node: "Hello ${user.name}, welcome" is a single node.
+      // A one-time replacement is sufficient here; splitting for reactivity, if
+      // needed, is done by bindings.js.
+      if (PLACEHOLDER.test(node.nodeValue)) {
+        PLACEHOLDER.lastIndex = 0; // reset the stateful regex
+        node.nodeValue = resolveString(node.nodeValue, context);
+      }
+    } else if (node.nodeType === Node.ELEMENT_NODE) {
+      // ${} in element attributes
+      for (const attr of Array.from(node.attributes)) {
+        if (PLACEHOLDER.test(attr.value)) {
+          PLACEHOLDER.lastIndex = 0;
+          attr.value = resolveString(attr.value, context);
+        }
+      }
+    }
+    node = walker.nextNode();
+  }
+}
+
+/**
+ * Reads the template, clones it, resolves ${path} placeholders with the
+ * context, and returns a ready DocumentFragment.
+ *
+ * Why it returns a fragment (not a string): reactive handles (bindings.js)
+ * will later bind directly to DOM nodes; that binding couldn't be
+ * established if a string were returned.
+ *
+ * @param {string} name    - Template name
+ * @param {Object} [context={}] - Value object for ${path} resolution
+ * @returns {DocumentFragment|null} Ready fragment; null if the template isn't found.
+ */
+export function renderTemplate(name, context = {}) {
+  const fragment = getTemplate(name);
+  if (!fragment) return null;
+  resolveStatic(fragment, context);
+  return fragment;
+}