@repobit/dex-store-elements 1.7.2 → 2.0.0

package/dist/src/controllers/controller.compute.js

@@ -0,0 +1,110 @@
+// src/controllers/controller.compute.ts
+import { expandScenarios, reducePriceRange } from '../compute/compute.expand.js';
+import { mergeComputeScans } from '../compute/compute.scan.js';
+import { scenarioKey } from '../compute/option-resolver.js';
+import { BdResolveController } from './controller.resolve.js';
+export const BD_COMPUTE_CHANGED_EVENT = 'bd-compute-changed';
+/**
+ * Dry-run min/max price compute over every product/option combination reachable
+ * from a bd node boundary.
+ *
+ * It never dispatches bd-action-request. It reads resolved option seeds and
+ * collected action declarations from topology, expands them against the same
+ * command shapes the runtime would honor, and reduces price. Reruns are driven
+ * by the store scope, the resolved seed set, and the action topology revision.
+ */
+export class BdComputeController {
+    constructor(host, options) {
+        this.host = host;
+        this.options = options;
+        host.addController(this);
+        this._resolver = new BdResolveController(host, {
+            name: options.name ?? 'bd-compute',
+            args: () => [
+                this.options.store(),
+                this._enabled(),
+                optionSeedsKey(this.host.collectOptionSeeds()),
+                this._revision()
+            ],
+            enabled: ([store, enabled]) => Boolean(store) &&
+                enabled,
+            resolve: async ([store], context) => await this._compute(store, context),
+            commit: (result) => {
+                this._publish(result);
+            },
+            onDisabled: () => {
+                this._publish(undefined);
+            }
+        });
+    }
+    hostConnected() {
+        // BdResolveController owns compute scheduling.
+    }
+    hostDisconnected() {
+        // BdResolveController owns compute cancellation.
+    }
+    get pending() {
+        return this._resolver.pending;
+    }
+    get complete() {
+        return this._resolver.complete;
+    }
+    get failed() {
+        return this._resolver.failed;
+    }
+    get error() {
+        return this._resolver.error;
+    }
+    async run() {
+        return await this._resolver.run();
+    }
+    async _compute(store, context) {
+        if (!store) {
+            return undefined;
+        }
+        const seeds = this.host.collectOptionSeeds()
+            .map(optionToScenario);
+        if (seeds.length === 0) {
+            return undefined;
+        }
+        const scan = mergeComputeScans(this.host.collectActionScans());
+        const scenarios = await expandScenarios({
+            store,
+            seeds,
+            staticCommands: scan.staticCommands,
+            domains: scan.domains,
+            signal: context.signal,
+            maxScenarios: this.options.maxScenarios
+        });
+        return reducePriceRange(scenarios);
+    }
+    _publish(result) {
+        this.result = result;
+        this.options.onResult?.(result);
+        this.host.dispatchEvent(new CustomEvent(BD_COMPUTE_CHANGED_EVENT, {
+            bubbles: true,
+            composed: true,
+            detail: { result }
+        }));
+    }
+    _revision() {
+        return (this.options.revision?.() ??
+            this.host.actionTopologyRevision);
+    }
+    _enabled() {
+        return this.options.enabled?.() ?? true;
+    }
+}
+function optionToScenario(option) {
+    return {
+        product: option.getProduct(),
+        option
+    };
+}
+function optionSeedsKey(options) {
+    return options
+        .map((option) => scenarioKey(optionToScenario(option)))
+        .sort()
+        .join(';');
+}
+//# sourceMappingURL=controller.compute.js.map

