lime-csr-js 0.1.4

package/src/index.js

@@ -0,0 +1,312 @@
+/**
+ * @module index
+ * lime-csr.js -- main entry point and orchestration layer.
+ *
+ * Modules do NOT import each other; ordering is done only here.
+ *
+ * RENDER PIPELINE ORDER (critical):
+ *   1. beforeRender(context, store)  -- lifecycle hook (optional, from mount options)
+ *   2. expandPartials -- replace <partial>s with their contents (recursive).
+ *   3. expandLoops    -- expand <for>s based on array elements.
+ *   4. processAllIfs  -- select <if>/<else> branches.
+ *   (1-3 may be nested, so loop until no special tags remain)
+ *   5. resolveStatic  -- resolve remaining ${path} placeholders (top-level static).
+ *   6. setupModelBindings -- data-model two-way form binding. RUNS FIRST (2h).
+ *   7. setupBindings  -- data-text + {x}/data-x reactive bindings.
+ *   8. setupShowBindings  -- data-show reactive visibility (display toggle).
+ *   (6-8 order matters for 2h: data-model runs before data-on-* handlers)
+ *   9. afterRender(rootEl, store)    -- lifecycle hook (optional, from mount options)
+ *
+ * WHY resolveStatic LAST:
+ *   If called first, ${item.x} inside a <for> would be resolved in the wrong
+ *   (top-level) context -> "". expandLoops already calls resolveStatic itself;
+ *   only the top-level ${path}s (e.g. ${pageTitle}) need resolution after
+ *   structural expansion.
+ *
+ * WHY setupBindings LAST:
+ *   Binding before structure is fixed (partial/for/if resolved) would open
+ *   subscriptions on nodes that will be deleted -> memory leak.
+ *
+ * pipeline() CALLBACK:
+ *   expandLoops can receive pipeline() per item; this lets <if> and <partial>
+ *   inside the loop resolve correctly in the item context (itemContext).
+ *
+ * data-live BOUNDARY (hasSpecialTags + inLiveBlock):
+ *   A not-yet-expanded <if data-live>/<for data-live> block's INNER
+ *   ordinary <partial>/<for>/<if> are not touched in this pass -- they would
+ *   be rendered with the wrong (outer) context. That content is only processed
+ *   by setupLiveIfs/setupLiveFors's renderFn (render()) with the correct
+ *   branch/element context.
+ *
+ * STATIC <for> + <partial> BOUNDARY (RESOLVED):
+ *   Previously: a <partial> inside a static (non-data-live) <for> that
+ *   referenced a loop variable (data="item.x") would resolve with the wrong
+ *   (outer) context. Now partials.js's inUnexpandedFor() defers such <partial>s;
+ *   expandLoops's SAME-PASS pipeline() call handles them with the correct context.
+ *   Pipeline ORDER DID NOT CHANGE -- only which <partial>s expandPartials touches.
+ *
+ * EVENT DELEGATION (mount()'s OPTIONAL 5th argument -- NOT in render() PIPELINE):
+ *   data-on-{event} (bindings-events.js) is NOT part of the render() pipeline;
+ *   it sets up a single delegation listener on mount()'s `target` only.
+ *   `options.handlers` not provided -> event delegation NOT set up (zero cost,
+ *   backward compatible).
+ *
+ * LIFECYCLE HOOKS (2e):
+ *   mount() options.beforeRender(context, store): called BEFORE pipeline.
+ *   mount() options.afterRender(rootEl, store): called AFTER content appended to target.
+ *   Both are optional and backward-compatible (omitting them changes nothing).
+ *
+ * BLOCK-LEVEL HOOKS (data-after/data-before) NEED `handlers` INSIDE render():
+ *   Unlike data-on-* (bindings-events.js), which is delegation-based and lives
+ *   entirely outside the render() pipeline, data-after/data-before on
+ *   <if data-live>/<for data-live> (bindings-blocks.js/bindings-loops.js) are
+ *   evaluated DURING setupLiveIfs/setupLiveFors -- when a branch/item is
+ *   actually placed in or removed from the DOM. That happens on every
+ *   reconcile, not just at mount() time, so `handlers` cannot be threaded in
+ *   as a one-time delegation listener the way data-on-* is; it must be
+ *   available to render() itself. render() therefore takes `handlers` as an
+ *   explicit 4th parameter and passes it straight through to setupLiveFors/
+ *   setupLiveIfs as a 5th argument, which those modules also forward on their
+ *   own recursive renderFn(...) calls -- so nested live-blocks inside a
+ *   branch/item see the same handlers dictionary. mount() passes
+ *   options.handlers into the initial render() call. Omitting handlers is
+ *   backward-compatible: data-after/data-before are simply skipped with a
+ *   dev-mode warning if referenced without a handlers dictionary.
+ */
+
+import { getTemplate, resolveStatic } from './template.js';
+import { expandPartials } from './partials.js';
+import { expandLoops }    from './loops.js';
+import { processAllIfs }  from './conditionals.js';
+import { setupBindings }  from './bindings.js';
+import { setupModelBindings } from './bindings-model.js';
+import { setupShowBindings } from './bindings-show.js';
+import { setupEventBindings } from './bindings-events.js';
+import { setupLiveIfs }   from './bindings-blocks.js';
+import { setupLiveFors }  from './bindings-loops.js';
+import { errors }         from './errors.js';
+import { inLiveBlock }    from './shared.js';
+
+// ── Re-exports for external consumers ────────────────────────────────────────
+export { createStore, getByPath, setByPath } from './store.js';
+export { getTemplate, resolveStatic, renderTemplate } from './template.js';
+export { escapeHtml, safeAttr, safeUrl, safeStyleUrl } from './utils.js';
+export { evalCondition, processAllIfs, OPERATORS } from './conditionals.js';
+export { expandLoops } from './loops.js';
+export { expandPartials } from './partials.js';
+export { setupBindings } from './bindings.js';
+export { setupModelBindings } from './bindings-model.js';
+export { setupShowBindings } from './bindings-show.js';
+export { setupEventBindings } from './bindings-events.js';
+export { setDevMode, isDevMode, warn } from './errors.js';
+export { setupLiveIfs } from './bindings-blocks.js';
+export { setupLiveFors } from './bindings-loops.js';
+
+// ── Infinite loop protection ─────────────────────────────────────────────────
+const MAX_PIPELINE_ITERATIONS = 100;
+
+// ── Last cleanup record per target ───────────────────────────────────────────
+// WeakMap: automatically cleaned up when the target element is GC'd.
+const mountedTargets = new WeakMap();
+
+
+
+/**
+ * Is there a structural tag under root that the pipeline can STILL process?
+ *
+ * <if>/<for> with data-live are left to setupLiveIfs/setupLiveFors; the
+ * pipeline does NOT touch them. Likewise, ordinary <partial>/<for>/<if>
+ * INSIDE a not-yet-expanded live block also don't count this pass — they too
+ * are only processed once the correct branch/item context is supplied by
+ * renderFn (render()). Without this check, runPipeline would spin uselessly
+ * up to the MAX_PIPELINE_ITERATIONS limit because of live-block content that
+ * never advances.
+ *
+ * @param {Element|DocumentFragment} root
+ * @returns {boolean}
+ */
+function hasSpecialTags(root) {
+  const pending = (selector) =>
+    Array.from(root.querySelectorAll(selector)).some((el) => !inLiveBlock(el));
+
+  return (
+    pending('partial') ||
+    pending('for:not([data-live])') ||
+    pending('if:not([data-live])')
+  );
+}
+
+/**
+ * Runs the partial → for → if loop on the given fragment.
+ * Also passed as a callback to expandLoops AND expandPartials; this way
+ * inner partial/for/if resolve correctly with the loop item's / partial's
+ * (isolated/inherited) context.
+ *
+ * @param {DocumentFragment|Element} frag
+ * @param {Object}                   ctx
+ * @param {number}                   [depth=0] - Partial recursion depth (internal; passed to expandPartials)
+ */
+function runPipeline(frag, ctx, depth = 0) {
+  let iterations = 0;
+  while (hasSpecialTags(frag)) {
+    if (++iterations > MAX_PIPELINE_ITERATIONS) {
+      errors.pipelineDepthLimit(MAX_PIPELINE_ITERATIONS, frag);
+      break;
+    }
+    // Passing the pipeline callback: so inner if/for/partial also resolve
+    // correctly within the partial's own isolated context (see partials.js).
+    expandPartials(frag, ctx, depth, runPipeline);
+    // Passing the pipeline callback: so inner if/partial also resolve within the loop item's context
+    expandLoops(frag, ctx, runPipeline);
+    processAllIfs(frag, ctx);
+  }
+}
+
+/**
+ * Applies the full render pipeline to a fragment and returns a cleanup function.
+ *
+ * Pure function: not tied to global state, takes store and context as parameters.
+ * A reactive block (<if data-live>, reactive <for>) will call this function
+ * again for a subtree in the future: when the condition/list changes, the old
+ * subtree is cleaned up, the new fragment is processed with render() and placed.
+ *
+ * @param {DocumentFragment} fragment - Cloned fragment from getTemplate()
+ * @param {Object}           context  - For static ${path} resolution (stateless)
+ * @param {import('./store.js').Store|null} store - For reactive bindings
+ * @param {Object<string, function(Event, Element): void>} [handlers] - For
+ *   data-on-*'s handler lookup (bindings-events.js, via mount() only) AND
+ *   for block-level data-after/data-before hooks (bindings-blocks.js/
+ *   bindings-loops.js, evaluated here). Optional; omitting it just means
+ *   data-after/data-before are skipped with a dev-mode warning if referenced.
+ * @returns {function(): void} cleanup — cancels the subscriptions from setupBindings
+ */
+export function render(fragment, context, store, handlers) {
+  // 1-3. Structural expansion: loop until no partial/for/non-live-if remains.
+  //      <if>s with data-live are PRESERVED at this stage — left to setupLiveIfs.
+  runPipeline(fragment, context);
+
+  // 4. Resolve the remaining static ${path} placeholders.
+  resolveStatic(fragment, context);
+
+  // 5b. Two-way form binding (data-model). RUNS FIRST (2h): when data-model
+  //     and data-on-input are on the same element, model's listener is
+  //     registered before data-on-* handlers, so the store is up to date
+  //     by the time the application handler runs.
+  //     Same live-block skipping rule (bindings-model.js filter).
+  const modelCleanup = store ? setupModelBindings(fragment, store) : () => {};
+
+  // 5c. Reactive text/attr bindings (data-text + {x}/data-x). Runs after
+  //     model bindings per 2h ordering. Live-block content bound by
+  //     setupLiveFors/setupLiveIfs below -- no double-subscribe.
+  const bindingsCleanup = store ? setupBindings(fragment, store) : () => {};
+
+  // 5d. Reactive visibility (data-show). RUNS BEFORE DOM APPEND so the
+  //     initial state has no FOUC (see bindings-show.js).
+  //     Same live-block skipping rule; order vs. 5b/5c does not matter.
+  const showCleanup = store ? setupShowBindings(fragment, store) : () => {};
+
+  // 6. Reactive <for data-live>: key-based diff + identity preservation.
+  //    ORDER CRITICAL: setupLiveFors runs first. <if data-live> inside a
+  //    <for data-live> is handled by the recursive render() call inside
+  //    renderFn; by the time setupLiveIfs runs, those are already anchors.
+  //    `handlers` is passed through for data-after/data-before lookups; the
+  //    module's own recursive renderFn(...) calls also forward it, since
+  //    render() itself accepts (and needs) a 4th `handlers` argument.
+  const liveForCleanup = store
+    ? setupLiveFors(fragment, context, store, render, handlers)
+    : () => {};
+
+  // 7. Reactive <if data-live>: tear-down/rebuild + branch cleanup.
+  //    render() itself is passed as renderFn; re-called on branch change.
+  //    `handlers` is threaded through the same way as setupLiveFors above.
+  const liveCleanup = store
+    ? setupLiveIfs(fragment, context, store, render, handlers)
+    : () => {};
+
+  return function cleanup() {
+    modelCleanup();
+    bindingsCleanup();
+    showCleanup();
+    liveForCleanup();
+    liveCleanup();
+  };
+}
+
+/**
+ * Fetches a template, renders it, and mounts it to a DOM target.
+ * If called again on the same target: old cleanup runs, content cleared,
+ * new content mounted (page/component transition).
+ *
+ * @param {string}                         templateName
+ * @param {Object}                         context
+ * @param {Element}                        target
+ * @param {import('./store.js').Store|null} store
+ * @param {{
+ *   handlers?: Object<string, function(Event, Element): void>,
+ *   beforeRender?: function(Object, import('./store.js').Store): void,
+ *   afterRender?:  function(Element, import('./store.js').Store): void
+ * }} [options={}]
+ *   handlers: event delegation (bindings-events.js). Omit for zero cost.
+ *   beforeRender(context, store): called BEFORE the render pipeline.
+ *   afterRender(rootEl, store):   called AFTER content is appended to target.
+ *   Both lifecycle hooks are optional and backward-compatible.
+ * @returns {function(): void} cleanup
+ */
+export function mount(templateName, context, target, store, options = {}) {
+  // If already mounted on this target: cancel old subscriptions and clear content
+  const previous = mountedTargets.get(target);
+  if (previous) {
+    previous.cleanup();
+    // textContent = '' removes all child nodes (faster than innerHTML, no XSS risk)
+    target.textContent = '';
+  }
+
+  // 2e: beforeRender lifecycle hook
+  if (typeof options.beforeRender === 'function') {
+    options.beforeRender(context, store);
+  }
+
+  const fragment = getTemplate(templateName);
+  if (!fragment) {
+    const available = Array.from(document.querySelectorAll('template[id^="tpl-"]'))
+      .map((t) => t.id.slice(4));
+    errors.mountTemplateNotFound(templateName, available, target);
+    return () => {};
+  }
+
+  const renderCleanup = render(fragment, context, store, options.handlers);
+  target.appendChild(fragment);
+
+  // 2e: afterRender lifecycle hook (called after content is in the DOM)
+  if (typeof options.afterRender === 'function') {
+    options.afterRender(target, store);
+  }
+
+  // Event delegation: root is target (stable mount-lifetime root -- reactive
+  // inner changes don't affect it, see bindings-events.js).
+  const eventsCleanup = options.handlers
+    ? setupEventBindings(target, store, options.handlers)
+    : () => {};
+
+  const cleanup = function cleanup() {
+    renderCleanup();
+    eventsCleanup();
+  };
+
+  mountedTargets.set(target, { cleanup });
+  return cleanup;
+}
+
+/**
+ * Cancels the reactive bindings on target and clears its content.
+ *
+ * @param {Element} target
+ */
+export function unmount(target) {
+  const entry = mountedTargets.get(target);
+  if (entry) {
+    entry.cleanup();
+    mountedTargets.delete(target);
+  }
+  target.textContent = '';
+}

