@repobit/dex-store-elements 1.7.3 → 2.0.0

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

@@ -0,0 +1,263 @@
+/**
+ * Options accepted by `EtaMutationObserver`.
+ */
+export interface EtaMutationObserverOptions {
+    /**
+     * Optional callback fired after a batch of mutations has been
+     * forwarded. The controller uses this to schedule a fresh
+     * render whenever the DOM has changed.
+     *
+     * The observer only raises `onChange` from
+     * `flushPendingRecords({ notify: true })` and from the
+     * `notify`-aware parts of `disconnect()` — the live
+     * `MutationObserver` callback path does NOT raise `onChange`
+     * because the consumer (typically the batcher) decides when
+     * to render from its own scheduling logic.
+     */
+    readonly onChange?: () => void;
+    /**
+     * Optional callback fired with the raw `MutationRecord[]` batch
+     * produced by the underlying `MutationObserver`.
+     *
+     * The observer's single responsibility is to translate browser
+     * MutationObserver records and forward them to this callback.
+     * The consumer (typically the `EtaMutationBatcher`) is
+     * responsible for folding the records into the index.
+     */
+    readonly onRecords?: (records: readonly MutationRecord[]) => void;
+    /**
+     * Optional predicate evaluated for each attribute record.
+     * Returning `false` drops the record entirely. Used to ignore
+     * attributes the consumer does not care about (e.g. `class` /
+     * `style` flips on Lit hosts).
+     *
+     * **Has no effect when `onRecords` is provided.** The observer
+     * forwards the raw record array to `onRecords` without
+     * filtering — the consumer owns the filtering decision. This
+     * avoids double-filtering the same record.
+     */
+    readonly isAttributeInteresting?: (name: string) => boolean;
+    /**
+     * Optional list of attribute names the underlying
+     * `MutationObserver` should watch. Passed through as
+     * `MutationObserverInit.attributeFilter` so the browser itself
+     * only emits records for the listed attributes — a much cheaper
+     * filter than letting every attribute flip fire a callback.
+     *
+     * `undefined` means "watch every attribute". Tests that do not
+     * care leave this unset.
+     */
+    readonly attributeNames?: readonly string[];
+}
+/**
+ * Translates browser `MutationObserver` records and forwards them
+ * as a raw `MutationRecord[]` batch to the optional `onRecords`
+ * callback.
+ *
+ * The observer is intentionally thin:
+ *
+ * - It knows about the DOM MutationRecord shape.
+ * - It does not know about Eta, scope, the index data structure, or
+ *   the factory.
+ *
+ * This lets us unit-test it without a real Eta instance, and lets
+ * the controller swap in a different consumer (for example, a
+ * batcher) without touching the observer.
+ *
+ * **Routing.** When `options.onRecords` is provided, the observer
+ * forwards the raw `MutationRecord[]` batch to that callback and
+ * stops. The batcher is the canonical consumer of this path.
+ * `onChange` is NOT raised from the live observer callback — the
+ * consumer decides when to render from its own scheduling logic.
+ *
+ * **Dirty signal.** Whether `onChange` fires depends on the
+ * `notify` option of `flushPendingRecords` /
+ * `disconnect({ flush, notify })`. The observer itself does not
+ * know whether forwarded records were dirty — that decision is
+ * the consumer's.
+ *
+ * Self-induced mutations (e.g. a `TextOperation.execute` writing a
+ * new `nodeValue`) are dropped during a `suspendSync(callback)` block.
+ * The controller wraps the render loop in `suspendSync(...)` so the
+ * records produced by the operations themselves do not get fed
+ * back to the consumer as fresh mutations. Before entering that
+ * block the controller also calls `flushPendingRecords({ notify:
+ * false })` so any external records already queued by the browser
+ * are forwarded first; otherwise the `takeRecords()` drain inside
+ * `suspendSync`'s `finally` would discard those external records
+ * together with the self-induced ones.
+ *
+ * **Attribute namespace scope.** Attribute observation currently
+ * treats attributes as `Element + string` (qualified name). SVG
+ * and other namespaced attributes are intentionally out of scope:
+ * the observer does not thread `MutationRecord.attributeNamespace`
+ * and the index/factory do not call `getAttributeNS`. Future
+ * versions that need namespace awareness should propagate
+ * `record.attributeNamespace` through whatever attribute branch
+ * the consumer uses and add a `getAttributeNS`-based path in the
+ * factory. For non-namespaced HTML, which is the current target
+ * surface, the qualified-name model is sufficient.
+ */
+export declare class EtaMutationObserver {
+    private readonly observer;
+    private readonly onChange?;
+    private readonly onRecords?;
+    private readonly isAttributeInteresting?;
+    private readonly attributeNames?;
+    private suspended;
+    constructor(options?: EtaMutationObserverOptions);
+    /**
+     * Starts observing the given target.
+     *
+     * `subtree: true` ensures the observer sees mutations in the
+     * entire scoped boundary, not just the direct children of
+     * `target`.
+     *
+     * If `attributeNames` was supplied to the constructor it is
+     * forwarded to the browser as
+     * `MutationObserverInit.attributeFilter`. The browser will then
+     * only emit attribute records for the listed attributes, which
+     * keeps noisy Lit updates (`class` / `style` / reactive
+     * properties) from triggering downstream work.
+     */
+    observe(target: Node): void;
+    /**
+     * Stops observing and releases the underlying MutationObserver.
+     *
+     * Two modes:
+     *
+     * - **`flush: true`** — drains any queued records through
+     *   `onRecords` BEFORE disconnecting, so any consumer (the
+     *   batcher) can absorb them. Use this from a controller's
+     *   `hostDisconnected()` so an external mutation that landed
+     *   just before disconnect is not silently dropped.
+     * - **`flush: false` (default, current behaviour)** — drains the
+     *   queue via `takeRecords()` only. Records are discarded
+     *   without ever being forwarded.
+     *
+     * In both modes the underlying `MutationObserver.disconnect()`
+     * is the last call so delivery is stopped after the drain.
+     *
+     * `notify` only takes effect when `flush: true`; it controls
+     * whether a successful flush invokes `onChange`. Callers that
+     * are about to teardown (for example `hostDisconnected()`)
+     * should pass `notify: false` to avoid scheduling a render
+     * during teardown.
+     */
+    disconnect(options?: {
+        flush?: boolean;
+        notify?: boolean;
+    }): void;
+    /**
+     * Drains any records currently queued by the underlying
+     * `MutationObserver` and forwards them to `onRecords`.
+     *
+     * The entire record batch is forwarded as-is — no per-record
+     * mapping is performed here. The consumer (the batcher) is
+     * responsible for folding records into the index.
+     *
+     * Use `flushPendingRecords()` when the controller is about to
+     * read the index and must not miss legitimate external
+     * mutations that landed between the last render and the next
+     * one. Without this flush, a render that starts inside
+     * `suspendSync(callback)` would call `takeRecords()` in its
+     * `finally` block and discard those external records together
+     * with the self-induced render records.
+     *
+     * Returns:
+     *
+     * - `true` when at least one record was forwarded, `false` when
+     *   the queue was empty. The caller cannot tell dirty from
+     *   non-dirty at this layer — the consumer decides dirty on
+     *   its own tick.
+     *
+     * **`notify` semantics.** Pass `notify: false` when the flush
+     * happens immediately before a render that is already running,
+     * to avoid re-entering `task.run()` from inside an in-flight
+     * render pass. Pass `notify: true` (the default) when the flush
+     * happens outside a render pass and the caller wants the
+     * observer's `onChange` scheduling to kick in.
+     *
+     * `flushPendingRecords()` is synchronous — the records are
+     * drained via `takeRecords()` and processed in the same call
+     * stack.
+     */
+    flushPendingRecords(options?: {
+        notify?: boolean;
+    }): boolean;
+    /**
+     * Drops any records currently queued by the underlying
+     * `MutationObserver` without forwarding them.
+     *
+     * Most callers should prefer `suspendSync(callback)` so the drain
+     * happens immediately after the work that produced the records,
+     * or `flushPendingRecords()` when the queued records might
+     * contain legitimate external mutations that need to reach the
+     * consumer. `takeRecords()` is exposed for tests and advanced
+     * consumers that need to inspect the drained records directly.
+     */
+    takeRecords(): MutationRecord[];
+    /**
+     * Runs `callback` while suspending record forwarding.
+     *
+     * While suspended, any records delivered by the underlying
+     * `MutationObserver` are dropped on the floor (no consumer
+     * notification, no `onChange` callback). This is the right
+     * mode for render passes that write to the DOM — the writes
+     * should not be fed back as fresh mutations.
+     *
+     * After `callback` returns, the observer drains whatever the
+     * underlying `MutationObserver` has queued via `takeRecords()` so
+     * subsequent ticks start from a clean slate.
+     *
+     * The flag is restored in a `finally` block so a thrown callback
+     * does not leave the observer stuck in the suspended state.
+     *
+     * **Sync-only.** Operation execution and the typical render pass
+     * are synchronous, so this method runs `callback` to completion
+     * before restoring forwarding. Calling `suspendSync()` with an
+     * async function will NOT keep records suppressed past the
+     * synchronous portion of the callback — once the callback returns
+     * its first `await` boundary (or the callback's promise settles)
+     * the suspended flag has already been cleared. If async
+     * suppression is ever needed, a separate `suspendAsync` method
+     * should be added; it is intentionally not provided today.
+     */
+    suspendSync(callback: () => void): void;
+    /**
+     * Handles a batch of records produced by the browser.
+     *
+     * Records are processed in the order returned by the browser.
+     *
+     * The entire record batch is forwarded to `onRecords` as-is and
+     * the method returns immediately. The consumer (the batcher) is
+     * responsible for folding records into the index; the observer
+     * no longer maps records into `TemplateIndexMutation` values
+     * inline. `onChange` is also NOT raised from this path — the
+     * consumer triggers renders from its own scheduling so that
+     * "dirty" is decided after compaction, not per record.
+     *
+     * While `suspended` is true the callback drops every record
+     * without forwarding it; this is the path used during a render
+     * pass to discard self-induced mutations.
+     *
+     * **Suspended guard is defensive.** During normal DOM
+     * scheduling MutationObserver callbacks do not fire in the
+     * middle of a synchronous callback — the browser queues
+     * records and delivers them via a microtask once the current
+     * call stack unwinds. Self-induced records from a render pass
+     * are drained via `takeRecords()` after `suspendSync()`
+     * returns, so the `suspended` flag is normally `false` by the
+     * time the callback fires. The guard exists to prevent
+     * `handleRecords()` from running if the observer is somehow
+     * invoked manually while suspended — for example by tests that
+     * drive the callback directly or by future scheduling that
+     * re-enters this method synchronously from inside a render
+     * pass.
+     */
+    private readonly handleRecords;
+}
+/**
+ * Convenience helper used by the default controller.
+ */
+export declare function createEtaMutationObserver(options?: EtaMutationObserverOptions): EtaMutationObserver;

