@repobit/dex-store-elements 1.7.2 → 2.0.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/eta/cache.ts"],"names":[],"mappings":"AAAA,mBAAmB;AAEnB,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAO/B;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,uBAAuB;IAOlC,YACE,OAAuD;QANxC,YAAO,GAAG,IAAI,GAAG,EAG/B,CAAC;QAKF,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,CAAC;YACjB,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;YAClB,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CAAC,MAAc;QAChB,IAAI,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAExC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,oEAAoE;YACpE,6DAA6D;YAC7D,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CACtC,IAAI,CAAC,GAAG,CACc,CAAC;YAEzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACrC,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAuD;IAEvD,OAAO,IAAI,uBAAuB,CAAC,OAAO,CAAC,CAAC;AAC9C,CAAC","sourcesContent":["// src/eta/cache.ts\n\nimport { Eta } from 'eta/core';\n\nimport type {\n  EtaCompiledTemplate,\n  EtaTemplateCache\n} from './types.js';\n\n/**\n * Default cache backed by a single Eta instance.\n *\n * The Eta class compiles templates lazily and stores the resulting function\n * strings. Wrapping it in a small cache gives us:\n *\n * - a stable `source -> compiled` map that survives across renders\n * - a single, well-defined place that knows about Eta tags / options\n * - a `clear` hook so tests and HMR can drop the cache when templates change\n *\n * Compilation happens on first access for a given source. The cache is keyed\n * by the raw source string, so two equivalent template strings share a single\n * compiled entry.\n */\nexport class DefaultEtaTemplateCache implements EtaTemplateCache {\n  private readonly eta: Eta;\n  private readonly entries = new Map<\n    string,\n    EtaCompiledTemplate\n  >();\n\n  constructor(\n    options?: Partial<ConstructorParameters<typeof Eta>[0]>\n  ) {\n    this.eta = new Eta({\n      tags: ['{{', '}}'],\n      ...options\n    });\n  }\n\n  get(source: string): EtaCompiledTemplate {\n    let compiled = this.entries.get(source);\n\n    if (compiled === undefined) {\n      // Eta's compile() is bound to the instance. We bind once so callers\n      // can invoke the cached function without an explicit `this`.\n      compiled = this.eta.compile(source).bind(\n        this.eta\n      ) as EtaCompiledTemplate;\n\n      this.entries.set(source, compiled);\n    }\n\n    return compiled;\n  }\n\n  clear(): void {\n    this.entries.clear();\n  }\n\n  /**\n   * Number of compiled templates currently held in the cache.\n   *\n   * Exposed for diagnostics and tests; not part of the public contract.\n   */\n  get size(): number {\n    return this.entries.size;\n  }\n}\n\n/**\n * Convenience constructor used by the default factory.\n *\n * Tests can swap in a custom cache via the factory constructor; the rest of\n * the subsystem talks only to the `EtaTemplateCache` interface.\n */\nexport function createEtaTemplateCache(\n  options?: Partial<ConstructorParameters<typeof Eta>[0]>\n): EtaTemplateCache {\n  return new DefaultEtaTemplateCache(options);\n}\n"]}

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