package/src/loops.js

@@ -0,0 +1,117 @@
+/**
+ * @module loops
+ * @description Statically expands <for each="..." as="..."> lists in the DOM.
+ *
+ * Usage:
+ *   <for each="comments" as="comment">
+ *     <p>${comment.body}</p>
+ *   </for>
+ *
+ * SCOPE DIFFERENCE — contrast with partial isolation:
+ *   - partial: isolated context — only the "data" object is visible, parent is hidden.
+ *   - for:     INHERITED context — parent context is preserved, "as" (and index) are added on top.
+ *   Accessing outer variables (e.g. ${post.title}) inside <for> is natural.
+ *   In a nested <for>, the inner "as" naturally shadows the outer "as" via spread.
+ *
+ * Other rules:
+ *   - Empty array → <for> is removed, nothing is printed (not an error).
+ *   - "each" is not an array → warning + <for> is removed.
+ *   - <for> leaves no trace in the final DOM; only the expanded content remains.
+ *   - Nested <for> is processed recursively; inner <partial>/<if> are ordered by index.js.
+ *   - Reactive <for> (updates on list change) is NOT in this module — it's in bindings.js.
+ *   - Does NOT import conditionals.js or partials.js; orchestration lives in index.js.
+ *   - HTML5: <for/> is not treated as void; use <for ...></for>.
+ */
+
+import { getByPath } from './store.js';
+import { resolveStatic } from './template.js';
+import { errors } from './errors.js';
+import { inLiveBlock } from './shared.js';
+
+
+
+/**
+ * Expands every <for> element under root.
+ * For each array item, <for>'s content is cloned and resolved with the inherited context.
+ *
+ * @param {Element|DocumentFragment} root    - Root to traverse
+ * @param {Object}                   context - Context for path resolution
+ * @returns {void}
+ */
+export function expandLoops(root, context, pipeline = null) {
+  // Copy up front to avoid the live-NodeList problem
+  const fors = Array.from(root.querySelectorAll('for'));
+
+  for (const forEl of fors) {
+    // May already have left the DOM via replaceWith if it was inside an already-processed <for>
+    if (!root.contains(forEl)) continue;
+
+    // data-live → reactive list; left to bindings-loops.js, don't touch here.
+    if (forEl.hasAttribute('data-live')) continue;
+
+    // Also don't touch it if it's inside a not-yet-expanded live-if/live-for block —
+    // the correct (branch/item) context only arrives via renderFn's (render()) call.
+    if (inLiveBlock(forEl)) continue;
+
+    const each      = forEl.getAttribute('each');
+    const as        = forEl.getAttribute('as');
+    const indexAttr = forEl.getAttribute('index'); // optional: 0, 1, 2...
+
+    if (!each || !as) {
+      errors.forMissingAttr(forEl);
+      forEl.remove();
+      continue;
+    }
+
+    const list = getByPath(context, each);
+
+    if (!Array.isArray(list)) {
+      errors.forNotArray(each, list === null ? 'null' : typeof list, forEl);
+      forEl.remove();
+      continue;
+    }
+
+    // Empty array: remove <for>, nothing is printed — this is not an error
+    if (list.length === 0) {
+      forEl.remove();
+      continue;
+    }
+
+    // Store <for>'s content as template nodes; don't mutate the original
+    const templateNodes = Array.from(forEl.childNodes).map((n) => n.cloneNode(true));
+
+    const allNodes = [];
+
+    for (let i = 0; i < list.length; i++) {
+      const item = list[i];
+
+      // Inherited context: UNLIKE partial, the parent context is preserved.
+      // "as" (and "index" if present) is added on top; in a nested for, the
+      // inner "as" naturally shadows the outer "as" via spread.
+      const itemContext = { ...context, [as]: item };
+      if (indexAttr) itemContext[indexAttr] = i;
+
+      // Clone the content nodes independently for each item
+      const frag = document.createDocumentFragment();
+      for (const node of templateNodes) frag.appendChild(node.cloneNode(true));
+
+      // Static ${path} resolution: text nodes + attributes
+      resolveStatic(frag, itemContext);
+
+      // Process inner structural tags.
+      // If pipeline is given (comes from index.js): resolve partial+for+if all in the CORRECT context.
+      // If not (direct call / legacy behavior): only recurse into inner <for>s.
+      if (pipeline) {
+        pipeline(frag, itemContext);
+      } else {
+        expandLoops(frag, itemContext);
+      }
+
+      // Move nodes into allNodes (removed from frag, order preserved)
+      allNodes.push(...Array.from(frag.childNodes));
+    }
+
+    // Replace <for> with all the rendered content; leaves no trace
+    forEl.replaceWith(...allNodes);
+  }
+}

