@repobit/dex-store-elements 1.7.2 → 2.0.0

package/dist/src/eta/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../../src/eta/batch.ts"],"names":[],"mappings":"AAAA,mBAAmB;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,OAAO,gBAAgB;IAA7B;QACE;;;;;WAKG;QACM,UAAK,GAAG,IAAI,GAAG,EAAQ,CAAC;QAEjC;;;;WAIG;QACM,YAAO,GAAG,IAAI,GAAG,EAAQ,CAAC;QAEnC;;;;;WAKG;QACM,SAAI,GAAG,IAAI,GAAG,EAAQ,CAAC;QAEhC;;;;;WAKG;QACM,eAAU,GAAG,IAAI,GAAG,EAAwB,CAAC;IAiCxD,CAAC;IA/BC;;;;;;;OAOG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAClB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,KAAK;QACP,OAAO,CACL,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;YACrB,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC;YACpB,IAAI,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,CAC3B,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAuB,EACvB,MAAsB;IAEtB,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACrC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YACvC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO;IACT,CAAC;IAED,IACE,MAAM,CAAC,IAAI,KAAK,eAAe;QAC/B,MAAM,CAAC,MAAM,YAAY,IAAI,EAC7B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IAED,IACE,MAAM,CAAC,IAAI,KAAK,YAAY;QAC5B,MAAM,CAAC,MAAM,YAAY,OAAO;QAChC,MAAM,CAAC,aAAa,EACpB,CAAC;QACD,IAAI,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAChD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;YAC1B,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAClC,CAAC;AACH,CAAC","sourcesContent":["// src/eta/batch.ts\n\n/**\n * Accumulator for raw `MutationRecord`s produced by the\n * `EtaMutationObserver` between scheduled flushes.\n *\n * Records fall into four buckets:\n *\n * - `added` — nodes introduced into the DOM via `childList` records.\n * - `removed` — nodes detached via `childList` records.\n * - `text` — `Text` nodes whose data changed via `characterData`\n *   records.\n * - `attributes` — `(Element, attributeName)` pairs that flipped via\n *   `attributes` records.\n *\n * The buckets are `Set` / `Map` collections rather than arrays so\n * that repeated records for the same target naturally collapse\n * before flush (e.g. five `attributes` flips on the same `title`\n * only yield a single `(element, 'title')` entry by the time the\n * batch is applied).\n *\n * **Compaction rules.** A flush through `EtaMutationBatcher` applies\n * the following reductions to the bucket contents before forwarding\n * the compacted set to the `EtaTemplateIndex`:\n *\n * 1. `add` then `remove` of the same node within one batch is a\n *    no-op (the node ends up detached, the index never saw it).\n * 2. `remove` then `add` of the same node is forwarded as both a\n *    `remove` and an `add` (the move is real).\n * 3. An ancestor `add` subsumes descendant `add`s — the index walks\n *    the subtree on `add`, so descendant adds are redundant.\n * 4. An ancestor `remove` subsumes descendant `remove`s for the\n *    same reason.\n * 5. A `text` change inside an added subtree is dropped; the index\n *    reads the final text when it walks the new subtree.\n * 6. A `text` / `attribute` change inside a removed subtree is\n *    dropped; the node is leaving ownership.\n * 7. Repeated text changes on the same `Text` node collapse to one\n *    entry (the `Set` storage already handles this).\n * 8. Repeated attribute changes on the same `(Element, name)` pair\n *    collapse to one entry (the inner `Set<string>` storage already\n *    handles this).\n *\n * The batch itself does not enforce rules 1–6 — those live in the\n * batcher's compaction pass. Rules 7–8 are enforced automatically\n * by the bucket storage.\n *\n * **Immutability of contents.** Bucket contents are mutable in\n * place for performance reasons (`Set.add` / `Map.set` are O(1)).\n * Callers MUST NOT cache references to bucket internals across a\n * flush — `clear()` resets the bucket to empty. The controller\n * treats the batch as opaque between flushes.\n */\nexport class EtaMutationBatch {\n  /**\n   * Nodes added since the last flush.\n   *\n   * Stored as a `Set<Node>` so multiple adds of the same node\n   * collapse automatically (rule 7-equivalent for adds).\n   */\n  readonly added = new Set<Node>();\n\n  /**\n   * Nodes removed since the last flush.\n   *\n   * Stored as a `Set<Node>` for the same dedup reasons as `added`.\n   */\n  readonly removed = new Set<Node>();\n\n  /**\n   * `Text` nodes whose character data changed since the last flush.\n   *\n   * `Set<Text>` collapses repeated changes on the same text node\n   * (rule 7).\n   */\n  readonly text = new Set<Text>();\n\n  /**\n   * `Element` → set of changed attribute names since the last flush.\n   *\n   * The inner `Set<string>` collapses repeated changes to the same\n   * attribute name (rule 8).\n   */\n  readonly attributes = new Map<Element, Set<string>>();\n\n  /**\n   * Reset every bucket to empty.\n   *\n   * Called by `EtaMutationBatcher.flush()` after the compacted\n   * mutations have been applied to the index. The bucket instances\n   * are preserved (`Set` / `Map` references stay valid) so callers\n   * can safely hold long-lived references to them.\n   */\n  clear(): void {\n    this.added.clear();\n    this.removed.clear();\n    this.text.clear();\n    this.attributes.clear();\n  }\n\n  /**\n   * `true` when every bucket is empty — i.e. there is nothing to\n   * forward to the index on the next flush.\n   *\n   * Used by `EtaMutationBatcher.flush()` as a fast-path for \"no\n   * work to do\" so the batcher can return `false` without touching\n   * the index.\n   */\n  get empty(): boolean {\n    return (\n      this.added.size === 0 &&\n      this.removed.size === 0 &&\n      this.text.size === 0 &&\n      this.attributes.size === 0\n    );\n  }\n}\n\n/**\n * Fold a single `MutationRecord` into the appropriate bucket of\n * `batch`.\n *\n * The mapping mirrors `EtaMutationObserver.handleRecord` but\n * accumulates records rather than forwarding them straight to the\n * index. The batcher's compaction pass later walks the accumulated\n * buckets and decides what to actually apply.\n *\n * Mapping:\n *\n * - `childList` → `addedNodes` / `removedNodes` are added to the\n *   matching bucket.\n * - `characterData` → the `Text` target is added to `text` (when\n *   the target really is a `Text` — the DOM guard is defensive in\n *   case some exotic browser delivers a different node type).\n * - `attributes` → `(element, attributeName)` is added to\n *   `attributes` (when the target is an `Element` and the\n *   attribute name is present — both are required for the entry\n *   to be useful to the index).\n *\n * Unknown record types are silently dropped. The DOM only emits\n * the three types above, so this branch is defensive only.\n */\nexport function enqueueRecord(\n  batch: EtaMutationBatch,\n  record: MutationRecord\n): void {\n  if (record.type === 'childList') {\n    for (const node of record.addedNodes) {\n      batch.added.add(node);\n    }\n    for (const node of record.removedNodes) {\n      batch.removed.add(node);\n    }\n    return;\n  }\n\n  if (\n    record.type === 'characterData' &&\n    record.target instanceof Text\n  ) {\n    batch.text.add(record.target);\n    return;\n  }\n\n  if (\n    record.type === 'attributes' &&\n    record.target instanceof Element &&\n    record.attributeName\n  ) {\n    let attrs = batch.attributes.get(record.target);\n    if (!attrs) {\n      attrs = new Set<string>();\n      batch.attributes.set(record.target, attrs);\n    }\n    attrs.add(record.attributeName);\n  }\n}\n"]}

