@repobit/dex-store-elements 1.7.3 → 2.0.0

package/dist/src/eta/controller.js

@@ -0,0 +1,1036 @@
+// src/eta/controller.ts
+import { Task } from '@lit/task';
+import { EtaMutationBatcher } from './batcher.js';
+import { createEtaTemplateCache } from './cache.js';
+import { createDefaultTemplateOperationFactory } from './factory.js';
+import { EtaMutationObserver } from './observer.js';
+import { EtaTemplateIndex } from './template-index.js';
+/**
+ * Throws `signal.reason` when the signal has been aborted. No-op
+ * otherwise.
+ *
+ * Prefers the native `signal.throwIfAborted()` when available (most
+ * modern browsers) and falls back to a manual throw so the helper
+ * still works in environments that pre-date `AbortSignal`'s
+ * `throwIfAborted` method (notably some jsdom versions and older
+ * test runners).
+ */
+function throwIfAborted(signal) {
+    if (typeof signal.throwIfAborted === 'function') {
+        signal.throwIfAborted();
+        return;
+    }
+    if (signal.aborted) {
+        throw (signal.reason ??
+            new DOMException('The operation was aborted.', 'AbortError'));
+    }
+}
+/**
+ * Reactive controller that owns the lifecycle of the Eta template
+ * subsystem for a single scoped boundary.
+ *
+ * Responsibilities:
+ *
+ * - Owns the `@lit/task` that drives rendering.
+ * - Builds the rendering context from the host-supplied `args` /
+ *   `context` callbacks.
+ * - Owns the `MutationObserver` that feeds the index.
+ * - Owns a single `EtaTemplateIndex`.
+ * - Iterates operations and calls `execute(context)` on each.
+ * - Participates in `host.trackLocalWork` so render passes count
+ *   toward `BdNodeElement.updateComplete`.
+ *
+ * It does NOT:
+ *
+ * - Walk the DOM during render (the index is the source of truth).
+ * - Discover templates during render (the factory runs once on
+ *   `add`).
+ * - Know about products, options, prices, or transitions.
+ *
+ * **Skip-render semantics.** When `enabled(args)` returns `false`
+ * or `context(args)` returns `undefined`, the controller skips the
+ * render pass and returns `undefined`. Previously rendered DOM
+ * output stays as-is — the controller does not blank the DOM or
+ * remove rendered nodes. Hosts that want blank/fallback output
+ * should either return a context that causes templates to render
+ * blank values, or publish a fallback scope (e.g. an empty object
+ * or a sentinel value) before requesting a render. This behaviour
+ * is intentional: it lets the controller be safely driven from
+ * the host's reactive state without flickering on intermediate
+ * states where the scope is temporarily absent.
+ */
+export class EtaTemplateController {
+    /**
+     * The controller's internal template cache.
+     *
+     * **Internal — true private field.** The `#` ECMAScript private
+     * field cannot be observed from outside the class at all
+     * (neither via property lookup nor via casting). The TypeScript
+     * `private` modifier above would be enough for the type checker
+     * but JS property access would still find the field; using
+     * `#cache` closes that gap at runtime too.
+     *
+     * **Per-controller isolation.** The controller always builds its
+     * own cache; there is no public option to inject a different
+     * one. The cache is shared with the controller's private
+     * factory so `clearCache()` drains whatever the factory uses to
+     * memoize compiled templates.
+     *
+     * Hosts invalidate the controller's own cache via
+     * `controller.clearCache()`. The `clearCache()` call only clears
+     * this controller's cache; no other state is affected.
+     */
+    #cache;
+    constructor(host, options) {
+        /**
+         * Set of every shadow root that has already been wired into a
+         * shadow binding.
+         *
+         * `WeakSet` because shadow roots can be GC'd when their host
+         * disconnects — we never want to keep them alive through this
+         * field. `_addShadowBinding` is the single writer; both
+         * `_connectShadowRoots` (initial discovery) and
+         * `_discoverShadowRootsFor` (light-DOM mutation-driven
+         * discovery) gate registration through this set so the same
+         * shadow root is never wired twice.
+         */
+        this._seenShadows = new WeakSet();
+        /**
+         * Per-shadow-root observer + batcher + index triples. Empty
+         * when the host does not enumerate any shadow roots. Each
+         * triple is wired in `hostConnected` and torn down in
+         * `hostDisconnected` alongside the light-DOM observer.
+         */
+        this.shadowBindings = [];
+        this.host = host;
+        // Runtime guard — `EtaTemplateHost.root` is non-optional in
+        // the type system, but a host implementing the interface
+        // could still hand back `undefined` at runtime. The index
+        // uses `host.root` as its discovery boundary and silently
+        // indexing the whole document if `root` is missing would
+        // produce very confusing behaviour. Fail loudly instead.
+        if (!host.root) {
+            throw new Error('EtaTemplateController: host.root is required. ' +
+                'The host element must expose a `root` getter that ' +
+                'returns the Element the controller should index.');
+        }
+        this.argsFn = options.args;
+        this.enabledFn = options.enabled;
+        this.contextFn = options.context;
+        this.onRenderError = options.onRenderError;
+        this.mutationBatchScheduleOption =
+            options.mutationBatchSchedule ?? 'animation-frame';
+        this._boundaryElementPredicate =
+            options.isBoundaryElement;
+        this.#cache = createEtaTemplateCache();
+        // The controller owns its factory. There is no public option
+        // to inject one — the factory is a private collaborator like
+        // the cache. The controller builds a default
+        // `DefaultTemplateOperationFactory` that shares its `#cache`,
+        // so the cache and the factory stay in lockstep and
+        // `clearCache()` drains the factory's compiled-template store
+        // as well.
+        const normalizedAttributeNames = this._observerAttributeNames(options);
+        this._normalizedAttributeNames = normalizedAttributeNames;
+        this.factory =
+            createDefaultTemplateOperationFactory(this.#cache, this._factoryOptions(options, normalizedAttributeNames));
+        this.index =
+            options.createIndex?.(this.factory) ??
+                new EtaTemplateIndex(this.factory, {
+                    root: host.root,
+                    isBoundaryElement: options.isBoundaryElement
+                });
+        // Round-6 mutation-batching layer. The batcher sits between
+        // the observer and the index: the observer forwards raw
+        // MutationRecord batches via `onRecords`, the batcher
+        // accumulates them, compacts them per the design rules, and
+        // flushes the compacted mutations to the index on the
+        // configured schedule (`animation-frame` by default).
+        //
+        // The `onFlush` callback kicks a render when the flush was
+        // dirty — empty flushes never cause a render. We deliberately
+        // call `task.run()` (not `requestRender()`) because the
+        // batcher is the source of truth for "dirty" and we want the
+        // Task's scheduling semantics (abort, dedupe, re-entry)
+        // rather than the manual `requestRender()` path.
+        this.batcher = new EtaMutationBatcher(this.index, {
+            schedule: () => this.mutationBatchSchedule,
+            onFlush: (dirty) => {
+                if (dirty) {
+                    this.task.run();
+                }
+            }
+        });
+        this.observer = new EtaMutationObserver({
+            attributeNames: normalizedAttributeNames,
+            onRecords: (records) => {
+                this.batcher.enqueue(records);
+                // Discovery hook: a freshly-added element may carry a
+                // shadow root that did not exist when `_connectShadowRoots`
+                // ran. The hook is idempotent (gated by `_seenShadows`)
+                // and only walks `childList` records so attribute / text
+                // mutations stay cheap.
+                this._discoverShadowRootsFor(records);
+            }
+        });
+        this.task = new Task(host, {
+            autoRun: true,
+            argsEqual: options.argsEqual,
+            task: async (args, { signal }) => {
+                const work = this._runRenderPass(args, signal);
+                const tracked = this.host.trackLocalWork?.(this, work) ?? work;
+                return tracked;
+            },
+            args: () => this.argsFn()
+        });
+        host.addController(this);
+    }
+    /**
+     * Invalidates every compiled template this controller owns.
+     *
+     * Drops all entries from the controller's internal cache. The
+     * next render that touches a previously-compiled template will
+     * re-compile it through the cache.
+     *
+      * **Per-controller scope.** `clearCache()` only clears this
+      * controller's own cache. There is no public cache injection
+      * option; hosts that want shared templates across controllers
+      * should compile and store those templates at the application
+      * layer instead of sharing the controller's internal Eta cache.
+     *
+     * Safe to call at any time, including between renders.
+     */
+    clearCache() {
+        this.#cache.clear();
+    }
+    /**
+     * Status of the underlying Task.
+     *
+     * Exposed so consumers (e.g. tests) can assert progress without
+     * reaching into the `@lit/task` surface.
+     */
+    get status() {
+        return this.task.status;
+    }
+    /**
+     * Latest context produced by a successful render pass.
+     */
+    get value() {
+        return this.task.value;
+    }
+    /**
+     * Most recent render error, or `undefined` when the last render
+     * succeeded.
+     *
+     * Mirrors `@lit/task`'s `Task.error` getter. When a host passes
+     * `onRenderError`, the controller swallows render errors and
+     * records them here — read this getter to surface them in UI
+     * state (e.g. an error banner). When `onRenderError` is omitted,
+     * render errors reject `updateComplete`; both this getter and
+     * the rejected promise expose the same error value.
+     */
+    get error() {
+        return this.task.error;
+    }
+    /**
+     * Promise that resolves when the current render pass completes.
+     *
+     * Mirrors `BdNodeElement.updateComplete`'s promise semantics for
+     * the Eta subsystem. When the host supplies `trackLocalWork`,
+     * this promise is tracked under the controller's instance so the
+     * host's `updateComplete` waits for the render to settle before
+     * resolving.
+     *
+     * Useful for tests and for downstream consumers that need to
+     * observe render completion without poking at `@lit/task`.
+     */
+    get updateComplete() {
+        return this.task.taskComplete;
+    }
+    /**
+     * Requests a fresh render pass through the underlying `@lit/task`.
+     *
+     * Most consumers never need to call this: the controller re-runs
+     * whenever the host signals an update, the index mutates, or the
+     * Task args change. The hook is provided for tests and for
+     * consumers that want to force a re-render after an external cache
+     * invalidation, scope mutation outside the normal reactive flow,
+     * or other event that the Task's `argsEqual` check might miss.
+     *
+     * The name reflects what actually happens: `Task.run()` schedules
+     * the task through Task's own scheduling semantics (which may
+     * batch, dedupe, or abort against the current run id) rather than
+     * synchronously executing the render loop.
+     *
+     * **Returns a promise.** The promise resolves to the latest
+     * context (`TContext | undefined`) produced by the render pass
+     * that `Task.run()` scheduled. Awaiting it lets tests and
+     * downstream consumers observe render completion without
+     * reaching into `@lit/task`. The promise resolves with the
+     * controller's `value`, which is `undefined` when the render was
+     * skipped (because `enabled()` returned `false` or `context()`
+     * returned `undefined`).
+     *
+     * Because `Task.run()` returns `Promise<void>` in the installed
+     * `@lit/task` version, this method kicks the run and then waits
+     * on `taskComplete` (the same promise exposed as
+     * `controller.updateComplete`) before reading `this.value`.
+     * `Task.run()` resolves when the run is *scheduled*, not when it
+     * *completes*; waiting on `taskComplete` is the only way to
+     * guarantee the returned context reflects the render that this
+     * call kicked off. The same `taskComplete` is also what the host
+     * `updateComplete` waits on (through `trackLocalWork`), so
+     * awaiting this method aligns the caller with the host's
+     * subtree-completion promise.
+     */
+    async requestRender() {
+        // Kick the Task run. The returned promise resolves when the
+        // run is scheduled, NOT when the render completes.
+        this.task.run();
+        // Wait for the render to actually finish so `this.value`
+        // reflects this render's context rather than the previous
+        // run's value. `taskComplete` is the same promise exposed
+        // through the controller's `updateComplete` getter.
+        await this.task.taskComplete;
+        return this.value;
+    }
+    /**
+     * Flushes the mutation batcher synchronously.
+     *
+     * Forwards any pending `MutationRecord`s to the index through
+     * the batcher's compaction pass and returns whether the flush
+     * made the index dirty. Returns `false` when there was nothing
+     * to flush — an empty batch is a no-op.
+     *
+     * **Use cases:**
+     *
+     * - Hosts that drive the controller with
+     *   `mutationBatchSchedule: 'manual'` and want to apply a
+     *   known decoration phase's mutations before reading the
+     *   index. Pair with `flushAndRender()` when a render is
+     *   needed afterwards.
+     * - Tests that want a deterministic, intent-revealing way to
+     *   drain the batcher without going through the observer's
+     *   scheduled tick. This is the recommended way to assert on
+     *   the post-flush index state from test bodies.
+     * - Hot-path code that knows a render is about to be requested
+     *   via `requestRender()` and wants to guarantee the render
+     *   sees the latest mutations (the render task body already
+     *   calls `batcher.flush()` before executing, so this is
+     *   rarely needed in practice — but useful when callers want
+     *   the flush to happen synchronously at the call site rather
+     *   than inside the Task).
+     *
+     * Does NOT call `onFlush` on the batcher, so the flush never
+     * re-enters `task.run()` on its own. Call `flushAndRender()`
+     * when a render should follow the flush.
+     *
+     * Returns the batcher's `flush()` return value — `true` when
+     * at least one compacted mutation made the index dirty,
+     * `false` otherwise. The dirty flag mirrors the batcher's
+     * dirty semantics (OR-accumulated across the four compaction
+     * passes — see `EtaMutationBatcher.flush`).
+     */
+    /**
+     * Flushes every observer queue into its matching batcher, then
+     * flushes every batcher into its matching index.
+     *
+     * Forwards any pending `MutationRecord`s to the index through
+     * the batcher's compaction pass and returns whether the flush
+     * made the index dirty. Returns `false` when there was nothing
+     * to flush — an empty batch is a no-op.
+     *
+     * **Manual schedule mode.** When `mutationBatchSchedule` is
+     * `'manual'`, the batcher never auto-flushes; the host must
+     * drain the queue itself. This method honours that contract
+     * across every observed root (light + every shadow binding).
+     *
+     * **Drain order:**
+     *
+     * 1. Light observer → light batcher
+     *    (`observer.flushPendingRecords({ notify: false })`).
+     * 2. Every shadow observer → its shadow batcher
+     *    (`binding.observer.flushPendingRecords({ notify: false })`).
+     *    Drain the observer BEFORE the batcher so records the
+     *    browser has produced but not yet delivered reach the
+     *    batcher before the synchronous flush.
+     * 3. Light batcher → light index (`batcher.flush()`).
+     * 4. Every shadow batcher → its shadow index
+     *    (`binding.batcher.flush()`), OR-accumulated into the
+     *    combined dirty flag.
+     *
+     * **Use cases:**
+     *
+     * - Hosts that drive the controller with
+     *   `mutationBatchSchedule: 'manual'` and want to apply a
+     *   known decoration phase's mutations before reading the
+     *   index. Pair with `flushAndRender()` when a render is
+     *   needed afterwards.
+     * - Tests that want a deterministic, intent-revealing way to
+     *   drain the batcher without going through the observer's
+     *   scheduled tick. This is the recommended way to assert on
+     *   the post-flush index state from test bodies.
+     * - Hot-path code that knows a render is about to be requested
+     *   via `requestRender()` and wants to guarantee the render
+     *   sees the latest mutations (the render task body already
+     *   calls `batcher.flush()` before executing, so this is
+     *   rarely needed in practice — but useful when callers want
+     *   the flush to happen synchronously at the call site rather
+     *   than inside the Task).
+     *
+     * Does NOT call `onFlush` on any batcher, so the flush never
+     * re-enters `task.run()` on its own. Call `flushAndRender()`
+     * when a render should follow the flush.
+     *
+     * Returns the combined dirty flag — `true` when at least one
+     * batcher (light or shadow) made its index dirty, `false`
+     * otherwise. The dirty flag mirrors each batcher's dirty
+     * semantics (OR-accumulated across the four compaction passes
+     * — see `EtaMutationBatcher.flush`).
+     *
+     * Idempotent — calling on an empty queue/batch still returns
+     * `false` and never triggers a render. The `notify: false` flag
+     * on every `flushPendingRecords` call keeps the observer's
+     * own `onChange` callback dormant during a manual flush so a
+     * host that drains and then calls `requestRender()` does not
+     * double-schedule.
+     */
+    flushMutations() {
+        this.observer.flushPendingRecords({ notify: false });
+        for (const binding of this.shadowBindings) {
+            binding.observer.flushPendingRecords({ notify: false });
+        }
+        let dirty = this.batcher.flush();
+        for (const binding of this.shadowBindings) {
+            if (binding.batcher.flush()) {
+                dirty = true;
+            }
+        }
+        return dirty;
+    }
+    /**
+     * Flushes the mutation batcher and requests a fresh render
+     * pass when the flush was dirty.
+     *
+     * Convenience wrapper for the "manual" schedule mode — hosts
+     * that opt into `mutationBatchSchedule: 'manual'` must drain
+     * the batcher themselves and then trigger a render. This
+     * method collapses both steps into one call:
+     *
+     * ```ts
+     * decorateBlock(block);
+     * await decorateIcons(block);
+     * eta.flushAndRender();
+     * ```
+     *
+     * When the flush was a no-op (`false` return from the
+     * batcher) the render is skipped — there is no point re-running
+     * the Task against an unchanged index. When the flush was
+     * dirty, the call forwards to `requestRender()` so the Task
+     * runs with the same scheduling semantics as any other
+     * render-triggering path.
+     *
+     * Does NOT wait for the render to complete; callers that need
+     * to await the resulting context can follow up with
+     * `await controller.updateComplete` (or
+     * `await controller.requestRender()`). The return value of
+     * the underlying `requestRender()` is intentionally discarded
+     * to keep the API synchronous and easy to call from
+     * imperative decoration flows.
+     */
+    flushAndRender() {
+        const dirty = this.flushMutations();
+        if (dirty) {
+            // `requestRender()` returns a promise that resolves once
+            // the Task completes; we intentionally discard it so the
+            // host can call `flushAndRender()` from synchronous
+            // decoration code. Callers that need to await the render
+            // can use `await controller.updateComplete` afterwards.
+            void this.requestRender();
+        }
+    }
+    /**
+     * Reads the current batch schedule as resolved by the
+     * controller. Useful for diagnostics and for tests that want
+     * to assert on the controller's effective schedule without
+     * reaching into the private `batcher` field.
+     */
+    get mutationBatchSchedule() {
+        return this._currentMutationBatchSchedule();
+    }
+    _currentMutationBatchSchedule() {
+        const schedule = this.mutationBatchScheduleOption;
+        if (typeof schedule === 'function') {
+            return schedule() ?? 'animation-frame';
+        }
+        return schedule ?? 'animation-frame';
+    }
+    /**
+     * Runs a single render pass.
+     *
+     * The pass is gated by `enabled(args)` and `context(args)`:
+     *
+     * - `enabled` returning `false` skips the loop and returns
+     *   `undefined` (no context, no render).
+     * - `context` returning `undefined` does the same.
+     *
+     * When both gates pass, the render loop runs in two phases:
+     *
+     * 1. **Pre-flush.** The mutation batcher applies any pending
+     *    `MutationRecord` batches to the index via
+      *    `observer.flushPendingRecords({ notify: false })` drains
+      *    records the browser has produced but not delivered yet into
+      *    the batcher, then `batcher.flush()` applies the compacted
+      *    batch so the index and source registry are accurate before
+      *    the render reads operations. Without this step, a render
+      *    triggered by a Task args change or a manual `requestRender()`
+      *    call could run against a stale index whenever the observer or
+      *    batcher had not yet flushed a pending burst of DOM changes.
+     *
+     *    `batcher.flush()` cancels any pending scheduled flush
+     *    AND applies the current batch synchronously; it does NOT
+     *    call `onFlush`. That detail is important — calling
+     *    `onFlush` from inside an in-flight render pass would
+     *    re-enter `task.run()` and create an infinite render
+     *    loop. The Task's auto-run and the batcher's onFlush
+     *    callback are kept on separate scheduling paths for this
+     *    reason.
+     *
+      *    The round-6 batcher sits between the observer and the index,
+      *    so both layers participate in the pre-flush: the observer
+      *    drains queued records into the batcher, and the batcher
+      *    drains its compacted mutations into the index.
+     * 2. **Render.** The render loop runs in two phases so each
+     *    phase can suspend only the observer that would otherwise
+     *    treat the phase's self-induced mutations as fresh external
+     *    mutations:
+     *
+     *    a. **Light-DOM phase.** Iterates `this.index` inside
+     *       `observer.suspendSync(...)` so DOM writes performed by
+     *       light-DOM operations are not fed back as fresh
+     *       mutations. The `finally` block drains whatever's queued
+     *       after the loop — at this point only self-induced
+     *       records should remain.
+     *    b. **Shadow phase.** Iterates each binding's `index`
+     *       inside `binding.observer.suspendSync(...)`. Wrapping
+     *       the shadow phase in `this.observer.suspendSync` would
+     *       discard legitimate external light-DOM mutations queued
+     *       in the meantime via `takeRecords`, and would not
+     *       actually suppress shadow observer feedback (the light
+     *       observer cannot see shadow-tree writes anyway). Each
+     *       binding therefore suspends its OWN observer so writes
+     *       inside its shadow root are not fed back as fresh
+     *       mutations.
+     *
+     *    The pre-flush step above drained every shadow observer
+     *    BEFORE either phase, so the only records the shadow
+     *    observer will see during the shadow phase are writes from
+     *    the shadow operations themselves — exactly what each
+     *    shadow observer's `suspendSync` is there to suppress.
+     *
+     * Per-operation errors are routed to `onRenderError` when
+     * supplied; otherwise they propagate to the Task and abort the
+     * render pass.
+     */
+    async _runRenderPass(args, signal) {
+        if (this.enabledFn && !this.enabledFn(args)) {
+            return undefined;
+        }
+        const context = this.contextFn(args);
+        if (context === undefined) {
+            return undefined;
+        }
+        // Pre-flush: drain queued observer records into the batcher,
+        // then apply any pending batch mutations to the index BEFORE
+        // building the render loop. Without this step, the render
+        // would run against a stale index whenever a burst of DOM
+        // changes has been produced by the observer or accumulated by
+        // the batcher but not yet flushed.
+        //
+        // `batcher.flush()` cancels any pending scheduled flush and
+        // applies the current batch synchronously. It does NOT call
+        // `onFlush` (no re-entrant `task.run()` from inside an
+        // in-flight render pass — see the batcher's flush vs
+        // flushAndNotify split).
+        //
+        // Draining the observer first matters because suspendSync's
+        // final takeRecords() intentionally drops self-induced render
+        // records. External records queued before the render must reach
+        // the batcher before that drain happens. The same applies to
+        // every shadow observer — drain those too so render passes
+        // don't run against stale shadow indices.
+        this.observer.flushPendingRecords({ notify: false });
+        this.batcher.flush();
+        for (const binding of this.shadowBindings) {
+            binding.observer.flushPendingRecords({ notify: false });
+            binding.batcher.flush();
+        }
+        this.observer.suspendSync(() => {
+            for (const op of this.index) {
+                if (signal.aborted) {
+                    break;
+                }
+                try {
+                    op.execute(context);
+                }
+                catch (error) {
+                    if (this.onRenderError) {
+                        this.onRenderError(error, op);
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            }
+        });
+        // Shadow operations run under their OWN observer suspension.
+        // The render loop iterates light-DOM ops and shadow-binding
+        // ops in separate phases so each phase can suspend only the
+        // observer that would otherwise treat the phase's self-induced
+        // mutations as fresh external mutations.
+        //
+        // Why two phases:
+        //
+        // - The light-DOM observer stays alive while a shadow
+        //   operation writes its rendered value into a shadow node —
+        //   that observer cannot see the write (different root), so
+        //   it cannot feed back into the light index. Wrapping the
+        //   shadow phase in `this.observer.suspendSync` would be a
+        //   no-op (and would discard legitimate external light-DOM
+        //   mutations queued in the meantime via `takeRecords`).
+        // - The shadow observer for a binding sees only mutations
+        //   inside its own shadow root. Shadow operations writing
+        //   into that root must run under that observer's
+        //   suspension so the writes are not fed back as fresh
+        //   shadow mutations; otherwise the shadow batcher would
+        //   re-enqueue them on the next flush and the operation
+        //   would rebuild against no template and get dropped (the
+        //   shadow source registry has already persisted the
+        //   rendered plain string).
+        //
+        // Each phase reuses the existing abort-signal check and the
+        // `onRenderError` routing so a failing operation only fails
+        // its own phase.
+        for (const binding of this.shadowBindings) {
+            binding.observer.suspendSync(() => {
+                for (const op of binding.index) {
+                    if (signal.aborted) {
+                        break;
+                    }
+                    try {
+                        op.execute(context);
+                    }
+                    catch (error) {
+                        if (this.onRenderError) {
+                            this.onRenderError(error, op);
+                        }
+                        else {
+                            throw error;
+                        }
+                    }
+                }
+            });
+        }
+        // Surface aborts that fired during the render loop as Task
+        // errors so the task moves to the `ABORTED` status instead of
+        // returning a stale context. The render loop itself is
+        // synchronous, but external callers (e.g. host disconnection)
+        // can flip the signal between the loop's `break` check and the
+        // point where we return.
+        throwIfAborted(signal);
+        return context;
+    }
+    /**
+     * Returns the effective attribute-name list that both the
+     * observer and the factory must agree on.
+     *
+     * The single source of truth avoids contradictory
+     * configurations where the observer is told to watch every
+     * attribute while the factory is told to filter to a specific
+     * list (or vice versa). The previous behaviour dropped records
+     * on the floor silently when `observeAllAttributes: true` was
+     * combined with a non-empty `attributeNames`.
+     *
+     * Resolution order:
+     *
+     * 1. `observeAllAttributes: true` → `undefined` (watch
+     *    everything).
+     * 2. Non-empty `attributeNames` → that exact list.
+     * 3. Anything else → `undefined` (watch everything).
+     */
+    _observerAttributeNames(options) {
+        if (options.observeAllAttributes === true) {
+            return undefined;
+        }
+        if (options.attributeNames &&
+            options.attributeNames.length > 0) {
+            return options.attributeNames;
+        }
+        return undefined;
+    }
+    /**
+     * Builds the per-factory option object passed to the default
+     * factory constructor.
+     *
+     * `observeAllAttributes: true` (or no allowlist supplied) means
+     * the factory should observe every attribute, so we omit
+     * `attributeNames` entirely and let the factory default to
+     * "observe all".
+     *
+     * When the controller was constructed with an explicit
+     * `attributeNames` allowlist, we forward the **normalized** list
+     * (computed by `_observerAttributeNames`) so the factory and the
+     * observer agree on the same allowlist. Using the raw
+     * `options.attributeNames` here would let `observeAllAttributes:
+     * true` coexist with a non-empty list, contradicting the
+     * observer's "watch everything" mode.
+     */
+    _factoryOptions(_options, normalizedAttributeNames) {
+        if (normalizedAttributeNames === undefined) {
+            return {};
+        }
+        return { attributeNames: normalizedAttributeNames };
+    }
+    hostConnected() {
+        // Initialize after the host is connected so the light DOM is available.
+        // Nested boundaries are detected by the configured isBoundaryElement predicate.
+        this.index.initialize(this.host.root);
+        this.observer.observe(this.host.root);
+        // Shadow roots are wired after the light-DOM observer so a
+        // render pass covers both trees in stable order. The host's
+        // `shadowRoots` callback runs once per connect; closed roots
+        // are skipped with a one-time console.warn.
+        this._connectShadowRoots();
+    }
+    /**
+     * Discovers every open shadow root attached to a descendant of
+     * the host's light subtree and wires one observer + batcher +
+     * index triple per root.
+     *
+     * `MutationObserver` is scoped to a single root: an observer
+     * attached to the host's light root does NOT see mutations
+     * inside any nested shadow root. To render templates into
+     * shadow trees the controller must therefore attach a separate
+     * observer per shadow root. The controller discovers those roots
+     * itself — walking the host's light subtree and reading
+     * `element.shadowRoot` — so hosts do not have to plumb the
+     * list through.
+     *
+     * Closed shadow roots are unreachable from outside (the
+     * `shadowRoot` getter returns `null` for closed mode), so they
+     * are silently skipped. Hosts that want to render into a
+     * closed root should attach a controller from inside that root
+     * instead.
+     *
+     * Idempotent — re-running on a second `hostConnected()` first
+     * tears down any existing bindings, then rebuilds them.
+     */
+    _connectShadowRoots() {
+        if (this.shadowBindings.length > 0) {
+            this._disconnectShadowRoots();
+        }
+        const root = this.host.root;
+        if (root === undefined) {
+            return;
+        }
+        // Iterative DFS over both the light DOM and any attached open
+        // shadow roots. Each step pops a node from the stack; for
+        // light-DOM elements we descend into `children` AND follow
+        // `shadowRoot` so a shadow tree nested inside a child is
+        // discovered. For shadow roots we descend into the root's
+        // own children (which are the shadow-tree's top-level
+        // nodes). Iterative (not recursive) so deeply nested
+        // shadow trees cannot blow the stack.
+        const stack = [root];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (node instanceof ShadowRoot) {
+                // Register the shadow root through the shared helper —
+                // it gates against `_seenShadows` so the same shadow root
+                // is never wired twice (the same guard also catches a
+                // re-entrant `_addShadowBinding` from a nested element's
+                // own upgrade path).
+                this._addShadowBinding(node);
+                // Descend into the shadow tree's top-level children.
+                for (const child of Array.from(node.children)) {
+                    stack.push(child);
+                }
+                continue;
+            }
+            if (node instanceof Element) {
+                // Descend into light-DOM children first.
+                for (const child of Array.from(node.children)) {
+                    stack.push(child);
+                }
+                // Then follow any attached open shadow root. Order
+                // matters for stable enumeration — children first,
+                // then the shadow — so the outer widget's own shadow
+                // tree appears before an inner widget's shadow tree.
+                if (node.shadowRoot) {
+                    stack.push(node.shadowRoot);
+                }
+            }
+        }
+    }
+    /**
+     * Registers a single shadow root with the controller — builds
+     * one observer + batcher + index triple per root and wires it
+     * into the light-DOM observer's discovery callback.
+     *
+     * Gates registration through `_seenShadows` so the same shadow
+     * root is never wired twice. Closed roots are skipped
+     * silently (their `shadowRoot` getter returns `null` so the
+     * caller should not pass them in).
+     */
+    _addShadowBinding(shadow) {
+        if (this._seenShadows.has(shadow)) {
+            return;
+        }
+        this._seenShadows.add(shadow);
+        const index = new EtaTemplateIndex(this.factory, {
+            root: shadow,
+            isBoundaryElement: this._shadowBoundaryPredicate(shadow)
+        });
+        const batcher = new EtaMutationBatcher(index, {
+            schedule: () => this.mutationBatchSchedule,
+            onFlush: (dirty) => {
+                if (dirty) {
+                    this.task.run();
+                }
+            }
+        });
+        const observer = new EtaMutationObserver({
+            attributeNames: this._normalizedAttributeNames,
+            onRecords: (records) => {
+                batcher.enqueue(records);
+            }
+        });
+        index.initialize(shadow);
+        observer.observe(shadow);
+        this.shadowBindings.push({
+            shadow,
+            observer,
+            batcher,
+            index
+        });
+    }
+    /**
+     * Reacts to a light-DOM `MutationRecord` batch by registering
+     * any newly-discovered open shadow roots.
+     *
+     * Lit `until` directives, `repeat` expansions, and custom
+     * element upgrades can attach shadow roots after the
+     * controller's `hostConnected()` pass has already walked the
+     * subtree. The light-DOM observer's callback fires for every
+     * mutation batch — we hook it here so a newly-inserted element
+     * that carries an open shadow root gets wired into the
+     * controller on the next batcher tick.
+     *
+     * Idempotent — `_addShadowBinding` gates against
+     * `_seenShadows`, so re-running the discovery walk on the same
+     * records (or running it during a `suspendSync` of the light
+     * observer) is harmless.
+     *
+     * Only `childList` records matter: an `add` of an element is
+     * what can carry a fresh shadow root, and skipping text /
+     * attribute records keeps the discovery walk cheap.
+     */
+    _discoverShadowRootsFor(records) {
+        for (const record of records) {
+            if (record.type !== 'childList') {
+                continue;
+            }
+            for (const added of Array.from(record.addedNodes)) {
+                this._walkForShadows(added);
+            }
+        }
+    }
+    /**
+     * Iterative DFS over `node`'s subtree (light children + open
+     * shadow roots) that registers every shadow root it encounters
+     * via `_addShadowBinding`.
+     *
+     * Mirrors the discovery shape used inside `_connectShadowRoots`
+     * but operates on a single subtree rooted at `node` rather
+     * than the full host subtree. Skips detached roots and any
+     * element/shadow already known to the controller — the
+     * `_seenShadows` gate inside `_addShadowBinding` short-circuits
+     * the second registration.
+     */
+    _walkForShadows(node) {
+        const stack = [node];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (current instanceof ShadowRoot) {
+                this._addShadowBinding(current);
+                // Descend into the shadow tree's top-level children —
+                // a nested host's own shadow must also be picked up.
+                for (const child of Array.from(current.children)) {
+                    stack.push(child);
+                }
+                continue;
+            }
+            if (current instanceof Element) {
+                for (const child of Array.from(current.children)) {
+                    stack.push(child);
+                }
+                const shadow = current.shadowRoot;
+                // `shadowRoot` is `null` for closed-mode and for
+                // elements that have not yet created a shadow root. Open
+                // roots are reachable via the getter and have a
+                // non-null return — `_addShadowBinding` then gates
+                // against `_seenShadows`.
+                if (shadow !== null) {
+                    stack.push(shadow);
+                }
+            }
+        }
+    }
+    /**
+     * Tears down every per-shadow-root observer, batcher, and index.
+     * Mirrors the light-DOM teardown order in `hostDisconnected()`
+     * so source-registry preservation behaves the same way on
+     * shadow roots as it does on the light tree.
+     *
+     * Clears `_seenShadows` so a subsequent `hostConnected()` can
+     * re-discover every shadow root from scratch — observers do
+     * not survive disconnect, so previously-seen shadow roots are
+     * no longer wired and should be re-discovered.
+     */
+    _disconnectShadowRoots() {
+        for (const binding of this.shadowBindings) {
+            binding.observer.flushPendingRecords({ notify: false });
+            binding.batcher.flush();
+            binding.observer.disconnect();
+            binding.index.disposeAll();
+        }
+        this.shadowBindings = [];
+        // Rebuild the seen-set to match the cleared bindings list.
+        // `WeakSet` cannot be cleared so we reassign the field —
+        // any other code holding a reference to the previous set
+        // would still see stale entries, but the controller is the
+        // sole writer and the only other read site is
+        // `_addShadowBinding`, which always reads the latest field
+        // value. The `unknown` cast is needed because the field is
+        // declared `private readonly` — the same pattern is used by
+        // the existing `WeakMap` / `WeakSet` resets in
+        // `EtaTemplateIndex.clear()`.
+        this._seenShadows = new WeakSet();
+    }
+    /**
+     * Returns the boundary predicate for a shadow-root index. The
+     * controller currently reuses the host's
+     * `isBoundaryElement` rule for every observed root — the host
+     * option is the single source of truth. This helper exists so
+     * per-root overrides can be added later without churning the
+     * `_connectShadowRoots` call site.
+     *
+     * Returns `undefined` when the host did not supply an
+     * `isBoundaryElement` predicate — preserves the pre-fix
+     * behaviour for those hosts (the shadow index then has no
+     * boundary rule and falls back to its own ownership checks).
+     */
+    _shadowBoundaryPredicate(_shadow) {
+        return this._boundaryElementPredicate;
+    }
+    hostDisconnected() {
+        // Round-6 teardown order. The order matters for source-
+        // registry preservation:
+        //
+        // 1. `observer.flushPendingRecords({ notify: false })` —
+        //    drains any records the browser has already produced
+        //    for the underlying `MutationObserver` and forwards
+        //    them through `onRecords` into the batcher. This is
+        //    the round-6 equivalent of round 5's
+        //    `observer.disconnect({ flush: true, notify: false })`:
+        //    the batcher is now the destination, so we drain into
+        //    the batcher first and let the regular disconnect path
+        //    skip the flush. `notify: false` avoids scheduling a
+        //    render during teardown.
+        // 2. `batcher.flush()` — applies the accumulated batch
+        //    synchronously so the index / source registry are
+        //    accurate through the next `disposeAll()`. Without
+        //    this step, an external mutation that landed just
+        //    before disconnect would survive only inside the
+        //    batcher's pending batch and be discarded together
+        //    with the batch on the next `flush()` (which won't
+        //    run because the observer is no longer attached).
+        // 3. `observer.disconnect()` — stops the underlying
+        //    `MutationObserver` from delivering future records.
+        //    Defaults to drain-only (`flush: false`) because step 1
+        //    already forwarded the queue; the observer's `finally`
+        //    `takeRecords()` is defensive.
+        // 4. `index.disposeAll()` — clears operations while
+        //    preserving the source registry for the next reconnect.
+        //
+        // No double-disconnect — step 3 is the only call to the
+        // underlying `observer.disconnect()`.
+        this.observer.flushPendingRecords({ notify: false });
+        this.batcher.flush();
+        this.observer.disconnect();
+        this.index.disposeAll();
+        // Shadow roots tear down in the same order: drain observer
+        // → flush batcher → disconnect observer → dispose index.
+        // `_disconnectShadowRoots()` clears `shadowBindings`, so a
+        // subsequent `hostConnected()` rebuilds them from scratch.
+        this._disconnectShadowRoots();
+    }
+    /**
+     * Explicit-disposal alias for `hostDisconnected()`.
+     *
+     * Lit `ReactiveController`s are torn down automatically when
+     * the host is disconnected, so most consumers never need this
+     * method. It exists for two cases:
+     *
+     * - Tests that want a deterministic, intent-revealing way to
+     *   tear down the controller from the test body, without
+     *   reaching into the Lit host's `hostDisconnected()` hook
+     *   manually. This makes the teardown intent obvious in
+     *   tests that exercise the observer / index wiring in
+     *   isolation.
+     * - Application code that owns a controller instance and wants
+     *   to mirror the Lit `hostConnected` / `hostDisconnected`
+     *   pair with a single, intent-revealing `dispose()` call —
+     *   for example, when a controller's lifetime is decoupled
+     *   from the host element (a controller that should be
+     *   disposed when a feature is unmounted, even if the host
+     *   stays connected for other reasons).
+     *
+     * The controller still requires a Lit `ReactiveControllerHost`
+     * because the constructor calls `host.addController(this)` —
+     * `dispose()` does not enable non-Lit integrations on its own,
+     * it only offers a more direct teardown path for the
+     * already-Lit-managed controller. If you need a true non-Lit
+     * integration, wrap the controller in a minimal
+     * `ReactiveControllerHost` adapter.
+     *
+     * The behaviour is identical to `hostDisconnected()`: the
+     * observer is drained into the batcher via
+     * `flushPendingRecords({ notify: false })`, the batcher is
+     * flushed synchronously, the observer is disconnected, and the
+     * index runs `disposeAll()`. Safe to call multiple times — the
+     * underlying `MutationObserver.disconnect()` is idempotent and
+     * the observer is one-shot, so a second call is a no-op.
+     */
+    dispose() {
+        this.hostDisconnected();
+    }
+}
+/**
+ * Convenience constructor used by `BdScopedElement` (in a follow-up
+ * task) and by tests that want a one-line setup.
+ *
+ * The controller owns its own cache and factory — neither is a
+ * public option. This constructor simply forwards to
+ * `new EtaTemplateController(host, options)` with no
+ * transformations. It exists as a named export so callers do not
+ * have to import the class directly.
+ *
+ * `args` and `context` are required by `EtaTemplateController` and
+ * must be supplied by the caller. The convenience constructor does
+ * not synthesise defaults for them.
+ */
+export function createEtaTemplateController(host, options) {
+    return new EtaTemplateController(host, options);
+}
+//# sourceMappingURL=controller.js.map