package/dist/src/controllers/controller.compute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.compute.js","sourceRoot":"","sources":["../../../src/controllers/controller.compute.ts"],"names":[],"mappings":"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","sourcesContent":["// src/controllers/controller.compute.ts\n\nimport {\n  expandScenarios,\n  reducePriceRange,\n  type BdComputeResult\n} from '@/compute/compute.expand.js';\nimport {\n  mergeComputeScans,\n  type BdComputeScan\n} from '@/compute/compute.scan.js';\nimport {\n  scenarioKey,\n  type BdOptionScenario\n} from '@/compute/option-resolver.js';\nimport type {\n  ProductOption,\n  Store\n} from '@repobit/dex-store';\nimport type { ReactiveController } from 'lit';\nimport {\n  BdResolveController,\n  type BdResolveContext,\n  type BdResolveHost\n} from './controller.resolve.js';\n\nexport const BD_COMPUTE_CHANGED_EVENT = 'bd-compute-changed' as const;\n\nexport type BdComputeChangedDetail = Readonly<{\n  result?: BdComputeResult;\n}>;\n\ndeclare global {\n  interface HTMLElementEventMap {\n    [BD_COMPUTE_CHANGED_EVENT]: CustomEvent<BdComputeChangedDetail>;\n  }\n}\n\n/**\n * Host requirements for the compute controller. Any BdNodeElement satisfies\n * this: it tracks local work, is an EventTarget, can query its own subtree, and\n * exposes the incremental action topology.\n */\nexport interface BdComputeHost extends BdResolveHost, EventTarget, ParentNode {\n  readonly actionTopologyRevision: number;\n  collectActionScans(): BdComputeScan[];\n  collectOptionSeeds(): ProductOption[];\n}\n\nexport interface BdComputeOptions {\n  name?: string;\n\n  /**\n   * The store used to resolve products. Usually `() => this.scope?.store`.\n   */\n  store: () => Store | undefined;\n\n  /**\n   * Global/local compute switch. Disabled compute publishes an undefined result.\n   */\n  enabled?: () => boolean;\n\n  /**\n   * Extra change signal mixed into the task args. Defaults to the host's action\n   * topology revision, which already bumps on action and bd-subtree changes.\n   */\n  revision?: () => number;\n\n  /**\n   * Safety cap on the fixed-point search size.\n   */\n  maxScenarios?: number;\n\n  onResult?: (result: BdComputeResult | undefined) => void;\n}\n\ntype BdComputeArgs = readonly [\n  store: Store | undefined,\n  enabled: boolean,\n  seedsKey: string,\n  revision: number\n];\n\n/**\n * Dry-run min/max price compute over every product/option combination reachable\n * from a bd node boundary.\n *\n * It never dispatches bd-action-request. It reads resolved option seeds and\n * collected action declarations from topology, expands them against the same\n * command shapes the runtime would honor, and reduces price. Reruns are driven\n * by the store scope, the resolved seed set, and the action topology revision.\n */\nexport class BdComputeController implements ReactiveController {\n  result?: BdComputeResult;\n\n  private readonly _resolver: BdResolveController<BdComputeArgs, BdComputeResult | undefined>;\n\n  constructor(\n    private readonly host: BdComputeHost,\n    private readonly options: BdComputeOptions\n  ) {\n    host.addController(this);\n\n    this._resolver = new BdResolveController<BdComputeArgs, BdComputeResult | undefined>(\n      host,\n      {\n        name: options.name ?? 'bd-compute',\n\n        args: () =>\n          [\n            this.options.store(),\n            this._enabled(),\n            optionSeedsKey(this.host.collectOptionSeeds()),\n            this._revision()\n          ] as const,\n\n        enabled: ([store, enabled]) =>\n          Boolean(store) &&\n          enabled,\n\n        resolve: async ([store], context) =>\n          await this._compute(store, context),\n\n        commit: (result) => {\n          this._publish(result);\n        },\n\n        onDisabled: () => {\n          this._publish(undefined);\n        }\n      }\n    );\n  }\n\n  hostConnected(): void {\n    // BdResolveController owns compute scheduling.\n  }\n\n  hostDisconnected(): void {\n    // BdResolveController owns compute cancellation.\n  }\n\n  get pending(): boolean {\n    return this._resolver.pending;\n  }\n\n  get complete(): boolean {\n    return this._resolver.complete;\n  }\n\n  get failed(): boolean {\n    return this._resolver.failed;\n  }\n\n  get error(): unknown {\n    return this._resolver.error;\n  }\n\n  async run(): Promise<BdComputeResult | undefined> {\n    return await this._resolver.run();\n  }\n\n  private async _compute(\n    store: Store | undefined,\n    context: BdResolveContext\n  ): Promise<BdComputeResult | undefined> {\n    if (!store) {\n      return undefined;\n    }\n\n    const seeds =\n      this.host.collectOptionSeeds()\n        .map(optionToScenario);\n\n    if (seeds.length === 0) {\n      return undefined;\n    }\n\n    const scan =\n      mergeComputeScans(this.host.collectActionScans());\n\n    const scenarios =\n      await expandScenarios({\n        store,\n        seeds,\n        staticCommands: scan.staticCommands,\n        domains       : scan.domains,\n        signal        : context.signal,\n        maxScenarios  : this.options.maxScenarios\n      });\n\n    return reducePriceRange(scenarios);\n  }\n\n  private _publish(\n    result: BdComputeResult | undefined\n  ): void {\n    this.result = result;\n    this.options.onResult?.(result);\n\n    this.host.dispatchEvent(\n      new CustomEvent<BdComputeChangedDetail>(\n        BD_COMPUTE_CHANGED_EVENT,\n        {\n          bubbles : true,\n          composed: true,\n          detail  : { result }\n        }\n      )\n    );\n  }\n\n  private _revision(): number {\n    return (\n      this.options.revision?.() ??\n      this.host.actionTopologyRevision\n    );\n  }\n\n  private _enabled(): boolean {\n    return this.options.enabled?.() ?? true;\n  }\n}\n\nfunction optionToScenario(\n  option: ProductOption\n): BdOptionScenario {\n  return {\n    product: option.getProduct(),\n    option\n  };\n}\n\nfunction optionSeedsKey(\n  options: readonly ProductOption[]\n): string {\n  return options\n    .map((option) =>\n      scenarioKey(optionToScenario(option))\n    )\n    .sort()\n    .join(';');\n}\n"]}

package/dist/src/controllers/controller.resolve.d.ts