package/src/partials.js

@@ -0,0 +1,158 @@
+/**
+ * @module partials
+ * @description Expands <partial name="..."> elements from templates.
+ *
+ * Data passing — isolation model:
+ *   <partial name="avatar" data="user.profile"></partial>
+ *   - data="user.profile" → resolved via getByPath in the parent context.
+ *   - The resolved object becomes the partial's NEW context; the parent context is INVISIBLE.
+ *   - If data is absent: renders with an empty object {}.
+ *   - Inside the partial, ${name} → the "name" field of the new (resolved) context.
+ *
+ * Extra props — passing multiple fields:
+ *   <partial name="like-button" data="post" action="likeAction" count="likeCount"></partial>
+ *   - Every attribute OTHER THAN "name"/"data" is a PROP: its value (a raw path
+ *     string, NOT WRAPPED in ${...} — same rule as data) is resolved via
+ *     getByPath in the parent context and added ON TOP of data (if present)
+ *     to the partial context (prop wins on collision).
+ *   - The attribute name becomes the context key VERBATIM. Since HTML attribute
+ *     names are normalized to lowercase, multi-word prop names must be written
+ *     in kebab-case (e.g. state-class="x" → context["state-class"], read
+ *     inside the partial as ${state-class} — a single-segment literal key, not a path).
+ *   - If data is not given at all: the context consists only of props (instead of {}).
+ *
+ * Recursive expansion:
+ *   - If a new <partial> appears inside the expanded fragment, it is processed
+ *     recursively with the same context. If MAX_DEPTH (50) is exceeded, a
+ *     warning is issued and expansion stops.
+ *
+ * THE pipeline() CALLBACK (same pattern as loops.js):
+ *   - A partial's OWN template may contain <if>/<for> (e.g. a "verified"
+ *     badge). These must be resolved with the partial's isolated context
+ *     (partialContext) — not the caller's context. expandPartials alone only
+ *     recurses into NESTED <partial>s; it does not process <if>/<for>.
+ *     index.js passes its own pipeline() function (expandPartials→expandLoops→
+ *     processAllIfs) as a callback; this way the partial content goes through
+ *     the full pipeline with the correct (isolated) context. Without a
+ *     pipeline (direct call), only nested <partial>s are recursed — legacy behavior.
+ *
+ * Important:
+ *   - This module does NOT import conditionals.js; orchestration happens in index.js.
+ *   - Reactivity (data-live) is NOT in this module — handled in
+ *     bindings-blocks.js/bindings-loops.js. But if a <partial> is INSIDE a
+ *     not-yet-expanded <if data-live>/<for data-live> block, it is SKIPPED
+ *     here too: otherwise it would be rendered early with the wrong (outer)
+ *     context — the correct (branch/item) context is only known by
+ *     setupLiveIfs/setupLiveFors's renderFn call.
+ *   - For the same reason, if a <partial> is INSIDE a not-yet-expanded
+ *     ordinary (non-data-live) <for>, it is also SKIPPED: since expandPartials
+ *     runs BEFORE expandLoops in the same pass, the "as" variable does not yet
+ *     exist in context. The correct (item) context is supplied by
+ *     expandLoops's pipeline() call later in the same pass (see inUnexpandedFor).
+ *   - <partial> leaves no trace in the final DOM; only the expanded content remains.
+ *   - HTML5: <partial/> is not treated as void; use <partial ...></partial>.
+ */
+
+import { getByPath } from './store.js';
+import { renderTemplate } from './template.js';
+import { errors } from './errors.js';
+import { inLiveBlock, inUnexpandedFor } from './shared.js';
+
+/** Maximum recursion depth against infinite loops. */
+const MAX_DEPTH = 50;
+const UNSAFE_PROP_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
+
+
+
+/**
+ * Expands every <partial> element under root.
+ * Recurses up to MAX_DEPTH if a new <partial> appears inside the expanded fragment.
+ *
+ * @param {Element|DocumentFragment} root    - Root to traverse
+ * @param {Object}                   context - Parent context (for resolving the data path)
+ * @param {number}                   [depth=0] - Recursion depth (internal)
+ * @param {function(DocumentFragment, Object, number): void} [pipeline=null]
+ *   If given (comes from index.js): the partial content is processed with
+ *   this callback (the full if/for/partial pipeline) in partialContext.
+ *   If not: only nested <partial>s are recursed (legacy/standalone call behavior).
+ * @returns {void}
+ */
+export function expandPartials(root, context, depth = 0, pipeline = null) {
+  // Grab all <partial>s at once; don't traverse a live list
+  const partials = Array.from(root.querySelectorAll('partial'));
+
+  if (depth >= MAX_DEPTH) {
+    // Warning and returning is NOT enough: if unprocessed <partial>s remain in
+    // the DOM, the caller's (index.js) hasSpecialTags/while loop (which uses
+    // the pipeline callback) would think "there's still work" and retry —
+    // hitting the depth limit again on every attempt. This causes an
+    // infinite/exponentially growing amount of work. So the remaining
+    // <partial>s are removed (degrade gracefully).
+    if (partials.length > 0) {
+      errors.partialDepthLimit(MAX_DEPTH, root);
+      for (const el of partials) el.remove();
+    }
+    return;
+  }
+
+  for (const partialEl of partials) {
+    // May already have left the DOM via replaceWith if it was inside an already-processed partial
+    if (!root.contains(partialEl)) continue;
+
+    // Don't touch it if it's inside a live-if/live-for — the correct context
+    // will already be supplied per branch/item by renderFn (render()).
+    if (inLiveBlock(partialEl)) continue;
+
+    // Also don't touch it if it's inside a not-yet-expanded ordinary <for> —
+    // the "as" variable isn't in context yet; the correct context will be
+    // supplied by expandLoops's pipeline() call in the same pass (see inUnexpandedFor).
+    if (inUnexpandedFor(partialEl)) continue;
+
+    const name = partialEl.getAttribute('name');
+    if (!name) {
+      errors.partialMissingName(partialEl);
+      partialEl.remove();
+      continue;
+    }
+
+    // data attribute -> resolve in parent context -> base of partial's isolated context
+    const dataPath = partialEl.getAttribute('data');
+    const baseContext = dataPath ? (getByPath(context, dataPath) ?? {}) : {};
+
+    // Extra props: attributes OTHER THAN "name", "data", and any "data-*" are props.
+    // 2f rule: data-* attributes are reserved for the lime-csr engine (data-model,
+    // data-text, etc.) and CANNOT be prop names. Non-data-* attrs override the base
+    // context key of the same name (prop wins over data default on collision).
+    const partialContext = { ...baseContext };
+    for (const attr of Array.from(partialEl.attributes)) {
+      if (attr.name === 'name' || attr.name === 'data') continue;
+      if (attr.name.startsWith('data-')) continue; // 2f: reserved for engine
+      if (UNSAFE_PROP_NAMES.has(attr.name)) continue;
+      partialContext[attr.name] = getByPath(context, attr.value);
+    }
+
+    // renderTemplate: finds the template, clones it, resolves ${path}, returns a fragment
+    const fragment = renderTemplate(name, partialContext);
+
+    if (!fragment) {
+      const available = Array.from(document.querySelectorAll('template[id^="tpl-"]'))
+        .map((t) => t.id.slice(4));
+      errors.partialNotFound(name, available, partialEl);
+      partialEl.remove();
+      continue;
+    }
+
+    // Process the expanded fragment with the partial's own (isolated) context.
+    // If pipeline is given: the full if/for/partial pipeline (resolves
+    // <if>/<for> too, with the correct context). Otherwise only nested
+    // <partial>s are recursed.
+    if (pipeline) {
+      pipeline(fragment, partialContext, depth + 1);
+    } else {
+      expandPartials(fragment, partialContext, depth + 1);
+    }
+
+    // Replace the <partial> element with the processed fragment — leaves no trace
+    partialEl.replaceWith(fragment);
+  }
+}