package/dist/src/eta/observer.js

@@ -0,0 +1,263 @@
+// src/eta/observer.ts
+/**
+ * Translates browser `MutationObserver` records and forwards them
+ * as a raw `MutationRecord[]` batch to the optional `onRecords`
+ * callback.
+ *
+ * The observer is intentionally thin:
+ *
+ * - It knows about the DOM MutationRecord shape.
+ * - It does not know about Eta, scope, the index data structure, or
+ *   the factory.
+ *
+ * This lets us unit-test it without a real Eta instance, and lets
+ * the controller swap in a different consumer (for example, a
+ * batcher) without touching the observer.
+ *
+ * **Routing.** When `options.onRecords` is provided, the observer
+ * forwards the raw `MutationRecord[]` batch to that callback and
+ * stops. The batcher is the canonical consumer of this path.
+ * `onChange` is NOT raised from the live observer callback — the
+ * consumer decides when to render from its own scheduling logic.
+ *
+ * **Dirty signal.** Whether `onChange` fires depends on the
+ * `notify` option of `flushPendingRecords` /
+ * `disconnect({ flush, notify })`. The observer itself does not
+ * know whether forwarded records were dirty — that decision is
+ * the consumer's.
+ *
+ * Self-induced mutations (e.g. a `TextOperation.execute` writing a
+ * new `nodeValue`) are dropped during a `suspendSync(callback)` block.
+ * The controller wraps the render loop in `suspendSync(...)` so the
+ * records produced by the operations themselves do not get fed
+ * back to the consumer as fresh mutations. Before entering that
+ * block the controller also calls `flushPendingRecords({ notify:
+ * false })` so any external records already queued by the browser
+ * are forwarded first; otherwise the `takeRecords()` drain inside
+ * `suspendSync`'s `finally` would discard those external records
+ * together with the self-induced ones.
+ *
+ * **Attribute namespace scope.** Attribute observation currently
+ * treats attributes as `Element + string` (qualified name). SVG
+ * and other namespaced attributes are intentionally out of scope:
+ * the observer does not thread `MutationRecord.attributeNamespace`
+ * and the index/factory do not call `getAttributeNS`. Future
+ * versions that need namespace awareness should propagate
+ * `record.attributeNamespace` through whatever attribute branch
+ * the consumer uses and add a `getAttributeNS`-based path in the
+ * factory. For non-namespaced HTML, which is the current target
+ * surface, the qualified-name model is sufficient.
+ */
+export class EtaMutationObserver {
+    constructor(options) {
+        this.suspended = false;
+        /**
+         * Handles a batch of records produced by the browser.
+         *
+         * Records are processed in the order returned by the browser.
+         *
+         * The entire record batch is forwarded to `onRecords` as-is and
+         * the method returns immediately. The consumer (the batcher) is
+         * responsible for folding records into the index; the observer
+         * no longer maps records into `TemplateIndexMutation` values
+         * inline. `onChange` is also NOT raised from this path — the
+         * consumer triggers renders from its own scheduling so that
+         * "dirty" is decided after compaction, not per record.
+         *
+         * While `suspended` is true the callback drops every record
+         * without forwarding it; this is the path used during a render
+         * pass to discard self-induced mutations.
+         *
+         * **Suspended guard is defensive.** During normal DOM
+         * scheduling MutationObserver callbacks do not fire in the
+         * middle of a synchronous callback — the browser queues
+         * records and delivers them via a microtask once the current
+         * call stack unwinds. Self-induced records from a render pass
+         * are drained via `takeRecords()` after `suspendSync()`
+         * returns, so the `suspended` flag is normally `false` by the
+         * time the callback fires. The guard exists to prevent
+         * `handleRecords()` from running if the observer is somehow
+         * invoked manually while suspended — for example by tests that
+         * drive the callback directly or by future scheduling that
+         * re-enters this method synchronously from inside a render
+         * pass.
+         */
+        this.handleRecords = (records) => {
+            if (this.suspended) {
+                return;
+            }
+            this.onRecords?.(records);
+        };
+        this.onChange = options?.onChange;
+        this.onRecords = options?.onRecords;
+        this.isAttributeInteresting =
+            options?.isAttributeInteresting;
+        this.attributeNames = options?.attributeNames;
+        this.observer = new MutationObserver(this.handleRecords);
+    }
+    /**
+     * Starts observing the given target.
+     *
+     * `subtree: true` ensures the observer sees mutations in the
+     * entire scoped boundary, not just the direct children of
+     * `target`.
+     *
+     * If `attributeNames` was supplied to the constructor it is
+     * forwarded to the browser as
+     * `MutationObserverInit.attributeFilter`. The browser will then
+     * only emit attribute records for the listed attributes, which
+     * keeps noisy Lit updates (`class` / `style` / reactive
+     * properties) from triggering downstream work.
+     */
+    observe(target) {
+        const init = {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            characterData: true
+        };
+        if (this.attributeNames &&
+            this.attributeNames.length > 0) {
+            init.attributeFilter = [
+                ...this.attributeNames
+            ];
+        }
+        this.observer.observe(target, init);
+    }
+    /**
+     * Stops observing and releases the underlying MutationObserver.
+     *
+     * Two modes:
+     *
+     * - **`flush: true`** — drains any queued records through
+     *   `onRecords` BEFORE disconnecting, so any consumer (the
+     *   batcher) can absorb them. Use this from a controller's
+     *   `hostDisconnected()` so an external mutation that landed
+     *   just before disconnect is not silently dropped.
+     * - **`flush: false` (default, current behaviour)** — drains the
+     *   queue via `takeRecords()` only. Records are discarded
+     *   without ever being forwarded.
+     *
+     * In both modes the underlying `MutationObserver.disconnect()`
+     * is the last call so delivery is stopped after the drain.
+     *
+     * `notify` only takes effect when `flush: true`; it controls
+     * whether a successful flush invokes `onChange`. Callers that
+     * are about to teardown (for example `hostDisconnected()`)
+     * should pass `notify: false` to avoid scheduling a render
+     * during teardown.
+     */
+    disconnect(options = {}) {
+        if (options.flush === true) {
+            this.flushPendingRecords({
+                notify: options.notify
+            });
+        }
+        else {
+            this.observer.takeRecords();
+        }
+        this.observer.disconnect();
+    }
+    /**
+     * Drains any records currently queued by the underlying
+     * `MutationObserver` and forwards them to `onRecords`.
+     *
+     * The entire record batch is forwarded as-is — no per-record
+     * mapping is performed here. The consumer (the batcher) is
+     * responsible for folding records into the index.
+     *
+     * Use `flushPendingRecords()` when the controller is about to
+     * read the index and must not miss legitimate external
+     * mutations that landed between the last render and the next
+     * one. Without this flush, a render that starts inside
+     * `suspendSync(callback)` would call `takeRecords()` in its
+     * `finally` block and discard those external records together
+     * with the self-induced render records.
+     *
+     * Returns:
+     *
+     * - `true` when at least one record was forwarded, `false` when
+     *   the queue was empty. The caller cannot tell dirty from
+     *   non-dirty at this layer — the consumer decides dirty on
+     *   its own tick.
+     *
+     * **`notify` semantics.** Pass `notify: false` when the flush
+     * happens immediately before a render that is already running,
+     * to avoid re-entering `task.run()` from inside an in-flight
+     * render pass. Pass `notify: true` (the default) when the flush
+     * happens outside a render pass and the caller wants the
+     * observer's `onChange` scheduling to kick in.
+     *
+     * `flushPendingRecords()` is synchronous — the records are
+     * drained via `takeRecords()` and processed in the same call
+     * stack.
+     */
+    flushPendingRecords(options = {}) {
+        const records = this.observer.takeRecords();
+        if (records.length === 0) {
+            return false;
+        }
+        this.onRecords?.(records);
+        if (options.notify !== false) {
+            this.onChange?.();
+        }
+        return true;
+    }
+    /**
+     * Drops any records currently queued by the underlying
+     * `MutationObserver` without forwarding them.
+     *
+     * Most callers should prefer `suspendSync(callback)` so the drain
+     * happens immediately after the work that produced the records,
+     * or `flushPendingRecords()` when the queued records might
+     * contain legitimate external mutations that need to reach the
+     * consumer. `takeRecords()` is exposed for tests and advanced
+     * consumers that need to inspect the drained records directly.
+     */
+    takeRecords() {
+        return this.observer.takeRecords();
+    }
+    /**
+     * Runs `callback` while suspending record forwarding.
+     *
+     * While suspended, any records delivered by the underlying
+     * `MutationObserver` are dropped on the floor (no consumer
+     * notification, no `onChange` callback). This is the right
+     * mode for render passes that write to the DOM — the writes
+     * should not be fed back as fresh mutations.
+     *
+     * After `callback` returns, the observer drains whatever the
+     * underlying `MutationObserver` has queued via `takeRecords()` so
+     * subsequent ticks start from a clean slate.
+     *
+     * The flag is restored in a `finally` block so a thrown callback
+     * does not leave the observer stuck in the suspended state.
+     *
+     * **Sync-only.** Operation execution and the typical render pass
+     * are synchronous, so this method runs `callback` to completion
+     * before restoring forwarding. Calling `suspendSync()` with an
+     * async function will NOT keep records suppressed past the
+     * synchronous portion of the callback — once the callback returns
+     * its first `await` boundary (or the callback's promise settles)
+     * the suspended flag has already been cleared. If async
+     * suppression is ever needed, a separate `suspendAsync` method
+     * should be added; it is intentionally not provided today.
+     */
+    suspendSync(callback) {
+        this.suspended = true;
+        try {
+            callback();
+        }
+        finally {
+            this.suspended = false;
+            this.observer.takeRecords();
+        }
+    }
+}
+/**
+ * Convenience helper used by the default controller.
+ */
+export function createEtaMutationObserver(options) {
+    return new EtaMutationObserver(options);
+}
+//# sourceMappingURL=observer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../../src/eta/observer.ts"],"names":[],"mappings":"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","sourcesContent":["// src/eta/observer.ts\n\n/**\n * Options accepted by `EtaMutationObserver`.\n */\nexport interface EtaMutationObserverOptions {\n  /**\n   * Optional callback fired after a batch of mutations has been\n   * forwarded. The controller uses this to schedule a fresh\n   * render whenever the DOM has changed.\n   *\n   * The observer only raises `onChange` from\n   * `flushPendingRecords({ notify: true })` and from the\n   * `notify`-aware parts of `disconnect()` — the live\n   * `MutationObserver` callback path does NOT raise `onChange`\n   * because the consumer (typically the batcher) decides when\n   * to render from its own scheduling logic.\n   */\n  readonly onChange?: () => void;\n\n  /**\n   * Optional callback fired with the raw `MutationRecord[]` batch\n   * produced by the underlying `MutationObserver`.\n   *\n   * The observer's single responsibility is to translate browser\n   * MutationObserver records and forward them to this callback.\n   * The consumer (typically the `EtaMutationBatcher`) is\n   * responsible for folding the records into the index.\n   */\n  readonly onRecords?: (\n    records: readonly MutationRecord[]\n  ) => void;\n\n  /**\n   * Optional predicate evaluated for each attribute record.\n   * Returning `false` drops the record entirely. Used to ignore\n   * attributes the consumer does not care about (e.g. `class` /\n   * `style` flips on Lit hosts).\n   *\n   * **Has no effect when `onRecords` is provided.** The observer\n   * forwards the raw record array to `onRecords` without\n   * filtering — the consumer owns the filtering decision. This\n   * avoids double-filtering the same record.\n   */\n  readonly isAttributeInteresting?: (\n    name: string\n  ) => boolean;\n\n  /**\n   * Optional list of attribute names the underlying\n   * `MutationObserver` should watch. Passed through as\n   * `MutationObserverInit.attributeFilter` so the browser itself\n   * only emits records for the listed attributes — a much cheaper\n   * filter than letting every attribute flip fire a callback.\n   *\n   * `undefined` means \"watch every attribute\". Tests that do not\n   * care leave this unset.\n   */\n  readonly attributeNames?: readonly string[];\n}\n\n/**\n * Translates browser `MutationObserver` records and forwards them\n * as a raw `MutationRecord[]` batch to the optional `onRecords`\n * callback.\n *\n * The observer is intentionally thin:\n *\n * - It knows about the DOM MutationRecord shape.\n * - It does not know about Eta, scope, the index data structure, or\n *   the factory.\n *\n * This lets us unit-test it without a real Eta instance, and lets\n * the controller swap in a different consumer (for example, a\n * batcher) without touching the observer.\n *\n * **Routing.** When `options.onRecords` is provided, the observer\n * forwards the raw `MutationRecord[]` batch to that callback and\n * stops. The batcher is the canonical consumer of this path.\n * `onChange` is NOT raised from the live observer callback — the\n * consumer decides when to render from its own scheduling logic.\n *\n * **Dirty signal.** Whether `onChange` fires depends on the\n * `notify` option of `flushPendingRecords` /\n * `disconnect({ flush, notify })`. The observer itself does not\n * know whether forwarded records were dirty — that decision is\n * the consumer's.\n *\n * Self-induced mutations (e.g. a `TextOperation.execute` writing a\n * new `nodeValue`) are dropped during a `suspendSync(callback)` block.\n * The controller wraps the render loop in `suspendSync(...)` so the\n * records produced by the operations themselves do not get fed\n * back to the consumer as fresh mutations. Before entering that\n * block the controller also calls `flushPendingRecords({ notify:\n * false })` so any external records already queued by the browser\n * are forwarded first; otherwise the `takeRecords()` drain inside\n * `suspendSync`'s `finally` would discard those external records\n * together with the self-induced ones.\n *\n * **Attribute namespace scope.** Attribute observation currently\n * treats attributes as `Element + string` (qualified name). SVG\n * and other namespaced attributes are intentionally out of scope:\n * the observer does not thread `MutationRecord.attributeNamespace`\n * and the index/factory do not call `getAttributeNS`. Future\n * versions that need namespace awareness should propagate\n * `record.attributeNamespace` through whatever attribute branch\n * the consumer uses and add a `getAttributeNS`-based path in the\n * factory. For non-namespaced HTML, which is the current target\n * surface, the qualified-name model is sufficient.\n */\nexport class EtaMutationObserver {\n  private readonly observer: MutationObserver;\n\n  private readonly onChange? : () => void;\n  private readonly onRecords?             : (\n    records: readonly MutationRecord[]\n  ) => void;\n  private readonly isAttributeInteresting?: (\n    name: string\n  ) => boolean;\n  private readonly attributeNames?: readonly string[];\n  private suspended = false;\n\n  constructor(options?: EtaMutationObserverOptions) {\n    this.onChange = options?.onChange;\n    this.onRecords = options?.onRecords;\n    this.isAttributeInteresting =\n      options?.isAttributeInteresting;\n    this.attributeNames = options?.attributeNames;\n\n    this.observer = new MutationObserver(\n      this.handleRecords\n    );\n  }\n\n  /**\n   * Starts observing the given target.\n   *\n   * `subtree: true` ensures the observer sees mutations in the\n   * entire scoped boundary, not just the direct children of\n   * `target`.\n   *\n   * If `attributeNames` was supplied to the constructor it is\n   * forwarded to the browser as\n   * `MutationObserverInit.attributeFilter`. The browser will then\n   * only emit attribute records for the listed attributes, which\n   * keeps noisy Lit updates (`class` / `style` / reactive\n   * properties) from triggering downstream work.\n   */\n  observe(target: Node): void {\n    const init: MutationObserverInit = {\n      childList    : true,\n      subtree      : true,\n      attributes   : true,\n      characterData: true\n    };\n\n    if (\n      this.attributeNames &&\n      this.attributeNames.length > 0\n    ) {\n      init.attributeFilter = [\n        ...this.attributeNames\n      ];\n    }\n\n    this.observer.observe(target, init);\n  }\n\n  /**\n   * Stops observing and releases the underlying MutationObserver.\n   *\n   * Two modes:\n   *\n   * - **`flush: true`** — drains any queued records through\n   *   `onRecords` BEFORE disconnecting, so any consumer (the\n   *   batcher) can absorb them. Use this from a controller's\n   *   `hostDisconnected()` so an external mutation that landed\n   *   just before disconnect is not silently dropped.\n   * - **`flush: false` (default, current behaviour)** — drains the\n   *   queue via `takeRecords()` only. Records are discarded\n   *   without ever being forwarded.\n   *\n   * In both modes the underlying `MutationObserver.disconnect()`\n   * is the last call so delivery is stopped after the drain.\n   *\n   * `notify` only takes effect when `flush: true`; it controls\n   * whether a successful flush invokes `onChange`. Callers that\n   * are about to teardown (for example `hostDisconnected()`)\n   * should pass `notify: false` to avoid scheduling a render\n   * during teardown.\n   */\n  disconnect(\n    options: {\n      flush? : boolean;\n      notify?: boolean;\n    } = {}\n  ): void {\n    if (options.flush === true) {\n      this.flushPendingRecords({\n        notify: options.notify\n      });\n    } else {\n      this.observer.takeRecords();\n    }\n\n    this.observer.disconnect();\n  }\n\n  /**\n   * Drains any records currently queued by the underlying\n   * `MutationObserver` and forwards them to `onRecords`.\n   *\n   * The entire record batch is forwarded as-is — no per-record\n   * mapping is performed here. The consumer (the batcher) is\n   * responsible for folding records into the index.\n   *\n   * Use `flushPendingRecords()` when the controller is about to\n   * read the index and must not miss legitimate external\n   * mutations that landed between the last render and the next\n   * one. Without this flush, a render that starts inside\n   * `suspendSync(callback)` would call `takeRecords()` in its\n   * `finally` block and discard those external records together\n   * with the self-induced render records.\n   *\n   * Returns:\n   *\n   * - `true` when at least one record was forwarded, `false` when\n   *   the queue was empty. The caller cannot tell dirty from\n   *   non-dirty at this layer — the consumer decides dirty on\n   *   its own tick.\n   *\n   * **`notify` semantics.** Pass `notify: false` when the flush\n   * happens immediately before a render that is already running,\n   * to avoid re-entering `task.run()` from inside an in-flight\n   * render pass. Pass `notify: true` (the default) when the flush\n   * happens outside a render pass and the caller wants the\n   * observer's `onChange` scheduling to kick in.\n   *\n   * `flushPendingRecords()` is synchronous — the records are\n   * drained via `takeRecords()` and processed in the same call\n   * stack.\n   */\n  flushPendingRecords(\n    options: { notify?: boolean } = {}\n  ): boolean {\n    const records = this.observer.takeRecords();\n\n    if (records.length === 0) {\n      return false;\n    }\n\n    this.onRecords?.(records);\n\n    if (options.notify !== false) {\n      this.onChange?.();\n    }\n\n    return true;\n  }\n\n  /**\n   * Drops any records currently queued by the underlying\n   * `MutationObserver` without forwarding them.\n   *\n   * Most callers should prefer `suspendSync(callback)` so the drain\n   * happens immediately after the work that produced the records,\n   * or `flushPendingRecords()` when the queued records might\n   * contain legitimate external mutations that need to reach the\n   * consumer. `takeRecords()` is exposed for tests and advanced\n   * consumers that need to inspect the drained records directly.\n   */\n  takeRecords(): MutationRecord[] {\n    return this.observer.takeRecords();\n  }\n\n  /**\n   * Runs `callback` while suspending record forwarding.\n   *\n   * While suspended, any records delivered by the underlying\n   * `MutationObserver` are dropped on the floor (no consumer\n   * notification, no `onChange` callback). This is the right\n   * mode for render passes that write to the DOM — the writes\n   * should not be fed back as fresh mutations.\n   *\n   * After `callback` returns, the observer drains whatever the\n   * underlying `MutationObserver` has queued via `takeRecords()` so\n   * subsequent ticks start from a clean slate.\n   *\n   * The flag is restored in a `finally` block so a thrown callback\n   * does not leave the observer stuck in the suspended state.\n   *\n   * **Sync-only.** Operation execution and the typical render pass\n   * are synchronous, so this method runs `callback` to completion\n   * before restoring forwarding. Calling `suspendSync()` with an\n   * async function will NOT keep records suppressed past the\n   * synchronous portion of the callback — once the callback returns\n   * its first `await` boundary (or the callback's promise settles)\n   * the suspended flag has already been cleared. If async\n   * suppression is ever needed, a separate `suspendAsync` method\n   * should be added; it is intentionally not provided today.\n   */\n  suspendSync(callback: () => void): void {\n    this.suspended = true;\n\n    try {\n      callback();\n    } finally {\n      this.suspended = false;\n      this.observer.takeRecords();\n    }\n  }\n\n  /**\n   * Handles a batch of records produced by the browser.\n   *\n   * Records are processed in the order returned by the browser.\n   *\n   * The entire record batch is forwarded to `onRecords` as-is and\n   * the method returns immediately. The consumer (the batcher) is\n   * responsible for folding records into the index; the observer\n   * no longer maps records into `TemplateIndexMutation` values\n   * inline. `onChange` is also NOT raised from this path — the\n   * consumer triggers renders from its own scheduling so that\n   * \"dirty\" is decided after compaction, not per record.\n   *\n   * While `suspended` is true the callback drops every record\n   * without forwarding it; this is the path used during a render\n   * pass to discard self-induced mutations.\n   *\n   * **Suspended guard is defensive.** During normal DOM\n   * scheduling MutationObserver callbacks do not fire in the\n   * middle of a synchronous callback — the browser queues\n   * records and delivers them via a microtask once the current\n   * call stack unwinds. Self-induced records from a render pass\n   * are drained via `takeRecords()` after `suspendSync()`\n   * returns, so the `suspended` flag is normally `false` by the\n   * time the callback fires. The guard exists to prevent\n   * `handleRecords()` from running if the observer is somehow\n   * invoked manually while suspended — for example by tests that\n   * drive the callback directly or by future scheduling that\n   * re-enters this method synchronously from inside a render\n   * pass.\n   */\n  private readonly handleRecords = (\n    records: MutationRecord[]\n  ): void => {\n    if (this.suspended) {\n      return;\n    }\n\n    this.onRecords?.(records);\n  };\n}\n\n/**\n * Convenience helper used by the default controller.\n */\nexport function createEtaMutationObserver(\n  options?: EtaMutationObserverOptions\n): EtaMutationObserver {\n  return new EtaMutationObserver(options);\n}\n"]}

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