@@ -0,0 +1,78 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { type TaskStatus as LitTaskStatus } from '@lit/task';
+export type MaybePromise<T> = T | Promise<T>;
+export type BdResolveStatus = 'initial' | 'disabled' | 'pending' | 'complete' | 'error';
+export type BdResolveHookPhase = 'pending' | 'disabled' | 'complete' | 'error';
+export type BdResolveContext = Readonly<{
+    signal: AbortSignal;
+    runId: number;
+}>;
+export interface BdResolveHost extends ReactiveControllerHost {
+    trackLocalWork<T>(key: unknown, work: PromiseLike<T>): Promise<T>;
+}
+export type BdWorkKey = object | symbol;
+export interface BdResolveOptions<TArgs extends readonly unknown[], TResult> {
+    /**
+     * Optional debug name.
+     *
+     * This is not used as the tracking key.
+     */
+    name?: string;
+    /**
+     * Advanced escape hatch.
+     *
+     * Usually you should not set this.
+     * By default, the controller instance itself is used as the work key.
+     */
+    workKey?: BdWorkKey;
+    args: () => TArgs;
+    enabled?: (args: TArgs) => boolean;
+    argsEqual?: (oldArgs: TArgs, newArgs: TArgs) => boolean;
+    autoRun?: boolean | 'afterUpdate';
+    resolve: (args: TArgs, context: BdResolveContext) => MaybePromise<TResult>;
+    commit?: (result: TResult, args: TArgs, context: BdResolveContext) => MaybePromise<void>;
+    onPending?: (args: TArgs, context: BdResolveContext) => MaybePromise<void>;
+    onDisabled?: (args: TArgs, context: BdResolveContext) => MaybePromise<void>;
+    onComplete?: (result: TResult, args: TArgs, context: BdResolveContext) => MaybePromise<void>;
+    onError?: (error: unknown, args: TArgs, context: BdResolveContext) => MaybePromise<void>;
+    onHookError?: (error: unknown, phase: BdResolveHookPhase) => void;
+    abortOnDisconnect?: boolean;
+}
+export declare class BdResolveController<TArgs extends readonly unknown[], TResult> implements ReactiveController {
+    private readonly host;
+    private readonly options;
+    status: BdResolveStatus;
+    value?: TResult;
+    error?: unknown;
+    readonly name: string;
+    private readonly _workKey;
+    private readonly _task;
+    private _activeRunId;
+    constructor(host: BdResolveHost, options: BdResolveOptions<TArgs, TResult>);
+    hostDisconnected(): void;
+    get litTaskStatus(): LitTaskStatus;
+    get pending(): boolean;
+    get complete(): boolean;
+    get disabled(): boolean;
+    get failed(): boolean;
+    /**
+     * Manual execution.
+     *
+     * Useful if options.autoRun === false.
+     */
+    run(args?: TArgs): Promise<TResult | undefined>;
+    /**
+     * Abort the current task.
+     *
+     * This also invalidates the current controller runId so an old async result
+     * cannot later commit stale data.
+     */
+    abort(reason?: unknown): void;
+    private _startRunId;
+    private _isCurrentRun;
+    private _run;
+    private _runDisabled;
+    private _runEnabled;
+    private _callHook;
+}
+export declare function throwIfAborted(signal: AbortSignal): void;

package/dist/src/controllers/controller.resolve.js

@@ -0,0 +1,205 @@
+import { Task, initialState } from '@lit/task';
+export class BdResolveController {
+    constructor(host, options) {
+        this.host = host;
+        this.options = options;
+        this.status = 'initial';
+        this._activeRunId = 0;
+        this.name =
+            options.name ??
+                'bd-resolve';
+        /**
+         * By default, each controller instance is its own unique work key.
+         * This allows the controller to manage its own work without risk of conflict.
+         */
+        this._workKey =
+            options.workKey ??
+                this;
+        host.addController(this);
+        this._task = new Task(host, {
+            args: options.args,
+            autoRun: options.autoRun ?? true,
+            argsEqual: options.argsEqual,
+            task: (args, { signal }) => {
+                const runId = this._startRunId();
+                const context = {
+                    signal,
+                    runId
+                };
+                const work = this._run(args, context);
+                return this.host.trackLocalWork(this._workKey, work);
+            }
+        });
+    }
+    hostDisconnected() {
+        if (this.options.abortOnDisconnect ?? true) {
+            this.abort(createAbortError('BdResolveController host disconnected.'));
+        }
+    }
+    get litTaskStatus() {
+        return this._task.status;
+    }
+    get pending() {
+        return this.status === 'pending';
+    }
+    get complete() {
+        return this.status === 'complete';
+    }
+    get disabled() {
+        return this.status === 'disabled';
+    }
+    get failed() {
+        return this.status === 'error';
+    }
+    /**
+     * Manual execution.
+     *
+     * Useful if options.autoRun === false.
+     */
+    async run(args) {
+        await this._task.run(args);
+        if (this.status === 'error') {
+            throw this.error;
+        }
+        return this.value;
+    }
+    /**
+     * Abort the current task.
+     *
+     * This also invalidates the current controller runId so an old async result
+     * cannot later commit stale data.
+     */
+    abort(reason) {
+        this._activeRunId += 1;
+        this._task.abort(reason ??
+            createAbortError(`${this.name} aborted.`));
+        this.status = 'initial';
+        this.value = undefined;
+        this.error = undefined;
+        /**
+         * Replace this work slot with a completed promise.
+         *
+         * This prevents updateComplete from being blocked forever by an obsolete
+         * task that ignores AbortSignal.
+         */
+        this.host.trackLocalWork(this._workKey, Promise.resolve(undefined));
+        this.host.requestUpdate();
+    }
+    _startRunId() {
+        this._activeRunId += 1;
+        return this._activeRunId;
+    }
+    _isCurrentRun(context) {
+        return context.runId === this._activeRunId;
+    }
+    async _run(args, context) {
+        try {
+            const enabled = this.options.enabled?.(args) ?? true;
+            if (!enabled) {
+                return await this._runDisabled(args, context);
+            }
+            return await this._runEnabled(args, context);
+        }
+        catch (error) {
+            if (context.signal.aborted ||
+                !this._isCurrentRun(context)) {
+                return initialState;
+            }
+            this.status = 'error';
+            this.error = error;
+            this.value = undefined;
+            this.host.requestUpdate();
+            await this._callHook('error', () => this.options.onError?.(error, args, context));
+            /**
+             * Re-throw so @lit/task also enters ERROR state.
+             */
+            throw error;
+        }
+    }
+    async _runDisabled(args, context) {
+        if (!this._isCurrentRun(context)) {
+            return initialState;
+        }
+        this.status = 'disabled';
+        this.value = undefined;
+        this.error = undefined;
+        this.host.requestUpdate();
+        throwIfAborted(context.signal);
+        if (!this._isCurrentRun(context)) {
+            return initialState;
+        }
+        await this._callHook('disabled', () => this.options.onDisabled?.(args, context));
+        throwIfAborted(context.signal);
+        if (!this._isCurrentRun(context)) {
+            return initialState;
+        }
+        this.host.requestUpdate();
+        return initialState;
+    }
+    async _runEnabled(args, context) {
+        if (!this._isCurrentRun(context)) {
+            return initialState;
+        }
+        this.status = 'pending';
+        this.value = undefined;
+        this.error = undefined;
+        this.host.requestUpdate();
+        throwIfAborted(context.signal);
+        if (!this._isCurrentRun(context)) {
+            return initialState;
+        }
+        await this._callHook('pending', () => this.options.onPending?.(args, context));
+        throwIfAborted(context.signal);
+        if (!this._isCurrentRun(context)) {
+            return initialState;
+        }
+        const result = await this.options.resolve(args, context);
+        throwIfAborted(context.signal);
+        if (!this._isCurrentRun(context)) {
+            return initialState;
+        }
+        await this.options.commit?.(result, args, context);
+        throwIfAborted(context.signal);
+        if (!this._isCurrentRun(context)) {
+            return initialState;
+        }
+        this.status = 'complete';
+        this.value = result;
+        this.error = undefined;
+        this.host.requestUpdate();
+        await this._callHook('complete', () => this.options.onComplete?.(result, args, context));
+        throwIfAborted(context.signal);
+        if (!this._isCurrentRun(context)) {
+            return initialState;
+        }
+        return result;
+    }
+    async _callHook(phase, callback) {
+        try {
+            await callback();
+        }
+        catch (error) {
+            this.options.onHookError?.(error, phase);
+        }
+    }
+}
+export function throwIfAborted(signal) {
+    if (!signal.aborted) {
+        return;
+    }
+    if (typeof signal.throwIfAborted === 'function') {
+        signal.throwIfAborted();
+        return;
+    }
+    throw (signal.reason ??
+        createAbortError('The operation was aborted.'));
+}
+function createAbortError(message) {
+    if (typeof DOMException === 'function') {
+        return new DOMException(message, 'AbortError');
+    }
+    const error = new Error(message);
+    error.name = 'AbortError';
+    return error;
+}
+//# sourceMappingURL=controller.resolve.js.map