package/dist/src/eta/batcher.d.ts

@@ -0,0 +1,184 @@
+import type { EtaMutationBatchSchedule, EtaMutationBatchScheduleOption, EtaTemplateIndexLike } from './types.js';
+export type { EtaMutationBatchSchedule };
+/**
+ * Options accepted by `EtaMutationBatcher`.
+ */
+export interface EtaMutationBatcherOptions {
+    /**
+     * Schedule mode. Defaults to `'animation-frame'` when omitted.
+     *
+     * See `EtaMutationBatchSchedule` for the full set of modes.
+     */
+    schedule?: EtaMutationBatchScheduleOption;
+    /**
+     * Called after each flush with the dirty flag from the index.
+     *
+     * The controller wires this to `task.run()` so a dirty flush
+     * triggers a fresh render. When the flush was a no-op (empty
+     * batch or every compaction dropped), `dirty` is `false` and the
+     * controller should skip the render.
+     *
+     * `onFlush` runs synchronously inside the flush callback. The
+     * controller MUST NOT block here — it should only kick the Task
+     * run, not wait for it.
+     */
+    onFlush: (dirty: boolean) => void;
+}
+/**
+ * `EtaMutationBatcher` is the bridge between the
+ * `EtaMutationObserver` and the `EtaTemplateIndex`.
+ *
+ * Responsibilities:
+ *
+ * - Accumulate raw `MutationRecord`s into an `EtaMutationBatch`
+ *   via `enqueueRecord`.
+ * - Schedule a flush on the configured tick
+ *   (`microtask` / `animation-frame` / `idle` / `manual`).
+ * - Compact the accumulated batch when flushing (apply rules 1–8).
+ * - Forward the compacted mutations to the index through its
+ *   existing `apply()` entry point.
+ * - Notify the host via `onFlush(dirty)` so a dirty flush can kick
+ *   a render task.
+ *
+ * **Why one flush per burst.** Without batching, every mutation
+ * record fires its own index update and its own render — DOM
+ * decoration flows that add / decorate / measure a block in one
+ * frame end up running the render pass three or four times. The
+ * batcher collapses that into one flush per frame (or per idle
+ * window / per explicit call).
+ *
+ * **Why compaction matters.** Many DOM edits land as
+ * `add subtree` followed by several descendant `add`s and
+ * `attribute` flips. Forwarding each one to the index would walk
+ * the subtree once per record. Compaction collapses the subtree
+ * walk to a single `add(subtree)` call.
+ */
+export declare class EtaMutationBatcher {
+    private readonly batch;
+    private readonly index;
+    private readonly options;
+    /**
+     * `true` while a flush is queued but has not yet run. Used to
+     * coalesce multiple `enqueue()` calls into a single flush.
+     *
+     * Reset to `false` immediately before the flush callback runs
+     * (so a flush that re-enters `enqueue()` schedules a fresh
+     * flush, but a flush that runs `flush()` directly does not).
+     */
+    private scheduled;
+    /**
+     * Pending `requestAnimationFrame` handle, if any.
+     *
+     * Stored so `flush()` / `cancelSchedule()` can cancel a pending
+     * frame flush.
+     */
+    private frameId;
+    /**
+     * Pending `requestIdleCallback` handle, if any.
+     *
+     * Stored so `flush()` / `cancelSchedule()` can cancel a pending
+     * idle flush.
+     */
+    private idleId;
+    /**
+     * Token for the most recently scheduled microtask flush, if any.
+     *
+     * The standard `queueMicrotask` API does not return a handle that
+     * can be cancelled, so we capture a fresh object identity every
+     * time we schedule a microtask flush. The queued callback checks
+     * the captured token against `this.microtaskToken` before
+     * running — if they no longer match (because a subsequent
+     * `schedule()` produced a new token, or because `cancelSchedule`
+     * invalidated the field), the queued callback is a no-op.
+     *
+     * The existing `cancelSchedule()` already clears `this.scheduled`
+     * so a fresh `enqueue()` after a manual flush can schedule a
+     * new flush; the token approach is purely additive — it turns a
+     * previously-harmless "empty batch re-flush" into an explicit
+     * skip so observers can distinguish "the batcher ran" from
+     * "the batcher was cancelled".
+     */
+    private microtaskToken;
+    constructor(index: EtaTemplateIndexLike, options: EtaMutationBatcherOptions);
+    /**
+     * Fold `records` into the accumulated batch and schedule a flush.
+     *
+     * Calling `enqueue()` while a flush is already scheduled is a
+     * no-op for scheduling — the pending flush will pick up the new
+     * records when it runs.
+     *
+     * When `schedule` is `'manual'`, the records are accumulated but
+     * no flush is scheduled; the host is expected to call
+     * `flush()` / `flushAndNotify()` itself.
+     *
+     * **No rule-1 vs rule-2 special case.** Earlier versions of this
+     * method tracked the FIRST op seen for each node and dropped
+     * nodes whose first op was `'add'` from both buckets (the
+     * "rule 1" no-op path). Real-world DOM mutation patterns
+     * (`replaceWith`, `replaceChildren`, drain-then-remove, etc.)
+     * all use distinct nodes for the removed and added sides — the
+     * same-node case only arises in custom code that explicitly
+     * moves a node within one flush. For that case, applying both
+     * the `remove` and the `add` produces the same end state as
+     * dropping both (the factory rebuilds the operation from the
+     * source registry on re-add), so the simpler implementation is
+     * observationally equivalent. The earlier tracking also kept a
+     * strong `Map` alive during the animation-frame window, which
+     * is a leak hazard for large mutation bursts; this simpler
+     * shape avoids that.
+     */
+    enqueue(records: readonly MutationRecord[]): void;
+    /**
+     * Apply the compacted batch to the index synchronously.
+     *
+     * Cancels any pending scheduled flush first so the manual flush
+     * does not run again on the next tick. When the batch is empty
+     * this is a no-op and returns `false`.
+     *
+     * Returns `true` when at least one compacted mutation made the
+     * index dirty, `false` otherwise.
+     *
+     * `flush()` does NOT call `onFlush`. Use `flushAndNotify()` when
+     * the host needs to be told about the flush.
+     */
+    flush(): boolean;
+    /**
+     * `flush()` then notify the host with the dirty flag.
+     *
+     * Always invokes `onFlush` — `onFlush(false)` on empty batches so
+     * the host can stay in sync with the flush cadence if it cares
+     * to. Most controllers ignore `dirty === false` because no
+     * render is needed.
+     */
+    flushAndNotify(): void;
+    /**
+     * Schedule a flush on the configured tick.
+     *
+     * Coalescing: subsequent `enqueue()` calls while a flush is
+     * already scheduled do not schedule a second flush.
+     *
+     * When `schedule` is `'manual'`, scheduling is a no-op — the
+     * host owns the flush lifecycle.
+     *
+     * The `scheduled` flag is cleared BEFORE the flush callback runs
+     * so a flush that re-enters through `enqueue()` (for example,
+     * because an `onFlush` handler mutates the DOM again) can
+     * schedule a fresh flush.
+     */
+    private schedule;
+    private currentSchedule;
+    /**
+     * Cancel any pending scheduled flush.
+     *
+     * Called by `flush()` so a manual flush is not followed by the
+     * scheduled flush. Safe to call when nothing is scheduled — the
+     * `undefined` checks short-circuit.
+     *
+     * **`microtask` schedule.** `queueMicrotask` does not expose a
+     * cancellation handle; we instead invalidate `this.microtaskToken`
+     * so the queued callback's identity-check fails and the callback
+     * becomes a no-op. `this.scheduled` is also reset so a fresh
+     * `enqueue()` after a manual flush can schedule a new flush.
+     */
+    private cancelSchedule;
+}