@@ -0,0 +1,41 @@
+import type { EtaCompiledTemplate, TemplateOperation } from './types.js';
+/**
+ * Renders a text node from a compiled Eta template.
+ *
+ * The text node's `nodeValue` is overwritten with the rendered
+ * string on every `execute` call. This matches how Eta is used
+ * elsewhere in the codebase: templates produce text output and the
+ * runtime writes that text into the DOM.
+ *
+ * `dispose` is a no-op for text operations; the GC reclaims the
+ * closure once the index drops the reference.
+ */
+export declare class TextOperation<TContext = object> implements TemplateOperation<TContext> {
+    readonly owner: Text;
+    private readonly template;
+    readonly kind: "text";
+    constructor(owner: Text, template: EtaCompiledTemplate);
+    execute(context: TContext): void;
+    dispose(): void;
+}
+/**
+ * Renders a single attribute on an element from a compiled Eta
+ * template.
+ *
+ * Every rendered value — including the empty string — is written
+ * via `setAttribute`. The runtime does not remove attributes as a
+ * side-effect of rendering; an empty template result is a valid
+ * attribute value and removing the attribute would change the
+ * element's semantics (e.g. `<input>` vs `<input value="">`).
+ *
+ * `dispose` is a no-op for attribute operations.
+ */
+export declare class AttributeOperation<TContext = object> implements TemplateOperation<TContext> {
+    readonly owner: Element;
+    private readonly qualifiedName;
+    private readonly template;
+    readonly kind: "attribute";
+    constructor(owner: Element, qualifiedName: string, template: EtaCompiledTemplate);
+    execute(context: TContext): void;
+    dispose(): void;
+}