package/dist/src/controllers/controller.resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.resolve.js","sourceRoot":"","sources":["../../../src/controllers/controller.resolve.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ReactiveController,\n  ReactiveControllerHost\n} from 'lit';\n\nimport {\n  Task,\n  initialState,\n  type TaskStatus as LitTaskStatus\n} from '@lit/task';\n\nexport type MaybePromise<T> = T | Promise<T>;\n\nexport type BdResolveStatus =\n  | 'initial'\n  | 'disabled'\n  | 'pending'\n  | 'complete'\n  | 'error';\n\nexport type BdResolveHookPhase =\n  | 'pending'\n  | 'disabled'\n  | 'complete'\n  | 'error';\n\nexport type BdResolveContext = Readonly<{\n  signal: AbortSignal;\n  runId : number;\n}>;\n\nexport interface BdResolveHost extends ReactiveControllerHost {\n  trackLocalWork<T>(\n    key: unknown,\n    work: PromiseLike<T>,\n  ): Promise<T>;\n}\n\nexport type BdWorkKey = object | symbol;\n\nexport interface BdResolveOptions<\n  TArgs extends readonly unknown[],\n  TResult\n> {\n  /**\n   * Optional debug name.\n   *\n   * This is not used as the tracking key.\n   */\n  name?: string;\n\n  /**\n   * Advanced escape hatch.\n   *\n   * Usually you should not set this.\n   * By default, the controller instance itself is used as the work key.\n   */\n  workKey?: BdWorkKey;\n\n  args: () => TArgs;\n\n  enabled?: (args: TArgs) => boolean;\n\n  argsEqual?: (\n    oldArgs: TArgs,\n    newArgs: TArgs\n  ) => boolean;\n\n  autoRun?: boolean | 'afterUpdate';\n\n  resolve: (\n    args: TArgs,\n    context: BdResolveContext\n  ) => MaybePromise<TResult>;\n\n  commit?: (\n    result: TResult,\n    args: TArgs,\n    context: BdResolveContext\n  ) => MaybePromise<void>;\n\n  onPending?: (\n    args: TArgs,\n    context: BdResolveContext\n  ) => MaybePromise<void>;\n\n  onDisabled?: (\n    args: TArgs,\n    context: BdResolveContext\n  ) => MaybePromise<void>;\n\n  onComplete?: (\n    result: TResult,\n    args: TArgs,\n    context: BdResolveContext\n  ) => MaybePromise<void>;\n\n  onError?: (\n    error: unknown,\n    args: TArgs,\n    context: BdResolveContext\n  ) => MaybePromise<void>;\n\n  onHookError?: (\n    error: unknown,\n    phase: BdResolveHookPhase\n  ) => void;\n\n  abortOnDisconnect?: boolean;\n}\n\nexport class BdResolveController<\n  TArgs extends readonly unknown[],\n  TResult\n> implements ReactiveController {\n  status: BdResolveStatus = 'initial';\n  value?: TResult;\n  error?: unknown;\n\n  readonly name: string;\n\n  private readonly _workKey: BdWorkKey;\n  private readonly _task   : Task<TArgs, TResult>;\n  private _activeRunId = 0;\n\n  constructor(\n    private readonly host: BdResolveHost,\n    private readonly options: BdResolveOptions<TArgs, TResult>\n  ) {\n    this.name =\n      options.name ??\n      'bd-resolve';\n\n    /**\n     * By default, each controller instance is its own unique work key.\n     * This allows the controller to manage its own work without risk of conflict.\n     */\n    this._workKey =\n      options.workKey ??\n      this;\n\n    host.addController(this);\n\n    this._task = new Task<TArgs, TResult>(host, {\n      args: options.args,\n\n      autoRun:\n        options.autoRun ?? true,\n\n      argsEqual:\n        options.argsEqual,\n\n      task: (args, { signal }) => {\n        const runId = this._startRunId();\n\n        const context: BdResolveContext = {\n          signal,\n          runId\n        };\n\n        const work = this._run(\n          args,\n          context\n        );\n\n        return this.host.trackLocalWork(\n          this._workKey,\n          work\n        );\n      }\n    });\n  }\n\n  hostDisconnected(): void {\n    if (this.options.abortOnDisconnect ?? true) {\n      this.abort(\n        createAbortError(\n          'BdResolveController host disconnected.'\n        )\n      );\n    }\n  }\n\n  get litTaskStatus(): LitTaskStatus {\n    return this._task.status;\n  }\n\n  get pending(): boolean {\n    return this.status === 'pending';\n  }\n\n  get complete(): boolean {\n    return this.status === 'complete';\n  }\n\n  get disabled(): boolean {\n    return this.status === 'disabled';\n  }\n\n  get failed(): boolean {\n    return this.status === 'error';\n  }\n\n  /**\n   * Manual execution.\n   *\n   * Useful if options.autoRun === false.\n   */\n  async run(\n    args?: TArgs\n  ): Promise<TResult | undefined> {\n    await this._task.run(args);\n\n    if (this.status === 'error') {\n      throw this.error;\n    }\n\n    return this.value;\n  }\n\n  /**\n   * Abort the current task.\n   *\n   * This also invalidates the current controller runId so an old async result\n   * cannot later commit stale data.\n   */\n  abort(reason?: unknown): void {\n    this._activeRunId += 1;\n\n    this._task.abort(\n      reason ??\n        createAbortError(\n          `${this.name} aborted.`\n        )\n    );\n\n    this.status = 'initial';\n    this.value = undefined;\n    this.error = undefined;\n\n    /**\n     * Replace this work slot with a completed promise.\n     *\n     * This prevents updateComplete from being blocked forever by an obsolete\n     * task that ignores AbortSignal.\n     */\n    this.host.trackLocalWork(\n      this._workKey,\n      Promise.resolve(undefined)\n    );\n\n    this.host.requestUpdate();\n  }\n\n  private _startRunId(): number {\n    this._activeRunId += 1;\n    return this._activeRunId;\n  }\n\n  private _isCurrentRun(\n    context: BdResolveContext\n  ): boolean {\n    return context.runId === this._activeRunId;\n  }\n\n  private async _run(\n    args: TArgs,\n    context: BdResolveContext\n  ): Promise<TResult | typeof initialState> {\n    try {\n      const enabled =\n        this.options.enabled?.(args) ?? true;\n\n      if (!enabled) {\n        return await this._runDisabled(\n          args,\n          context\n        );\n      }\n\n      return await this._runEnabled(\n        args,\n        context\n      );\n    } catch (error) {\n      if (\n        context.signal.aborted ||\n        !this._isCurrentRun(context)\n      ) {\n        return initialState;\n      }\n\n      this.status = 'error';\n      this.error = error;\n      this.value = undefined;\n      this.host.requestUpdate();\n\n      await this._callHook(\n        'error',\n        () =>\n          this.options.onError?.(\n            error,\n            args,\n            context\n          )\n      );\n\n      /**\n       * Re-throw so @lit/task also enters ERROR state.\n       */\n      throw error;\n    }\n  }\n\n  private async _runDisabled(\n    args: TArgs,\n    context: BdResolveContext\n  ): Promise<typeof initialState> {\n    if (!this._isCurrentRun(context)) {\n      return initialState;\n    }\n\n    this.status = 'disabled';\n    this.value = undefined;\n    this.error = undefined;\n    this.host.requestUpdate();\n\n    throwIfAborted(context.signal);\n\n    if (!this._isCurrentRun(context)) {\n      return initialState;\n    }\n\n    await this._callHook(\n      'disabled',\n      () =>\n        this.options.onDisabled?.(\n          args,\n          context\n        )\n    );\n\n    throwIfAborted(context.signal);\n\n    if (!this._isCurrentRun(context)) {\n      return initialState;\n    }\n\n    this.host.requestUpdate();\n\n    return initialState;\n  }\n\n  private async _runEnabled(\n    args: TArgs,\n    context: BdResolveContext\n  ): Promise<TResult | typeof initialState> {\n    if (!this._isCurrentRun(context)) {\n      return initialState;\n    }\n\n    this.status = 'pending';\n    this.value = undefined;\n    this.error = undefined;\n    this.host.requestUpdate();\n\n    throwIfAborted(context.signal);\n\n    if (!this._isCurrentRun(context)) {\n      return initialState;\n    }\n\n    await this._callHook(\n      'pending',\n      () =>\n        this.options.onPending?.(\n          args,\n          context\n        )\n    );\n\n    throwIfAborted(context.signal);\n\n    if (!this._isCurrentRun(context)) {\n      return initialState;\n    }\n\n    const result =\n      await this.options.resolve(\n        args,\n        context\n      );\n\n    throwIfAborted(context.signal);\n\n    if (!this._isCurrentRun(context)) {\n      return initialState;\n    }\n\n    await this.options.commit?.(\n      result,\n      args,\n      context\n    );\n\n    throwIfAborted(context.signal);\n\n    if (!this._isCurrentRun(context)) {\n      return initialState;\n    }\n\n    this.status = 'complete';\n    this.value = result;\n    this.error = undefined;\n    this.host.requestUpdate();\n\n    await this._callHook(\n      'complete',\n      () =>\n        this.options.onComplete?.(\n          result,\n          args,\n          context\n        )\n    );\n\n    throwIfAborted(context.signal);\n\n    if (!this._isCurrentRun(context)) {\n      return initialState;\n    }\n\n    return result;\n  }\n\n  private async _callHook(\n    phase: BdResolveHookPhase,\n    callback: () => MaybePromise<void>\n  ): Promise<void> {\n    try {\n      await callback();\n    } catch (error) {\n      this.options.onHookError?.(\n        error,\n        phase\n      );\n    }\n  }\n}\n\nexport function throwIfAborted(\n  signal: AbortSignal\n): void {\n  if (!signal.aborted) {\n    return;\n  }\n\n  if (typeof signal.throwIfAborted === 'function') {\n    signal.throwIfAborted();\n    return;\n  }\n\n  throw (\n    signal.reason ??\n    createAbortError(\n      'The operation was aborted.'\n    )\n  );\n}\n\nfunction createAbortError(\n  message: string\n): Error | DOMException {\n  if (typeof DOMException === 'function') {\n    return new DOMException(\n      message,\n      'AbortError'\n    );\n  }\n\n  const error = new Error(message);\n  error.name = 'AbortError';\n\n  return error;\n}"]}