@@ -0,0 +1,608 @@
+import { type TaskStatus } from '@lit/task';
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { EtaMutationBatchSchedule, EtaTemplateControllerOptions, EtaTemplateHost, EtaTemplateIndexLike } from './types.js';
+/**
+ * Default context type for the Eta template subsystem.
+ *
+ * **This is a recommended context shape, NOT something the controller
+ * builds automatically.** The controller used to spread a default
+ * `$scope` / `$compute` context internally; the current `args` /
+ * `context` API delegates that to the host. Hosts that want the
+ * documented shape should construct the context themselves:
+ *
+ * ```ts
+ * context: ([scope]) => ({
+ *   ...(scope ?? {}),
+ *   $scope  : scope,
+ *   $compute: this.compute
+ * })
+ * ```
+ *
+ * Templates may reference any property of the scope as a top-level
+ * binding.
+ */
+export type DefaultEtaContext = {
+    readonly $scope?: object;
+    readonly $compute?: object;
+} & Record<string, unknown>;
+/**
+ * Status of the underlying `@lit/task`. Re-exported so consumers do
+ * not need a direct `@lit/task` dependency to read it.
+ */
+export type EtaTemplateStatus = TaskStatus;
+/**
+ * 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 declare class EtaTemplateController<TArgs extends readonly unknown[] = readonly unknown[], TContext extends object = DefaultEtaContext> implements ReactiveController {
+    #private;
+    readonly index: EtaTemplateIndexLike<TContext>;
+    private readonly host;
+    private readonly argsFn;
+    private readonly enabledFn;
+    private readonly contextFn;
+    private readonly onRenderError;
+    private readonly mutationBatchScheduleOption;
+    /**
+     * Cached boundary-element predicate, captured once in the
+     * constructor and forwarded to every shadow-root index through
+     * `_shadowBoundaryPredicate`. The controller is the single
+     * source of truth for the predicate — the host supplies it via
+     * `options.isBoundaryElement` and the controller threads the
+     * SAME predicate to every observed root (light + shadow).
+     *
+     * Captured up-front so `_shadowBoundaryPredicate` does not need
+     * to reach back into `this.options` at every shadow-binding
+     * creation. `undefined` when the host did not supply a
+     * predicate — preserves the pre-fix behaviour for those hosts.
+     */
+    private readonly _boundaryElementPredicate;
+    /**
+     * 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.
+     */
+    private readonly _seenShadows;
+    private readonly observer;
+    private readonly batcher;
+    private readonly task;
+    private readonly factory;
+    /**
+     * 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.
+     */
+    private shadowBindings;
+    constructor(host: EtaTemplateHost & ReactiveControllerHost, options: EtaTemplateControllerOptions<TArgs, TContext>);
+    /**
+     * 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(): void;
+    /**
+     * Status of the underlying Task.
+     *
+     * Exposed so consumers (e.g. tests) can assert progress without
+     * reaching into the `@lit/task` surface.
+     */
+    get status(): EtaTemplateStatus;
+    /**
+     * Latest context produced by a successful render pass.
+     */
+    get value(): TContext | undefined;
+    /**
+     * 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(): unknown;
+    /**
+     * 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(): Promise<TContext | undefined>;
+    /**
+     * 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.
+     */
+    requestRender(): Promise<TContext | undefined>;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): void;
+    /**
+     * 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(): EtaMutationBatchSchedule;
+    private _currentMutationBatchSchedule;
+    /**
+     * 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.
+     */
+    private _runRenderPass;
+    /**
+     * 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).
+     */
+    private _observerAttributeNames;
+    /**
+     * 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.
+     */
+    private _factoryOptions;
+    hostConnected(): void;
+    /**
+     * 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.
+     */
+    private _connectShadowRoots;
+    /**
+     * 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).
+     */
+    private _addShadowBinding;
+    /**
+     * 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.
+     */
+    private _discoverShadowRootsFor;
+    /**
+     * 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.
+     */
+    private _walkForShadows;
+    /**
+     * 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.
+     */
+    private _disconnectShadowRoots;
+    /**
+     * 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).
+     */
+    private _shadowBoundaryPredicate;
+    /**
+     * Cached normalized attribute name list. The controller
+     * computes this once in the constructor and reuses it for both
+     * the light-DOM observer and every shadow observer so a single
+     * allowlist applies across every observed root.
+     */
+    private readonly _normalizedAttributeNames;
+    hostDisconnected(): void;
+    /**
+     * 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(): void;
+}
+/**
+ * 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 declare function createEtaTemplateController<TArgs extends readonly unknown[] = readonly unknown[], TContext extends object = DefaultEtaContext>(host: EtaTemplateHost & ReactiveControllerHost, options: EtaTemplateControllerOptions<TArgs, TContext>): EtaTemplateController<TArgs, TContext>;