package/dist/src/eta/operations.js

@@ -0,0 +1,59 @@
+// src/eta/operations.ts
+/**
+ * Renders a text node from a compiled Eta template.
+ *
+ * The text node's `nodeValue` is overwritten with the rendered
+ * string on every `execute` call. This matches how Eta is used
+ * elsewhere in the codebase: templates produce text output and the
+ * runtime writes that text into the DOM.
+ *
+ * `dispose` is a no-op for text operations; the GC reclaims the
+ * closure once the index drops the reference.
+ */
+export class TextOperation {
+    constructor(owner, template) {
+        this.owner = owner;
+        this.template = template;
+        this.kind = 'text';
+    }
+    execute(context) {
+        const rendered = this.template(context);
+        if (this.owner.nodeValue !== rendered) {
+            this.owner.nodeValue = rendered;
+        }
+    }
+    dispose() {
+        // TextOperation holds no listeners or observers.
+    }
+}
+/**
+ * Renders a single attribute on an element from a compiled Eta
+ * template.
+ *
+ * Every rendered value — including the empty string — is written
+ * via `setAttribute`. The runtime does not remove attributes as a
+ * side-effect of rendering; an empty template result is a valid
+ * attribute value and removing the attribute would change the
+ * element's semantics (e.g. `<input>` vs `<input value="">`).
+ *
+ * `dispose` is a no-op for attribute operations.
+ */
+export class AttributeOperation {
+    constructor(owner, qualifiedName, template) {
+        this.owner = owner;
+        this.qualifiedName = qualifiedName;
+        this.template = template;
+        this.kind = 'attribute';
+    }
+    execute(context) {
+        const rendered = this.template(context);
+        const current = this.owner.getAttribute(this.qualifiedName);
+        if (current !== rendered) {
+            this.owner.setAttribute(this.qualifiedName, rendered);
+        }
+    }
+    dispose() {
+        // AttributeOperation holds no listeners or observers.
+    }
+}
+//# sourceMappingURL=operations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/eta/operations.ts"],"names":[],"mappings":"AAAA,wBAAwB;AAOxB;;;;;;;;;;GAUG;AACH,MAAM,OAAO,aAAa;IAKxB,YACW,KAAW,EACH,QAA6B;QADrC,UAAK,GAAL,KAAK,CAAM;QACH,aAAQ,GAAR,QAAQ,CAAqB;QAJvC,SAAI,GAAG,MAAe,CAAC;IAK7B,CAAC;IAEJ,OAAO,CAAC,OAAiB;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAC5B,OAA4B,CAC7B,CAAC;QAEF,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;YACtC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,QAAQ,CAAC;QAClC,CAAC;IACH,CAAC;IAED,OAAO;QACL,iDAAiD;IACnD,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,kBAAkB;IAM7B,YACW,KAAc,EACN,aAAqB,EACrB,QAA6B;QAFrC,UAAK,GAAL,KAAK,CAAS;QACN,kBAAa,GAAb,aAAa,CAAQ;QACrB,aAAQ,GAAR,QAAQ,CAAqB;QALvC,SAAI,GAAG,WAAoB,CAAC;IAMlC,CAAC;IAEJ,OAAO,CAAC,OAAiB;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAC5B,OAA4B,CAC7B,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CACrC,IAAI,CAAC,aAAa,CACnB,CAAC;QAEF,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,YAAY,CACrB,IAAI,CAAC,aAAa,EAClB,QAAQ,CACT,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,sDAAsD;IACxD,CAAC;CACF","sourcesContent":["// src/eta/operations.ts\n\nimport type {\n  EtaCompiledTemplate,\n  TemplateOperation\n} from './types.js';\n\n/**\n * Renders a text node from a compiled Eta template.\n *\n * The text node's `nodeValue` is overwritten with the rendered\n * string on every `execute` call. This matches how Eta is used\n * elsewhere in the codebase: templates produce text output and the\n * runtime writes that text into the DOM.\n *\n * `dispose` is a no-op for text operations; the GC reclaims the\n * closure once the index drops the reference.\n */\nexport class TextOperation<TContext = object>\nimplements TemplateOperation<TContext>\n{\n  readonly kind = 'text' as const;\n\n  constructor(\n    readonly owner: Text,\n    private readonly template: EtaCompiledTemplate\n  ) {}\n\n  execute(context: TContext): void {\n    const rendered = this.template(\n      context as unknown as object\n    );\n\n    if (this.owner.nodeValue !== rendered) {\n      this.owner.nodeValue = rendered;\n    }\n  }\n\n  dispose(): void {\n    // TextOperation holds no listeners or observers.\n  }\n}\n\n/**\n * Renders a single attribute on an element from a compiled Eta\n * template.\n *\n * Every rendered value — including the empty string — is written\n * via `setAttribute`. The runtime does not remove attributes as a\n * side-effect of rendering; an empty template result is a valid\n * attribute value and removing the attribute would change the\n * element's semantics (e.g. `<input>` vs `<input value=\"\">`).\n *\n * `dispose` is a no-op for attribute operations.\n */\nexport class AttributeOperation<\n  TContext = object\n> implements TemplateOperation<TContext>\n{\n  readonly kind = 'attribute' as const;\n\n  constructor(\n    readonly owner: Element,\n    private readonly qualifiedName: string,\n    private readonly template: EtaCompiledTemplate\n  ) {}\n\n  execute(context: TContext): void {\n    const rendered = this.template(\n      context as unknown as object\n    );\n\n    const current = this.owner.getAttribute(\n      this.qualifiedName\n    );\n\n    if (current !== rendered) {\n      this.owner.setAttribute(\n        this.qualifiedName,\n        rendered\n      );\n    }\n  }\n\n  dispose(): void {\n    // AttributeOperation holds no listeners or observers.\n  }\n}\n"]}