package/dist/src/core/action-topology.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Action topology events.
+ *
+ * These describe STRUCTURE, not intent and not resolved state:
+ *
+ *   bd-action-connect / bd-action-disconnect
+ *     A native action element appeared / disappeared. Announced by
+ *     BdActionElementAdapter. Caught by the nearest bd node, which owns that
+ *     element's membership (same boundary that would catch bd-action-request).
+ *
+ *   bd-action-topology-changed
+ *     The set of action elements under some bd node changed. Bubbles up so
+ *     ancestors can bump their action revision and recompute.
+ *
+ * Topology must never be stored in BdScope. It is local node structure, read on
+ * demand by compute. Putting it in scope would break scope immutability and
+ * atomicity.
+ */
+import type { BdComputeScan } from '../compute/compute.scan.js';
+export declare const BD_ACTION_CONNECT_EVENT: "bd-action-connect";
+export declare const BD_ACTION_DISCONNECT_EVENT: "bd-action-disconnect";
+export declare const BD_ACTION_UPDATE_EVENT: "bd-action-update";
+export declare const BD_ACTION_TOPOLOGY_CHANGED_EVENT: "bd-action-topology-changed";
+/**
+ * Sent when an action element connects.
+ *
+ * The nearest bd node calls claim() so the adapter can later announce the
+ * disconnect directly to that owner, even after the element is detached from
+ * the DOM (a bubbling event on a detached element would never reach it).
+ */
+export type BdActionConnectDetail = Readonly<{
+    element: HTMLElement;
+    scan: BdComputeScan;
+    claim: (owner: EventTarget) => void;
+}>;
+export type BdActionDisconnectDetail = Readonly<{
+    element: HTMLElement;
+}>;
+export type BdActionUpdateDetail = Readonly<{
+    element: HTMLElement;
+    scan: BdComputeScan;
+}>;
+declare global {
+    interface HTMLElementEventMap {
+        [BD_ACTION_CONNECT_EVENT]: CustomEvent<BdActionConnectDetail>;
+        [BD_ACTION_DISCONNECT_EVENT]: CustomEvent<BdActionDisconnectDetail>;
+        [BD_ACTION_UPDATE_EVENT]: CustomEvent<BdActionUpdateDetail>;
+        [BD_ACTION_TOPOLOGY_CHANGED_EVENT]: CustomEvent<undefined>;
+    }
+}
+export declare function dispatchBdActionConnect(element: HTMLElement, scan: BdComputeScan, claim: (owner: EventTarget) => void): void;
+/**
+ * Announce a disconnect.
+ *
+ * target should be the claimed owner when available, because the element may
+ * already be detached from the DOM by the time the registry observes its
+ * removal. Dispatching on the retained owner guarantees the owning node hears
+ * it regardless of DOM connectivity.
+ */
+export declare function dispatchBdActionDisconnect(target: EventTarget, element: HTMLElement): void;
+export declare function dispatchBdActionUpdate(target: EventTarget, element: HTMLElement, scan: BdComputeScan): void;
+export declare function dispatchBdActionTopologyChanged(target: EventTarget): void;