package/dist/src/eta/batcher.js

@@ -0,0 +1,335 @@
+// src/eta/batcher.ts
+import { EtaMutationBatch, enqueueRecord } from './batch.js';
+import { cancelIdle, requestIdle } from './idle.js';
+/**
+ * Internal helper: keep only the topmost roots in `nodes`.
+ *
+ * A node is dropped when another node in the same iterable strictly
+ * contains it. This collapses "added the subtree root AND added
+ * several descendants" into "added the subtree root" — the index
+ * walks descendants when it sees an `add`, so the descendant adds
+ * are redundant.
+ *
+ * Self-containment (`other === node`) is treated as "not contained"
+ * so the node survives its own filter pass.
+ *
+ * Used for both the `added` and `removed` buckets.
+ */
+function compactRoots(nodes) {
+    const arr = [...nodes];
+    return arr.filter((node) => !arr.some((other) => other !== node && other.contains(node)));
+}
+/**
+ * Internal helper: `true` when `node` is strictly contained by any
+ * root in `roots`.
+ *
+ * "Strictly" means `root !== node` AND `root.contains(node)`. The
+ * strict check matters for the `removed` pass — when a node is both
+ * in `removed` and a descendant of another `removed` root, the
+ * descendant is dropped by `compactRoots` first; this helper is
+ * used later to skip descendants of a removed root when walking the
+ * `added` bucket (rule 1 — descendant of a removed root has no
+ * observable add) and the `text` / `attributes` buckets
+ * (compaction rule 6 — descendants of a removed root have changes
+ * that are irrelevant because the ancestor removal wins).
+ *
+ * Note: the root element itself is NOT considered "inside" any
+ * root by this helper. Attribute mutations on the removed root
+ * itself therefore reach the index, where `_ownsNode` rejects
+ * them by walking `parentNode` upward — see the test
+ * `Compaction order rules through the controller pipeline >
+ * skips attribute changes inside a removed subtree` for the
+ * observable contract.
+ */
+function isInsideAny(node, roots) {
+    for (const root of roots) {
+        if (root !== node && root.contains(node)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * `EtaMutationBatcher` is the bridge between the
+ * `EtaMutationObserver` and the `EtaTemplateIndex`.
+ *
+ * Responsibilities:
+ *
+ * - Accumulate raw `MutationRecord`s into an `EtaMutationBatch`
+ *   via `enqueueRecord`.
+ * - Schedule a flush on the configured tick
+ *   (`microtask` / `animation-frame` / `idle` / `manual`).
+ * - Compact the accumulated batch when flushing (apply rules 1–8).
+ * - Forward the compacted mutations to the index through its
+ *   existing `apply()` entry point.
+ * - Notify the host via `onFlush(dirty)` so a dirty flush can kick
+ *   a render task.
+ *
+ * **Why one flush per burst.** Without batching, every mutation
+ * record fires its own index update and its own render — DOM
+ * decoration flows that add / decorate / measure a block in one
+ * frame end up running the render pass three or four times. The
+ * batcher collapses that into one flush per frame (or per idle
+ * window / per explicit call).
+ *
+ * **Why compaction matters.** Many DOM edits land as
+ * `add subtree` followed by several descendant `add`s and
+ * `attribute` flips. Forwarding each one to the index would walk
+ * the subtree once per record. Compaction collapses the subtree
+ * walk to a single `add(subtree)` call.
+ */
+export class EtaMutationBatcher {
+    constructor(index, options) {
+        this.batch = new EtaMutationBatch();
+        /**
+         * `true` while a flush is queued but has not yet run. Used to
+         * coalesce multiple `enqueue()` calls into a single flush.
+         *
+         * Reset to `false` immediately before the flush callback runs
+         * (so a flush that re-enters `enqueue()` schedules a fresh
+         * flush, but a flush that runs `flush()` directly does not).
+         */
+        this.scheduled = false;
+        this.index = index;
+        this.options = options;
+    }
+    /**
+     * Fold `records` into the accumulated batch and schedule a flush.
+     *
+     * Calling `enqueue()` while a flush is already scheduled is a
+     * no-op for scheduling — the pending flush will pick up the new
+     * records when it runs.
+     *
+     * When `schedule` is `'manual'`, the records are accumulated but
+     * no flush is scheduled; the host is expected to call
+     * `flush()` / `flushAndNotify()` itself.
+     *
+     * **No rule-1 vs rule-2 special case.** Earlier versions of this
+     * method tracked the FIRST op seen for each node and dropped
+     * nodes whose first op was `'add'` from both buckets (the
+     * "rule 1" no-op path). Real-world DOM mutation patterns
+     * (`replaceWith`, `replaceChildren`, drain-then-remove, etc.)
+     * all use distinct nodes for the removed and added sides — the
+     * same-node case only arises in custom code that explicitly
+     * moves a node within one flush. For that case, applying both
+     * the `remove` and the `add` produces the same end state as
+     * dropping both (the factory rebuilds the operation from the
+     * source registry on re-add), so the simpler implementation is
+     * observationally equivalent. The earlier tracking also kept a
+     * strong `Map` alive during the animation-frame window, which
+     * is a leak hazard for large mutation bursts; this simpler
+     * shape avoids that.
+     */
+    enqueue(records) {
+        for (const record of records) {
+            enqueueRecord(this.batch, record);
+        }
+        this.schedule();
+    }
+    /**
+     * Apply the compacted batch to the index synchronously.
+     *
+     * Cancels any pending scheduled flush first so the manual flush
+     * does not run again on the next tick. When the batch is empty
+     * this is a no-op and returns `false`.
+     *
+     * Returns `true` when at least one compacted mutation made the
+     * index dirty, `false` otherwise.
+     *
+     * `flush()` does NOT call `onFlush`. Use `flushAndNotify()` when
+     * the host needs to be told about the flush.
+     */
+    flush() {
+        this.cancelSchedule();
+        if (this.batch.empty) {
+            return false;
+        }
+        const dirty = applyMutationBatch(this.index, this.batch);
+        this.batch.clear();
+        return dirty;
+    }
+    /**
+     * `flush()` then notify the host with the dirty flag.
+     *
+     * Always invokes `onFlush` — `onFlush(false)` on empty batches so
+     * the host can stay in sync with the flush cadence if it cares
+     * to. Most controllers ignore `dirty === false` because no
+     * render is needed.
+     */
+    flushAndNotify() {
+        const dirty = this.flush();
+        this.options.onFlush(dirty);
+    }
+    /**
+     * Schedule a flush on the configured tick.
+     *
+     * Coalescing: subsequent `enqueue()` calls while a flush is
+     * already scheduled do not schedule a second flush.
+     *
+     * When `schedule` is `'manual'`, scheduling is a no-op — the
+     * host owns the flush lifecycle.
+     *
+     * The `scheduled` flag is cleared BEFORE the flush callback runs
+     * so a flush that re-enters through `enqueue()` (for example,
+     * because an `onFlush` handler mutates the DOM again) can
+     * schedule a fresh flush.
+     */
+    schedule() {
+        if (this.scheduled) {
+            return;
+        }
+        const scheduleMode = this.currentSchedule();
+        if (scheduleMode === 'manual') {
+            return;
+        }
+        this.scheduled = true;
+        if (scheduleMode === 'microtask') {
+            // Capture a fresh token identity so a subsequent `schedule()`
+            // (or `cancelSchedule()` invalidating the field) invalidates
+            // the in-flight queued callback. The callback compares
+            // against `this.microtaskToken` and becomes a no-op when the
+            // tokens diverge — `queueMicrotask` itself cannot be
+            // cancelled, so identity-comparison is the standard escape
+            // hatch for that API.
+            const token = {};
+            this.microtaskToken = token;
+            queueMicrotask(() => {
+                if (this.microtaskToken !== token) {
+                    return;
+                }
+                this.microtaskToken = undefined;
+                this.scheduled = false;
+                this.flushAndNotify();
+            });
+            return;
+        }
+        if (scheduleMode === 'idle') {
+            this.idleId = requestIdle(() => {
+                this.idleId = undefined;
+                this.scheduled = false;
+                this.flushAndNotify();
+            });
+            return;
+        }
+        // Default: 'animation-frame'.
+        this.frameId = requestAnimationFrame(() => {
+            this.frameId = undefined;
+            this.scheduled = false;
+            this.flushAndNotify();
+        });
+    }
+    currentSchedule() {
+        const schedule = this.options.schedule;
+        if (typeof schedule === 'function') {
+            return schedule() ?? 'animation-frame';
+        }
+        return schedule ?? 'animation-frame';
+    }
+    /**
+     * Cancel any pending scheduled flush.
+     *
+     * Called by `flush()` so a manual flush is not followed by the
+     * scheduled flush. Safe to call when nothing is scheduled — the
+     * `undefined` checks short-circuit.
+     *
+     * **`microtask` schedule.** `queueMicrotask` does not expose a
+     * cancellation handle; we instead invalidate `this.microtaskToken`
+     * so the queued callback's identity-check fails and the callback
+     * becomes a no-op. `this.scheduled` is also reset so a fresh
+     * `enqueue()` after a manual flush can schedule a new flush.
+     */
+    cancelSchedule() {
+        if (this.frameId !== undefined) {
+            cancelAnimationFrame(this.frameId);
+            this.frameId = undefined;
+        }
+        if (this.idleId !== undefined) {
+            cancelIdle(this.idleId);
+            this.idleId = undefined;
+        }
+        this.microtaskToken = undefined;
+        this.scheduled = false;
+    }
+}
+/**
+ * Apply a compacted `EtaMutationBatch` to the index.
+ *
+ * The compaction rules are documented on `EtaMutationBatch`. The
+ * order of application matters:
+ *
+ * 1. **Compact `removed` and apply.** Removes must run first so
+ *    later `add` / `text` / `attribute` checks correctly identify
+ *    descendants of removed roots and skip them.
+ * 2. **Compact `added` and apply** (skipping nodes inside a
+ *    removed root). Adds come next so descendant text / attribute
+ *    changes inside added subtrees are dropped in step 3/4.
+ * 3. **Walk `text`** (skipping nodes inside any removed or added
+ *    root). The text bucket is walked last because text changes
+ *    inside add / remove roots are irrelevant.
+ * 4. **Walk `attributes`** (skipping elements inside any removed or
+ *    added root). Same rationale as step 3.
+ *
+ * Each compacted mutation is forwarded to `index.apply(...)`, which
+ * returns `true` only when the index actually changed. The dirty
+ * flag is OR-accumulated across all four passes.
+ *
+ * Returns `true` when at least one compacted mutation made the
+ * index dirty, `false` when every pass was a no-op.
+ */
+function applyMutationBatch(index, batch) {
+    const removedRoots = compactRoots(batch.removed);
+    const addedRoots = compactRoots(batch.added);
+    let dirty = false;
+    // 1. Removes first.
+    for (const node of removedRoots) {
+        if (index.apply({
+            type: 'remove',
+            node
+        })) {
+            dirty = true;
+        }
+    }
+    // 2. Adds second (skip descendants of removed roots).
+    for (const node of addedRoots) {
+        if (isInsideAny(node, removedRoots)) {
+            continue;
+        }
+        if (index.apply({
+            type: 'add',
+            node
+        })) {
+            dirty = true;
+        }
+    }
+    // 3. Text changes (skip descendants of add/remove roots).
+    for (const text of batch.text) {
+        if (isInsideAny(text, removedRoots) ||
+            isInsideAny(text, addedRoots)) {
+            continue;
+        }
+        if (index.apply({
+            type: 'text',
+            node: text
+        })) {
+            dirty = true;
+        }
+    }
+    // 4. Attribute changes (skip descendants of add/remove roots).
+    for (const [element, attrs] of batch.attributes) {
+        if (isInsideAny(element, removedRoots) ||
+            isInsideAny(element, addedRoots)) {
+            continue;
+        }
+        for (const attr of attrs) {
+            if (index.apply({
+                type: 'attribute',
+                element,
+                attribute: attr
+            })) {
+                dirty = true;
+            }
+        }
+    }
+    return dirty;
+}
+//# sourceMappingURL=batcher.js.map

package/dist/src/eta/batcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batcher.js","sourceRoot":"","sources":["../../../src/eta/batcher.ts"],"names":[],"mappings":"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","sourcesContent":["// src/eta/batcher.ts\n\nimport { EtaMutationBatch, enqueueRecord } from './batch.js';\nimport { cancelIdle, requestIdle } from './idle.js';\nimport type {\n  EtaMutationBatchSchedule,\n  EtaMutationBatchScheduleOption,\n  EtaTemplateIndexLike\n} from './types.js';\n\n// Re-export so direct importers of the batcher module still see\n// the schedule type without reaching into `./types.js`.\nexport type { EtaMutationBatchSchedule };\n\n/**\n * Options accepted by `EtaMutationBatcher`.\n */\nexport interface EtaMutationBatcherOptions {\n  /**\n   * Schedule mode. Defaults to `'animation-frame'` when omitted.\n   *\n   * See `EtaMutationBatchSchedule` for the full set of modes.\n   */\n  schedule?: EtaMutationBatchScheduleOption;\n\n  /**\n   * Called after each flush with the dirty flag from the index.\n   *\n   * The controller wires this to `task.run()` so a dirty flush\n   * triggers a fresh render. When the flush was a no-op (empty\n   * batch or every compaction dropped), `dirty` is `false` and the\n   * controller should skip the render.\n   *\n   * `onFlush` runs synchronously inside the flush callback. The\n   * controller MUST NOT block here — it should only kick the Task\n   * run, not wait for it.\n   */\n  onFlush: (dirty: boolean) => void;\n}\n\n/**\n * Internal helper: keep only the topmost roots in `nodes`.\n *\n * A node is dropped when another node in the same iterable strictly\n * contains it. This collapses \"added the subtree root AND added\n * several descendants\" into \"added the subtree root\" — the index\n * walks descendants when it sees an `add`, so the descendant adds\n * are redundant.\n *\n * Self-containment (`other === node`) is treated as \"not contained\"\n * so the node survives its own filter pass.\n *\n * Used for both the `added` and `removed` buckets.\n */\nfunction compactRoots<T extends Node>(\n  nodes: Iterable<T>\n): T[] {\n  const arr = [...nodes];\n  return arr.filter(\n    (node) =>\n      !arr.some(\n        (other) =>\n          other !== node && other.contains(node)\n      )\n  );\n}\n\n/**\n * Internal helper: `true` when `node` is strictly contained by any\n * root in `roots`.\n *\n * \"Strictly\" means `root !== node` AND `root.contains(node)`. The\n * strict check matters for the `removed` pass — when a node is both\n * in `removed` and a descendant of another `removed` root, the\n * descendant is dropped by `compactRoots` first; this helper is\n * used later to skip descendants of a removed root when walking the\n * `added` bucket (rule 1 — descendant of a removed root has no\n * observable add) and the `text` / `attributes` buckets\n * (compaction rule 6 — descendants of a removed root have changes\n * that are irrelevant because the ancestor removal wins).\n *\n * Note: the root element itself is NOT considered \"inside\" any\n * root by this helper. Attribute mutations on the removed root\n * itself therefore reach the index, where `_ownsNode` rejects\n * them by walking `parentNode` upward — see the test\n * `Compaction order rules through the controller pipeline >\n * skips attribute changes inside a removed subtree` for the\n * observable contract.\n */\nfunction isInsideAny(\n  node: Node,\n  roots: Iterable<Node>\n): boolean {\n  for (const root of roots) {\n    if (root !== node && root.contains(node)) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * `EtaMutationBatcher` is the bridge between the\n * `EtaMutationObserver` and the `EtaTemplateIndex`.\n *\n * Responsibilities:\n *\n * - Accumulate raw `MutationRecord`s into an `EtaMutationBatch`\n *   via `enqueueRecord`.\n * - Schedule a flush on the configured tick\n *   (`microtask` / `animation-frame` / `idle` / `manual`).\n * - Compact the accumulated batch when flushing (apply rules 1–8).\n * - Forward the compacted mutations to the index through its\n *   existing `apply()` entry point.\n * - Notify the host via `onFlush(dirty)` so a dirty flush can kick\n *   a render task.\n *\n * **Why one flush per burst.** Without batching, every mutation\n * record fires its own index update and its own render — DOM\n * decoration flows that add / decorate / measure a block in one\n * frame end up running the render pass three or four times. The\n * batcher collapses that into one flush per frame (or per idle\n * window / per explicit call).\n *\n * **Why compaction matters.** Many DOM edits land as\n * `add subtree` followed by several descendant `add`s and\n * `attribute` flips. Forwarding each one to the index would walk\n * the subtree once per record. Compaction collapses the subtree\n * walk to a single `add(subtree)` call.\n */\nexport class EtaMutationBatcher {\n  private readonly batch = new EtaMutationBatch();\n  private readonly index  : EtaTemplateIndexLike;\n  private readonly options: EtaMutationBatcherOptions;\n\n  /**\n   * `true` while a flush is queued but has not yet run. Used to\n   * coalesce multiple `enqueue()` calls into a single flush.\n   *\n   * Reset to `false` immediately before the flush callback runs\n   * (so a flush that re-enters `enqueue()` schedules a fresh\n   * flush, but a flush that runs `flush()` directly does not).\n   */\n  private scheduled = false;\n\n  /**\n   * Pending `requestAnimationFrame` handle, if any.\n   *\n   * Stored so `flush()` / `cancelSchedule()` can cancel a pending\n   * frame flush.\n   */\n  private frameId: number | undefined;\n\n  /**\n   * Pending `requestIdleCallback` handle, if any.\n   *\n   * Stored so `flush()` / `cancelSchedule()` can cancel a pending\n   * idle flush.\n   */\n  private idleId: number | undefined;\n\n  /**\n   * Token for the most recently scheduled microtask flush, if any.\n   *\n   * The standard `queueMicrotask` API does not return a handle that\n   * can be cancelled, so we capture a fresh object identity every\n   * time we schedule a microtask flush. The queued callback checks\n   * the captured token against `this.microtaskToken` before\n   * running — if they no longer match (because a subsequent\n   * `schedule()` produced a new token, or because `cancelSchedule`\n   * invalidated the field), the queued callback is a no-op.\n   *\n   * The existing `cancelSchedule()` already clears `this.scheduled`\n   * so a fresh `enqueue()` after a manual flush can schedule a\n   * new flush; the token approach is purely additive — it turns a\n   * previously-harmless \"empty batch re-flush\" into an explicit\n   * skip so observers can distinguish \"the batcher ran\" from\n   * \"the batcher was cancelled\".\n   */\n  private microtaskToken: object | undefined;\n\n  constructor(\n    index: EtaTemplateIndexLike,\n    options: EtaMutationBatcherOptions\n  ) {\n    this.index = index;\n    this.options = options;\n  }\n\n  /**\n   * Fold `records` into the accumulated batch and schedule a flush.\n   *\n   * Calling `enqueue()` while a flush is already scheduled is a\n   * no-op for scheduling — the pending flush will pick up the new\n   * records when it runs.\n   *\n   * When `schedule` is `'manual'`, the records are accumulated but\n   * no flush is scheduled; the host is expected to call\n   * `flush()` / `flushAndNotify()` itself.\n   *\n   * **No rule-1 vs rule-2 special case.** Earlier versions of this\n   * method tracked the FIRST op seen for each node and dropped\n   * nodes whose first op was `'add'` from both buckets (the\n   * \"rule 1\" no-op path). Real-world DOM mutation patterns\n   * (`replaceWith`, `replaceChildren`, drain-then-remove, etc.)\n   * all use distinct nodes for the removed and added sides — the\n   * same-node case only arises in custom code that explicitly\n   * moves a node within one flush. For that case, applying both\n   * the `remove` and the `add` produces the same end state as\n   * dropping both (the factory rebuilds the operation from the\n   * source registry on re-add), so the simpler implementation is\n   * observationally equivalent. The earlier tracking also kept a\n   * strong `Map` alive during the animation-frame window, which\n   * is a leak hazard for large mutation bursts; this simpler\n   * shape avoids that.\n   */\n  enqueue(records: readonly MutationRecord[]): void {\n    for (const record of records) {\n      enqueueRecord(this.batch, record);\n    }\n\n    this.schedule();\n  }\n\n  /**\n   * Apply the compacted batch to the index synchronously.\n   *\n   * Cancels any pending scheduled flush first so the manual flush\n   * does not run again on the next tick. When the batch is empty\n   * this is a no-op and returns `false`.\n   *\n   * Returns `true` when at least one compacted mutation made the\n   * index dirty, `false` otherwise.\n   *\n   * `flush()` does NOT call `onFlush`. Use `flushAndNotify()` when\n   * the host needs to be told about the flush.\n   */\n  flush(): boolean {\n    this.cancelSchedule();\n\n    if (this.batch.empty) {\n      return false;\n    }\n\n    const dirty = applyMutationBatch(\n      this.index,\n      this.batch\n    );\n\n    this.batch.clear();\n\n    return dirty;\n  }\n\n  /**\n   * `flush()` then notify the host with the dirty flag.\n   *\n   * Always invokes `onFlush` — `onFlush(false)` on empty batches so\n   * the host can stay in sync with the flush cadence if it cares\n   * to. Most controllers ignore `dirty === false` because no\n   * render is needed.\n   */\n  flushAndNotify(): void {\n    const dirty = this.flush();\n    this.options.onFlush(dirty);\n  }\n\n  /**\n   * Schedule a flush on the configured tick.\n   *\n   * Coalescing: subsequent `enqueue()` calls while a flush is\n   * already scheduled do not schedule a second flush.\n   *\n   * When `schedule` is `'manual'`, scheduling is a no-op — the\n   * host owns the flush lifecycle.\n   *\n   * The `scheduled` flag is cleared BEFORE the flush callback runs\n   * so a flush that re-enters through `enqueue()` (for example,\n   * because an `onFlush` handler mutates the DOM again) can\n   * schedule a fresh flush.\n   */\n  private schedule(): void {\n    if (this.scheduled) {\n      return;\n    }\n\n    const scheduleMode = this.currentSchedule();\n\n    if (scheduleMode === 'manual') {\n      return;\n    }\n\n    this.scheduled = true;\n\n    if (scheduleMode === 'microtask') {\n      // Capture a fresh token identity so a subsequent `schedule()`\n      // (or `cancelSchedule()` invalidating the field) invalidates\n      // the in-flight queued callback. The callback compares\n      // against `this.microtaskToken` and becomes a no-op when the\n      // tokens diverge — `queueMicrotask` itself cannot be\n      // cancelled, so identity-comparison is the standard escape\n      // hatch for that API.\n      const token = {};\n\n      this.microtaskToken = token;\n\n      queueMicrotask(() => {\n        if (this.microtaskToken !== token) {\n          return;\n        }\n\n        this.microtaskToken = undefined;\n        this.scheduled = false;\n        this.flushAndNotify();\n      });\n      return;\n    }\n\n    if (scheduleMode === 'idle') {\n      this.idleId = requestIdle(() => {\n        this.idleId = undefined;\n        this.scheduled = false;\n        this.flushAndNotify();\n      });\n      return;\n    }\n\n    // Default: 'animation-frame'.\n    this.frameId = requestAnimationFrame(() => {\n      this.frameId = undefined;\n      this.scheduled = false;\n      this.flushAndNotify();\n    });\n  }\n\n  private currentSchedule(): EtaMutationBatchSchedule {\n    const schedule = this.options.schedule;\n\n    if (typeof schedule === 'function') {\n      return schedule() ?? 'animation-frame';\n    }\n\n    return schedule ?? 'animation-frame';\n  }\n\n  /**\n   * Cancel any pending scheduled flush.\n   *\n   * Called by `flush()` so a manual flush is not followed by the\n   * scheduled flush. Safe to call when nothing is scheduled — the\n   * `undefined` checks short-circuit.\n   *\n   * **`microtask` schedule.** `queueMicrotask` does not expose a\n   * cancellation handle; we instead invalidate `this.microtaskToken`\n   * so the queued callback's identity-check fails and the callback\n   * becomes a no-op. `this.scheduled` is also reset so a fresh\n   * `enqueue()` after a manual flush can schedule a new flush.\n   */\n  private cancelSchedule(): void {\n    if (this.frameId !== undefined) {\n      cancelAnimationFrame(this.frameId);\n      this.frameId = undefined;\n    }\n\n    if (this.idleId !== undefined) {\n      cancelIdle(this.idleId);\n      this.idleId = undefined;\n    }\n\n    this.microtaskToken = undefined;\n    this.scheduled = false;\n  }\n}\n\n/**\n * Apply a compacted `EtaMutationBatch` to the index.\n *\n * The compaction rules are documented on `EtaMutationBatch`. The\n * order of application matters:\n *\n * 1. **Compact `removed` and apply.** Removes must run first so\n *    later `add` / `text` / `attribute` checks correctly identify\n *    descendants of removed roots and skip them.\n * 2. **Compact `added` and apply** (skipping nodes inside a\n *    removed root). Adds come next so descendant text / attribute\n *    changes inside added subtrees are dropped in step 3/4.\n * 3. **Walk `text`** (skipping nodes inside any removed or added\n *    root). The text bucket is walked last because text changes\n *    inside add / remove roots are irrelevant.\n * 4. **Walk `attributes`** (skipping elements inside any removed or\n *    added root). Same rationale as step 3.\n *\n * Each compacted mutation is forwarded to `index.apply(...)`, which\n * returns `true` only when the index actually changed. The dirty\n * flag is OR-accumulated across all four passes.\n *\n * Returns `true` when at least one compacted mutation made the\n * index dirty, `false` when every pass was a no-op.\n */\nfunction applyMutationBatch(\n  index: EtaTemplateIndexLike,\n  batch: EtaMutationBatch\n): boolean {\n  const removedRoots = compactRoots(batch.removed);\n  const addedRoots = compactRoots(batch.added);\n\n  let dirty = false;\n\n  // 1. Removes first.\n  for (const node of removedRoots) {\n    if (\n      index.apply({\n        type: 'remove',\n        node\n      })\n    ) {\n      dirty = true;\n    }\n  }\n\n  // 2. Adds second (skip descendants of removed roots).\n  for (const node of addedRoots) {\n    if (isInsideAny(node, removedRoots)) {\n      continue;\n    }\n\n    if (\n      index.apply({\n        type: 'add',\n        node\n      })\n    ) {\n      dirty = true;\n    }\n  }\n\n  // 3. Text changes (skip descendants of add/remove roots).\n  for (const text of batch.text) {\n    if (\n      isInsideAny(text, removedRoots) ||\n      isInsideAny(text, addedRoots)\n    ) {\n      continue;\n    }\n\n    if (\n      index.apply({\n        type: 'text',\n        node: text\n      })\n    ) {\n      dirty = true;\n    }\n  }\n\n  // 4. Attribute changes (skip descendants of add/remove roots).\n  for (const [element, attrs] of batch.attributes) {\n    if (\n      isInsideAny(element, removedRoots) ||\n      isInsideAny(element, addedRoots)\n    ) {\n      continue;\n    }\n\n    for (const attr of attrs) {\n      if (\n        index.apply({\n          type     : 'attribute',\n          element,\n          attribute: attr\n        })\n      ) {\n        dirty = true;\n      }\n    }\n  }\n\n  return dirty;\n}\n"]}

package/dist/src/eta/cache.d.ts

@@ -0,0 +1,36 @@
+import { Eta } from 'eta/core';
+import type { EtaCompiledTemplate, EtaTemplateCache } from './types.js';
+/**
+ * Default cache backed by a single Eta instance.
+ *
+ * The Eta class compiles templates lazily and stores the resulting function
+ * strings. Wrapping it in a small cache gives us:
+ *
+ * - a stable `source -> compiled` map that survives across renders
+ * - a single, well-defined place that knows about Eta tags / options
+ * - a `clear` hook so tests and HMR can drop the cache when templates change
+ *
+ * Compilation happens on first access for a given source. The cache is keyed
+ * by the raw source string, so two equivalent template strings share a single
+ * compiled entry.
+ */
+export declare class DefaultEtaTemplateCache implements EtaTemplateCache {
+    private readonly eta;
+    private readonly entries;
+    constructor(options?: Partial<ConstructorParameters<typeof Eta>[0]>);
+    get(source: string): EtaCompiledTemplate;
+    clear(): void;
+    /**
+     * Number of compiled templates currently held in the cache.
+     *
+     * Exposed for diagnostics and tests; not part of the public contract.
+     */
+    get size(): number;
+}
+/**
+ * Convenience constructor used by the default factory.
+ *
+ * Tests can swap in a custom cache via the factory constructor; the rest of
+ * the subsystem talks only to the `EtaTemplateCache` interface.
+ */
+export declare function createEtaTemplateCache(options?: Partial<ConstructorParameters<typeof Eta>[0]>): EtaTemplateCache;

package/dist/src/eta/cache.js

@@ -0,0 +1,56 @@
+// src/eta/cache.ts
+import { Eta } from 'eta/core';
+/**
+ * Default cache backed by a single Eta instance.
+ *
+ * The Eta class compiles templates lazily and stores the resulting function
+ * strings. Wrapping it in a small cache gives us:
+ *
+ * - a stable `source -> compiled` map that survives across renders
+ * - a single, well-defined place that knows about Eta tags / options
+ * - a `clear` hook so tests and HMR can drop the cache when templates change
+ *
+ * Compilation happens on first access for a given source. The cache is keyed
+ * by the raw source string, so two equivalent template strings share a single
+ * compiled entry.
+ */
+export class DefaultEtaTemplateCache {
+    constructor(options) {
+        this.entries = new Map();
+        this.eta = new Eta({
+            tags: ['{{', '}}'],
+            ...options
+        });
+    }
+    get(source) {
+        let compiled = this.entries.get(source);
+        if (compiled === undefined) {
+            // Eta's compile() is bound to the instance. We bind once so callers
+            // can invoke the cached function without an explicit `this`.
+            compiled = this.eta.compile(source).bind(this.eta);
+            this.entries.set(source, compiled);
+        }
+        return compiled;
+    }
+    clear() {
+        this.entries.clear();
+    }
+    /**
+     * Number of compiled templates currently held in the cache.
+     *
+     * Exposed for diagnostics and tests; not part of the public contract.
+     */
+    get size() {
+        return this.entries.size;
+    }
+}
+/**
+ * Convenience constructor used by the default factory.
+ *
+ * Tests can swap in a custom cache via the factory constructor; the rest of
+ * the subsystem talks only to the `EtaTemplateCache` interface.
+ */
+export function createEtaTemplateCache(options) {
+    return new DefaultEtaTemplateCache(options);
+}
+//# sourceMappingURL=cache.js.map