package/dist/src/core/action-topology.js

@@ -0,0 +1,67 @@
+/**
+ * Action topology events.
+ *
+ * These describe STRUCTURE, not intent and not resolved state:
+ *
+ *   bd-action-connect / bd-action-disconnect
+ *     A native action element appeared / disappeared. Announced by
+ *     BdActionElementAdapter. Caught by the nearest bd node, which owns that
+ *     element's membership (same boundary that would catch bd-action-request).
+ *
+ *   bd-action-topology-changed
+ *     The set of action elements under some bd node changed. Bubbles up so
+ *     ancestors can bump their action revision and recompute.
+ *
+ * Topology must never be stored in BdScope. It is local node structure, read on
+ * demand by compute. Putting it in scope would break scope immutability and
+ * atomicity.
+ */
+export const BD_ACTION_CONNECT_EVENT = 'bd-action-connect';
+export const BD_ACTION_DISCONNECT_EVENT = 'bd-action-disconnect';
+export const BD_ACTION_UPDATE_EVENT = 'bd-action-update';
+export const BD_ACTION_TOPOLOGY_CHANGED_EVENT = 'bd-action-topology-changed';
+export function dispatchBdActionConnect(element, scan, claim) {
+    element.dispatchEvent(new CustomEvent(BD_ACTION_CONNECT_EVENT, {
+        bubbles: true,
+        composed: true,
+        detail: {
+            element,
+            scan,
+            claim
+        }
+    }));
+}
+/**
+ * Announce a disconnect.
+ *
+ * target should be the claimed owner when available, because the element may
+ * already be detached from the DOM by the time the registry observes its
+ * removal. Dispatching on the retained owner guarantees the owning node hears
+ * it regardless of DOM connectivity.
+ */
+export function dispatchBdActionDisconnect(target, element) {
+    target.dispatchEvent(new CustomEvent(BD_ACTION_DISCONNECT_EVENT, {
+        bubbles: true,
+        composed: true,
+        detail: {
+            element
+        }
+    }));
+}
+export function dispatchBdActionUpdate(target, element, scan) {
+    target.dispatchEvent(new CustomEvent(BD_ACTION_UPDATE_EVENT, {
+        bubbles: true,
+        composed: true,
+        detail: {
+            element,
+            scan
+        }
+    }));
+}
+export function dispatchBdActionTopologyChanged(target) {
+    target.dispatchEvent(new CustomEvent(BD_ACTION_TOPOLOGY_CHANGED_EVENT, {
+        bubbles: true,
+        composed: true
+    }));
+}
+//# sourceMappingURL=action-topology.js.map

package/dist/src/core/action-topology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-topology.js","sourceRoot":"","sources":["../../../src/core/action-topology.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,CAAC,MAAM,uBAAuB,GAClC,mBAA4B,CAAC;AAE/B,MAAM,CAAC,MAAM,0BAA0B,GACrC,sBAA+B,CAAC;AAElC,MAAM,CAAC,MAAM,sBAAsB,GACjC,kBAA2B,CAAC;AAE9B,MAAM,CAAC,MAAM,gCAAgC,GAC3C,4BAAqC,CAAC;AAiCxC,MAAM,UAAU,uBAAuB,CACrC,OAAoB,EACpB,IAAmB,EACnB,KAAmC;IAEnC,OAAO,CAAC,aAAa,CACnB,IAAI,WAAW,CACb,uBAAuB,EACvB;QACE,OAAO,EAAG,IAAI;QACd,QAAQ,EAAE,IAAI;QACd,MAAM,EAAI;YACR,OAAO;YACP,IAAI;YACJ,KAAK;SACN;KACF,CACF,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAmB,EACnB,OAAoB;IAEpB,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CACb,0BAA0B,EAC1B;QACE,OAAO,EAAG,IAAI;QACd,QAAQ,EAAE,IAAI;QACd,MAAM,EAAI;YACR,OAAO;SACR;KACF,CACF,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,MAAmB,EACnB,OAAoB,EACpB,IAAmB;IAEnB,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CACb,sBAAsB,EACtB;QACE,OAAO,EAAG,IAAI;QACd,QAAQ,EAAE,IAAI;QACd,MAAM,EAAI;YACR,OAAO;YACP,IAAI;SACL;KACF,CACF,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B,CAC7C,MAAmB;IAEnB,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CACb,gCAAgC,EAChC;QACE,OAAO,EAAG,IAAI;QACd,QAAQ,EAAE,IAAI;KACf,CACF,CACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Action topology events.\n *\n * These describe STRUCTURE, not intent and not resolved state:\n *\n *   bd-action-connect / bd-action-disconnect\n *     A native action element appeared / disappeared. Announced by\n *     BdActionElementAdapter. Caught by the nearest bd node, which owns that\n *     element's membership (same boundary that would catch bd-action-request).\n *\n *   bd-action-topology-changed\n *     The set of action elements under some bd node changed. Bubbles up so\n *     ancestors can bump their action revision and recompute.\n *\n * Topology must never be stored in BdScope. It is local node structure, read on\n * demand by compute. Putting it in scope would break scope immutability and\n * atomicity.\n */\n\nimport type { BdComputeScan } from '@/compute/compute.scan.js';\n\nexport const BD_ACTION_CONNECT_EVENT =\n  'bd-action-connect' as const;\n\nexport const BD_ACTION_DISCONNECT_EVENT =\n  'bd-action-disconnect' as const;\n\nexport const BD_ACTION_UPDATE_EVENT =\n  'bd-action-update' as const;\n\nexport const BD_ACTION_TOPOLOGY_CHANGED_EVENT =\n  'bd-action-topology-changed' as const;\n\n/**\n * Sent when an action element connects.\n *\n * The nearest bd node calls claim() so the adapter can later announce the\n * disconnect directly to that owner, even after the element is detached from\n * the DOM (a bubbling event on a detached element would never reach it).\n */\nexport type BdActionConnectDetail = Readonly<{\n  element: HTMLElement;\n  scan   : BdComputeScan;\n  claim  : (owner: EventTarget) => void;\n}>;\n\nexport type BdActionDisconnectDetail = Readonly<{\n  element: HTMLElement;\n}>;\n\nexport type BdActionUpdateDetail = Readonly<{\n  element: HTMLElement;\n  scan   : BdComputeScan;\n}>;\n\ndeclare global {\n  interface HTMLElementEventMap {\n    [BD_ACTION_CONNECT_EVENT]         : CustomEvent<BdActionConnectDetail>;\n    [BD_ACTION_DISCONNECT_EVENT]      : CustomEvent<BdActionDisconnectDetail>;\n    [BD_ACTION_UPDATE_EVENT]          : CustomEvent<BdActionUpdateDetail>;\n    [BD_ACTION_TOPOLOGY_CHANGED_EVENT]: CustomEvent<undefined>;\n  }\n}\n\nexport function dispatchBdActionConnect(\n  element: HTMLElement,\n  scan: BdComputeScan,\n  claim: (owner: EventTarget) => void\n): void {\n  element.dispatchEvent(\n    new CustomEvent<BdActionConnectDetail>(\n      BD_ACTION_CONNECT_EVENT,\n      {\n        bubbles : true,\n        composed: true,\n        detail  : {\n          element,\n          scan,\n          claim\n        }\n      }\n    )\n  );\n}\n\n/**\n * Announce a disconnect.\n *\n * target should be the claimed owner when available, because the element may\n * already be detached from the DOM by the time the registry observes its\n * removal. Dispatching on the retained owner guarantees the owning node hears\n * it regardless of DOM connectivity.\n */\nexport function dispatchBdActionDisconnect(\n  target: EventTarget,\n  element: HTMLElement\n): void {\n  target.dispatchEvent(\n    new CustomEvent<BdActionDisconnectDetail>(\n      BD_ACTION_DISCONNECT_EVENT,\n      {\n        bubbles : true,\n        composed: true,\n        detail  : {\n          element\n        }\n      }\n    )\n  );\n}\n\nexport function dispatchBdActionUpdate(\n  target: EventTarget,\n  element: HTMLElement,\n  scan: BdComputeScan\n): void {\n  target.dispatchEvent(\n    new CustomEvent<BdActionUpdateDetail>(\n      BD_ACTION_UPDATE_EVENT,\n      {\n        bubbles : true,\n        composed: true,\n        detail  : {\n          element,\n          scan\n        }\n      }\n    )\n  );\n}\n\nexport function dispatchBdActionTopologyChanged(\n  target: EventTarget\n): void {\n  target.dispatchEvent(\n    new CustomEvent<undefined>(\n      BD_ACTION_TOPOLOGY_CHANGED_EVENT,\n      {\n        bubbles : true,\n        composed: true\n      }\n    )\n  );\n}\n"]}

package/dist/src/core/actions.d.ts

@@ -0,0 +1,64 @@
+export type UpdateByDelta = Readonly<{
+    type: 'devices' | 'subscription';
+    delta: number | 'next' | 'prev';
+    min?: number;
+    max?: number;
+    useAsValue?: boolean;
+    /**
+     * Optional identifier for the action source element
+     * (`data-store-event-id`). Consumers filter against this id via the
+     * `ignore-events` attribute on `bd-*` provider elements.
+     */
+    eventId?: string;
+}>;
+export type Action = Readonly<{
+    id?: string;
+    campaign?: string;
+    bundle?: boolean;
+    devices?: number;
+    subscription?: number;
+    /**
+     * Optional identifier for the action source element
+     * (`data-store-event-id`). Consumers filter against this id via the
+     * `ignore-events` attribute on `bd-*` provider elements.
+     */
+    eventId?: string;
+}>;
+export type BdActionCommand = Readonly<{
+    kind: 'update-by-delta';
+    update: UpdateByDelta;
+}> | Readonly<{
+    kind: 'set-action';
+    action: Action;
+}>;
+export type BdTransition = Readonly<{
+    seq: number;
+    command: BdActionCommand;
+    originNode?: EventTarget | null;
+    createdAt: number;
+}>;
+export declare const BD_ACTION_REQUEST_EVENT: "bd-action-request";
+export type BdActionRequestDetail = Readonly<{
+    command: BdActionCommand;
+}>;
+declare global {
+    interface HTMLElementEventMap {
+        [BD_ACTION_REQUEST_EVENT]: CustomEvent<BdActionRequestDetail>;
+    }
+}
+export declare function createBdTransition(detail: BdActionRequestDetail, originNode?: EventTarget | null): BdTransition;
+export declare function dispatchBdActionRequest(eventTarget: EventTarget, detail: BdActionRequestDetail): boolean;
+export declare function isBdActionRequestEvent(event: Event): event is CustomEvent<BdActionRequestDetail>;
+/**
+ * Pulls the optional `eventId` off the command carried by a transition.
+ *
+ * `eventId` is set on the action element via `data-store-event-id="…"` and
+ * is the matching key for the `ignore-events="…"` attribute on `bd-*`
+ * provider elements. Returns `undefined` for commands that did not declare
+ * one.
+ */
+export declare function getCommandEventId(command: BdActionCommand): string | undefined;
+/**
+ * Convenience wrapper around {@link getCommandEventId} for transitions.
+ */
+export declare function getTransitionEventId(transition: BdTransition): string | undefined;