@honua/react 0.1.4-beta.0 → 0.1.7-beta.0

package/interactions/declarative.d.ts

@@ -0,0 +1,198 @@
+/**
+ * `@honua/sdk-js/interactions/declarative` — compiles a standard
+ * `interactions[]` block (geospatial-mcp ADR-0030) onto this SDK's existing
+ * imperative binding primitives.
+ *
+ * The standard constrains the *document*, not the dispatcher: "client
+ * runtimes implement dispatch by compiling bindings onto whatever imperative
+ * primitives they already have". That is exactly what this module does — it
+ * owns no event plumbing of its own, only a compile table from the closed
+ * (`on.event`, `do.verb`) vocabulary onto `createSelectionHandler`,
+ * `createHoverHandler`, `bindTableSelectionToExploration`,
+ * `bindFilterControlsToExploration`, and `subscribeExplorationSelector`.
+ *
+ * Three properties are load-bearing and asserted by the suite:
+ *
+ * 1. **Validate before binding.** `compileHonuaInteractions` runs the whole
+ *    block through {@link validateHonuaInteractions} plus reference
+ *    resolution against the components it was handed. A block with issues
+ *    binds *nothing* — the standard rejects over-cap and malformed documents
+ *    rather than truncating them.
+ * 2. **Actions never emit events.** A verb-driven state change must not
+ *    re-enter the dispatcher. Two mechanisms enforce it: every compiled
+ *    handler is skipped while an action is in flight (`#dispatching`), and
+ *    exploration-backed subscriptions run with the view controller's default
+ *    `includeSelf: false`, so a change this compiler originated is never
+ *    delivered back to this compiler. There is no cycle detection because
+ *    there can be no cycle.
+ * 3. **Unsupported pairs are named, never dropped.** When a binding's
+ *    (`on.event`, `do.verb`) pair — or the component behind a ref — has no
+ *    primitive to compile onto, it lands in
+ *    {@link HonuaCompiledInteractions.unsupported} with the pair spelled out,
+ *    so a host can surface a real "this runtime cannot honor that binding"
+ *    message instead of silently rendering an inert app.
+ *
+ * @experimental The compiler surface tracks geospatial-mcp ADR-0030 while
+ * that ADR is Proposed; the component-adapter shapes may gain fields.
+ *
+ * @module
+ */
+import type { SourceId } from "../contract/types.js";
+import type { ExplorationViewController, FilterClause } from "../exploration/types.js";
+import type { InteractiveMap } from "./feature-state.js";
+import { type HonuaInteractionEvent, type HonuaInteractionIssue, type HonuaInteractionVerb } from "./declarative-contract.js";
+export * from "./declarative-contract.js";
+/**
+ * A layer addressed as `layer:{id}`. `map` is what the
+ * `featureSelect`/`featureHover` primitives bind to; the optional methods are
+ * the layer-scoped action targets.
+ */
+export interface HonuaInteractionLayerComponent {
+    /** MapLibre-style interactive map this layer renders on — the event source for `featureSelect`/`featureHover`. */
+    readonly map?: InteractiveMap;
+    /** Source id feature-state is written to. Defaults to the ref's id. */
+    readonly sourceId?: SourceId;
+    /** Rendered layer id clicks/hovers are observed on. Defaults to the ref's id. */
+    readonly layerId?: string;
+    /** Source layer, for vector-tile sources. */
+    readonly sourceLayer?: string;
+    /** Select multiple features rather than replacing on each click. @default false */
+    readonly multiSelect?: boolean;
+    /** `setVisibility` target. */
+    setVisibility?(visible: boolean): void;
+    /** `setFilter` target. When absent, `setFilter` falls back to the shared exploration filter keyed by this ref's id. */
+    setFilter?(clause: FilterClause | undefined): void;
+}
+export interface HonuaInteractionViewport {
+    readonly bbox?: readonly [number, number, number, number];
+    readonly center?: readonly [number, number];
+    readonly zoom?: number;
+    readonly pitch?: number;
+    readonly bearing?: number;
+}
+/** The `map` component. */
+export interface HonuaInteractionMapComponent {
+    /**
+     * `setViewport` target. When absent, `setViewport` falls back to the
+     * exploration view's `setExtent` for `bbox`-shaped arguments.
+     */
+    setViewport?(viewport: HonuaInteractionViewport): void;
+}
+/** A widget addressed as `widget:{id}`. */
+export interface HonuaInteractionWidgetComponent {
+    /** `runWidgetQuery` target. There is no exploration-level fallback for this verb. */
+    runQuery?(request: Readonly<Record<string, unknown>>): void;
+    /** `setFilter` target. When absent, falls back to the shared exploration filter keyed by this ref's id. */
+    setFilter?(clause: FilterClause | undefined): void;
+    /** `setVisibility` target. */
+    setVisibility?(visible: boolean): void;
+}
+/**
+ * A control addressed as `control:{id}`. A control's `change` event is read
+ * off the shared exploration filter slice keyed by the control's id — that is
+ * the same seam `bindFilterControlsToExploration` writes through, so a
+ * filter bar wired with that primitive needs no extra adapter here.
+ */
+export interface HonuaInteractionControlComponent {
+    /** `setVisibility` target. */
+    setVisibility?(visible: boolean): void;
+    /** `setFilter` target. When absent, falls back to the shared exploration filter keyed by this ref's id. */
+    setFilter?(clause: FilterClause | undefined): void;
+}
+/**
+ * The components an `interactions[]` block's refs resolve against. A ref that
+ * resolves to no component is a validation failure (`unresolved-ref`), matching
+ * the standard's "an implementation MUST reject a binding whose `ref` does not
+ * resolve within the document".
+ *
+ * `control:` and `widget:` refs may be declared with an empty object when the
+ * component needs no adapter — their events and their `setFilter` action both
+ * run through the shared exploration view.
+ */
+export interface HonuaInteractionComponents {
+    readonly map?: HonuaInteractionMapComponent;
+    readonly layers?: Readonly<Record<string, HonuaInteractionLayerComponent>>;
+    readonly widgets?: Readonly<Record<string, HonuaInteractionWidgetComponent>>;
+    readonly controls?: Readonly<Record<string, HonuaInteractionControlComponent>>;
+}
+/** One binding this runtime cannot honor, with the pair named. */
+export interface HonuaUnsupportedInteraction {
+    readonly interactionId: string;
+    readonly on: {
+        readonly ref: string;
+        readonly event: HonuaInteractionEvent;
+    };
+    readonly do: {
+        readonly ref: string;
+        readonly verb: HonuaInteractionVerb;
+    };
+    /** `"{event} -> {verb}"`, the pair as the standard spells it. */
+    readonly pair: string;
+    readonly reason: string;
+}
+/** One binding that compiled onto a primitive. */
+export interface HonuaCompiledInteractionBinding {
+    readonly interactionId: string;
+    readonly on: {
+        readonly ref: string;
+        readonly event: HonuaInteractionEvent;
+    };
+    readonly do: {
+        readonly ref: string;
+        readonly verb: HonuaInteractionVerb;
+    };
+    readonly pair: string;
+    /** Disposes just this binding. Idempotent. */
+    dispose(): void;
+}
+export interface HonuaCompiledInteractions {
+    /** True when the block validated and every non-disabled binding compiled. */
+    readonly ok: boolean;
+    /** Validation failures. When non-empty, nothing was bound. */
+    readonly issues: ReadonlyArray<HonuaInteractionIssue>;
+    readonly bindings: ReadonlyArray<HonuaCompiledInteractionBinding>;
+    readonly unsupported: ReadonlyArray<HonuaUnsupportedInteraction>;
+    /** Interaction ids skipped because `disabled: true`. */
+    readonly disabled: ReadonlyArray<string>;
+    /** Disposes every compiled binding. Idempotent. */
+    dispose(): void;
+}
+export interface CompileHonuaInteractionsOptions {
+    /**
+     * The exploration view this compiler owns — every action verb writes
+     * through it, and every exploration-backed event source subscribes on it.
+     *
+     * **Pass a view bound for the compiler alone** (`ctx.connectView({ id:
+     * "interactions", role: "custom" })`), not a view a widget also dispatches
+     * through. That is what makes "actions never emit events" structural rather
+     * than best-effort: an `ExplorationViewController` delivers a bound view its
+     * own notifications only under `includeSelf`, so a state change this
+     * compiler originated is never routed back into this compiler, while a real
+     * user gesture published by any *other* view is.
+     */
+    readonly view: ExplorationViewController;
+    readonly components?: HonuaInteractionComponents;
+    /** Per-(`on.ref`, `on.event`) fan-out cap. @default 8 */
+    readonly fanOutCap?: number;
+    /**
+     * Observes each dispatched action. Called after the verb ran; never called
+     * for a suppressed (action-originated) event, which is the whole point of
+     * "actions never emit events".
+     */
+    readonly onDispatch?: (dispatch: HonuaInteractionDispatch) => void;
+}
+export interface HonuaInteractionDispatch {
+    readonly interactionId: string;
+    readonly event: HonuaInteractionEvent;
+    readonly verb: HonuaInteractionVerb;
+    readonly ref: string;
+    /** Arguments after `$event.*` substitution. */
+    readonly args: Readonly<Record<string, unknown>>;
+}
+/**
+ * Compiles an `interactions[]` block onto live components. Returns disposers;
+ * never throws for a bad document — a malformed or over-cap block comes back
+ * as `{ ok: false, issues }` with nothing bound.
+ */
+export declare function compileHonuaInteractions(interactions: unknown, options: CompileHonuaInteractionsOptions): HonuaCompiledInteractions;
+//# sourceMappingURL=declarative.d.ts.map

package/interactions/declarative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declarative.d.ts","sourceRoot":"","sources":["../../../src/interactions/declarative.ts"],"names":[],"mappings":"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"}

package/interactions/declarative.js

@@ -0,0 +1,470 @@
+/**
+ * `@honua/sdk-js/interactions/declarative` — compiles a standard
+ * `interactions[]` block (geospatial-mcp ADR-0030) onto this SDK's existing
+ * imperative binding primitives.
+ *
+ * The standard constrains the *document*, not the dispatcher: "client
+ * runtimes implement dispatch by compiling bindings onto whatever imperative
+ * primitives they already have". That is exactly what this module does — it
+ * owns no event plumbing of its own, only a compile table from the closed
+ * (`on.event`, `do.verb`) vocabulary onto `createSelectionHandler`,
+ * `createHoverHandler`, `bindTableSelectionToExploration`,
+ * `bindFilterControlsToExploration`, and `subscribeExplorationSelector`.
+ *
+ * Three properties are load-bearing and asserted by the suite:
+ *
+ * 1. **Validate before binding.** `compileHonuaInteractions` runs the whole
+ *    block through {@link validateHonuaInteractions} plus reference
+ *    resolution against the components it was handed. A block with issues
+ *    binds *nothing* — the standard rejects over-cap and malformed documents
+ *    rather than truncating them.
+ * 2. **Actions never emit events.** A verb-driven state change must not
+ *    re-enter the dispatcher. Two mechanisms enforce it: every compiled
+ *    handler is skipped while an action is in flight (`#dispatching`), and
+ *    exploration-backed subscriptions run with the view controller's default
+ *    `includeSelf: false`, so a change this compiler originated is never
+ *    delivered back to this compiler. There is no cycle detection because
+ *    there can be no cycle.
+ * 3. **Unsupported pairs are named, never dropped.** When a binding's
+ *    (`on.event`, `do.verb`) pair — or the component behind a ref — has no
+ *    primitive to compile onto, it lands in
+ *    {@link HonuaCompiledInteractions.unsupported} with the pair spelled out,
+ *    so a host can surface a real "this runtime cannot honor that binding"
+ *    message instead of silently rendering an inert app.
+ *
+ * @experimental The compiler surface tracks geospatial-mcp ADR-0030 while
+ * that ADR is Proposed; the component-adapter shapes may gain fields.
+ *
+ * @module
+ */
+import { sourceFeatureSelectionTarget } from "../exploration/selection.js";
+import { subscribeExplorationSelector } from "../exploration/selectors.js";
+import { bindFilterControlsToExploration, bindTableSelectionToExploration } from "./exploration-bindings.js";
+import { createHoverHandler, createSelectionHandler } from "./feature-state.js";
+import { parseHonuaInteractionRef, resolveHonuaInteractionArgs, validateHonuaInteractions, } from "./declarative-contract.js";
+export * from "./declarative-contract.js";
+// ── Compiler ──────────────────────────────────────────────────
+const EMPTY_RESULT_BASE = { bindings: [], disabled: [] };
+/**
+ * Compiles an `interactions[]` block onto live components. Returns disposers;
+ * never throws for a bad document — a malformed or over-cap block comes back
+ * as `{ ok: false, issues }` with nothing bound.
+ */
+export function compileHonuaInteractions(interactions, options) {
+    const validation = validateHonuaInteractions(interactions, {
+        ...(options.fanOutCap !== undefined ? { fanOutCap: options.fanOutCap } : {}),
+    });
+    const components = options.components ?? {};
+    const declared = Array.isArray(interactions) ? interactions : [];
+    const refIssues = validation.ok ? resolveReferenceIssues(declared, components) : [];
+    const issues = [...validation.issues, ...refIssues];
+    if (issues.length > 0) {
+        return {
+            ok: false,
+            issues,
+            ...EMPTY_RESULT_BASE,
+            unsupported: [],
+            dispose: () => undefined,
+        };
+    }
+    const compiler = new InteractionCompiler(options, components);
+    for (const interaction of declared)
+        compiler.compile(interaction);
+    return compiler.result();
+}
+function resolveReferenceIssues(interactions, components) {
+    const issues = [];
+    interactions.forEach((interaction, index) => {
+        for (const side of ["on", "do"]) {
+            const ref = interaction[side].ref;
+            if (resolveComponent(ref, components) !== undefined)
+                continue;
+            issues.push({
+                code: "invalid-ref",
+                interactionId: interaction.id,
+                path: `interactions[${index}].${side}.ref`,
+                message: `\`${ref}\` does not resolve to a declared component.`,
+            });
+        }
+    });
+    return issues;
+}
+function resolveComponent(ref, components) {
+    const parsed = parseHonuaInteractionRef(ref);
+    if (!parsed)
+        return undefined;
+    if (parsed.kind === "map") {
+        return components.map ? { kind: "map", id: "map", component: components.map } : undefined;
+    }
+    const id = parsed.id;
+    const table = {
+        layer: components.layers,
+        widget: components.widgets,
+        control: components.controls,
+    };
+    const component = table[parsed.kind]?.[id];
+    if (!component)
+        return undefined;
+    return { kind: parsed.kind, id, component };
+}
+class InteractionCompiler {
+    #view;
+    #components;
+    #onDispatch;
+    #bindings = [];
+    #unsupported = [];
+    #disabled = [];
+    /** Re-entrancy guard: an event delivered while an action runs is dropped (actions never emit events). */
+    #dispatching = false;
+    #disposed = false;
+    constructor(options, components) {
+        this.#view = options.view;
+        this.#components = components;
+        this.#onDispatch = options.onDispatch;
+    }
+    compile(interaction) {
+        if (interaction.disabled === true) {
+            this.#disabled.push(interaction.id);
+            return;
+        }
+        const source = resolveComponent(interaction.on.ref, this.#components);
+        const target = resolveComponent(interaction.do.ref, this.#components);
+        const action = this.#compileAction(interaction, target);
+        if (typeof action === "string") {
+            this.#reject(interaction, action);
+            return;
+        }
+        const dispose = this.#compileEvent(interaction, source, action);
+        if (typeof dispose === "string") {
+            this.#reject(interaction, dispose);
+            return;
+        }
+        let released = false;
+        this.#bindings.push({
+            interactionId: interaction.id,
+            on: { ref: interaction.on.ref, event: interaction.on.event },
+            do: { ref: interaction.do.ref, verb: interaction.do.verb },
+            pair: pairLabel(interaction),
+            dispose: () => {
+                if (released)
+                    return;
+                released = true;
+                dispose();
+            },
+        });
+    }
+    result() {
+        const bindings = [...this.#bindings];
+        return {
+            ok: this.#unsupported.length === 0,
+            issues: [],
+            bindings,
+            unsupported: [...this.#unsupported],
+            disabled: [...this.#disabled],
+            dispose: () => {
+                if (this.#disposed)
+                    return;
+                this.#disposed = true;
+                for (const binding of bindings)
+                    binding.dispose();
+            },
+        };
+    }
+    #reject(interaction, reason) {
+        this.#unsupported.push({
+            interactionId: interaction.id,
+            on: { ref: interaction.on.ref, event: interaction.on.event },
+            do: { ref: interaction.do.ref, verb: interaction.do.verb },
+            pair: pairLabel(interaction),
+            reason,
+        });
+    }
+    // ── Event side ──────────────────────────────────────────────
+    /** Returns a disposer, or a string reason the pair is unsupported. */
+    #compileEvent(interaction, source, action) {
+        const emit = (payload) => {
+            if (this.#disposed || this.#dispatching)
+                return;
+            this.#dispatching = true;
+            try {
+                action(payload);
+            }
+            finally {
+                this.#dispatching = false;
+            }
+        };
+        switch (interaction.on.event) {
+            case "featureSelect": {
+                if (source.kind !== "layer")
+                    return `\`featureSelect\` is a layer event; \`${interaction.on.ref}\` is not a layer.`;
+                const map = source.component.map;
+                if (!map)
+                    return `Layer "${source.id}" declares no \`map\`, so \`featureSelect\` has no primitive to bind to.`;
+                const sourceId = source.component.sourceId ?? source.id;
+                const handle = createSelectionHandler(map, {
+                    source: sourceId,
+                    layer: source.component.layerId ?? source.id,
+                    ...(source.component.sourceLayer ? { sourceLayer: source.component.sourceLayer } : {}),
+                    ...(source.component.multiSelect !== undefined ? { multiSelect: source.component.multiSelect } : {}),
+                    onSelectionTargetsChange: (targets) => emit(featureSelectPayload(sourceId, targets)),
+                });
+                return () => handle.remove();
+            }
+            case "featureHover": {
+                if (source.kind !== "layer")
+                    return `\`featureHover\` is a layer event; \`${interaction.on.ref}\` is not a layer.`;
+                const map = source.component.map;
+                if (!map)
+                    return `Layer "${source.id}" declares no \`map\`, so \`featureHover\` has no primitive to bind to.`;
+                const sourceId = source.component.sourceId ?? source.id;
+                const handle = createHoverHandler(map, {
+                    source: sourceId,
+                    layer: source.component.layerId ?? source.id,
+                    ...(source.component.sourceLayer ? { sourceLayer: source.component.sourceLayer } : {}),
+                    onHoverTargetChange: (hovered) => emit(featureHoverPayload(sourceId, hovered)),
+                });
+                return () => handle.remove();
+            }
+            case "selection": {
+                if (source.kind !== "widget")
+                    return `\`selection\` is a widget event; \`${interaction.on.ref}\` is not a widget.`;
+                // Compiled onto the table/grid selection primitive: a widget publishes
+                // and observes selection through the shared exploration slice.
+                const unsubscribe = bindTableSelectionToExploration(this.#view).subscribe((selection) => emit(selectionPayload(selection)));
+                return unsubscribe;
+            }
+            case "change": {
+                if (source.kind !== "control")
+                    return `\`change\` is a control event; \`${interaction.on.ref}\` is not a control.`;
+                // Compiled onto the filter-control primitive, keyed by the control's
+                // own id — the same key `bindFilterControlsToExploration().setFilter`
+                // writes, so a filter bar built on that primitive needs no adapter.
+                const controlId = source.id;
+                let previous = this.#view.state.filters[controlId];
+                const unsubscribe = bindFilterControlsToExploration(this.#view).subscribe((filters) => {
+                    const clause = filters[controlId];
+                    if (clause === previous)
+                        return;
+                    previous = clause;
+                    emit(changePayload(controlId, clause, filters));
+                });
+                return unsubscribe;
+            }
+            case "viewportChange": {
+                if (source.kind !== "map")
+                    return "`viewportChange` is a map event; only `map` publishes it.";
+                // Compiled onto the shared extent slice — the slice
+                // `bindMapExtentToExploration` publishes into.
+                const unsubscribe = subscribeExplorationSelector(this.#view, "extent", (state) => state.extent, (extent) => emit(viewportPayload(extent)), { fireImmediately: false });
+                return unsubscribe;
+            }
+        }
+    }
+    // ── Action side ─────────────────────────────────────────────
+    /** Returns an action, or a string reason the pair is unsupported. */
+    #compileAction(interaction, target) {
+        const verb = interaction.do.verb;
+        const declaredArgs = interaction.do.args;
+        const observe = (args) => {
+            this.#onDispatch?.({
+                interactionId: interaction.id,
+                event: interaction.on.event,
+                verb,
+                ref: interaction.do.ref,
+                args,
+            });
+        };
+        switch (verb) {
+            case "setFilter": {
+                const setFilter = componentSetFilter(target);
+                const filterId = target.kind === "map" ? "map" : target.id;
+                return (payload) => {
+                    const args = resolveHonuaInteractionArgs(declaredArgs, payload);
+                    const clause = filterClauseFromArgs(args);
+                    if (setFilter)
+                        setFilter(clause);
+                    else if (clause)
+                        this.#view.setFilter(filterId, clause);
+                    else
+                        this.#view.clearFilter(filterId);
+                    observe(args);
+                };
+            }
+            case "setViewport": {
+                if (target.kind !== "map")
+                    return "`setViewport` targets `map`; no other component accepts it.";
+                const component = target.component;
+                return (payload) => {
+                    const args = resolveHonuaInteractionArgs(declaredArgs, payload);
+                    const viewport = viewportFromArgs(args);
+                    if (component.setViewport)
+                        component.setViewport(viewport);
+                    else
+                        this.#view.setExtent(extentFromBbox(viewport.bbox));
+                    observe(args);
+                };
+            }
+            case "selectFeature": {
+                if (target.kind === "control")
+                    return "`selectFeature` has no control-side primitive.";
+                const fallbackSourceId = target.kind === "layer" ? (target.component.sourceId ?? target.id) : target.id;
+                const selection = bindTableSelectionToExploration(this.#view);
+                return (payload) => {
+                    const args = resolveHonuaInteractionArgs(declaredArgs, payload);
+                    const featureId = args.featureId ?? args.id;
+                    if (featureId === undefined || featureId === null) {
+                        selection.clearSelection();
+                        observe(args);
+                        return;
+                    }
+                    const sourceId = typeof args.sourceId === "string" ? args.sourceId : fallbackSourceId;
+                    const target_ = sourceFeatureSelectionTarget(sourceId, featureId);
+                    selection.select([target_], { replace: args.replace !== false });
+                    observe(args);
+                };
+            }
+            case "runWidgetQuery": {
+                if (target.kind !== "widget")
+                    return "`runWidgetQuery` targets `widget:{id}`; no other component accepts it.";
+                const runQuery = target.component.runQuery;
+                if (!runQuery) {
+                    return `Widget "${target.id}" declares no \`runQuery\`, and there is no exploration-level fallback for \`runWidgetQuery\`.`;
+                }
+                return (payload) => {
+                    const args = resolveHonuaInteractionArgs(declaredArgs, payload);
+                    runQuery(args);
+                    observe(args);
+                };
+            }
+            case "setVisibility": {
+                if (target.kind === "map")
+                    return "`setVisibility` targets a layer, widget, or control, never `map`.";
+                const setVisibility = target.component.setVisibility;
+                if (!setVisibility) {
+                    return `${target.kind === "layer" ? "Layer" : target.kind === "widget" ? "Widget" : "Control"} "${target.id}" declares no \`setVisibility\`.`;
+                }
+                return (payload) => {
+                    const args = resolveHonuaInteractionArgs(declaredArgs, payload);
+                    setVisibility(args.visible !== false);
+                    observe(args);
+                };
+            }
+        }
+    }
+}
+// ── Payload builders ──────────────────────────────────────────
+function featureSelectPayload(sourceId, targets) {
+    const first = targets[0];
+    return {
+        sourceId: first?.sourceId ?? sourceId,
+        ...(first ? { featureId: first.id } : {}),
+        ...(first?.sourceLayer ? { sourceLayer: first.sourceLayer } : {}),
+        targets,
+        count: targets.length,
+    };
+}
+function featureHoverPayload(sourceId, hovered) {
+    return {
+        sourceId: hovered?.sourceId ?? sourceId,
+        ...(hovered ? { featureId: hovered.id } : {}),
+        ...(hovered?.sourceLayer ? { sourceLayer: hovered.sourceLayer } : {}),
+        ...(hovered ? { target: hovered } : {}),
+        hovering: hovered !== undefined,
+    };
+}
+function selectionPayload(selection) {
+    const first = selection[0];
+    const qualified = typeof first === "object" && first !== null ? first : undefined;
+    return {
+        targets: selection,
+        count: selection.length,
+        ...(qualified ? { sourceId: qualified.sourceId, featureId: qualified.id } : {}),
+        ...(qualified === undefined && first !== undefined ? { featureId: first } : {}),
+    };
+}
+function changePayload(id, clause, filters) {
+    return {
+        id,
+        ...(clause ? { field: clause.field, operator: clause.operator, value: clause.value, clause } : {}),
+        filters,
+    };
+}
+function viewportPayload(extent) {
+    return {
+        ...(extent ? { bbox: [extent.xmin, extent.ymin, extent.xmax, extent.ymax], extent } : {}),
+    };
+}
+// ── Argument projection ───────────────────────────────────────
+function componentSetFilter(target) {
+    if (target.kind === "map")
+        return undefined;
+    const setFilter = target.component.setFilter;
+    return setFilter ? (clause) => setFilter(clause) : undefined;
+}
+const FILTER_OPERATORS = new Set([
+    "=",
+    "!=",
+    "<",
+    "<=",
+    ">",
+    ">=",
+    "in",
+    "not-in",
+    "between",
+    "like",
+    "is-null",
+    "is-not-null",
+]);
+function filterClauseFromArgs(args) {
+    const declared = args.clause;
+    if (declared && typeof declared === "object" && !Array.isArray(declared)) {
+        const clause = declared;
+        if (typeof clause.field === "string") {
+            return {
+                field: clause.field,
+                operator: FILTER_OPERATORS.has(clause.operator) ? clause.operator : "=",
+                value: clause.value,
+                ...(Array.isArray(clause.appliesTo) ? { appliesTo: clause.appliesTo } : {}),
+            };
+        }
+    }
+    if (typeof args.field !== "string")
+        return undefined;
+    // A `$event.*` path that resolved to nothing clears the filter rather than
+    // installing an `= undefined` clause nothing can translate.
+    if (args.value === undefined && !isValuelessOperator(args.operator))
+        return undefined;
+    return {
+        field: args.field,
+        operator: FILTER_OPERATORS.has(args.operator) ? args.operator : "=",
+        value: args.value,
+        ...(Array.isArray(args.appliesTo) ? { appliesTo: args.appliesTo } : {}),
+    };
+}
+function isValuelessOperator(operator) {
+    return operator === "is-null" || operator === "is-not-null";
+}
+function viewportFromArgs(args) {
+    const bbox = numberTuple(args.bbox, 4);
+    const center = numberTuple(args.center, 2);
+    return {
+        ...(bbox ? { bbox } : {}),
+        ...(center ? { center } : {}),
+        ...(typeof args.zoom === "number" ? { zoom: args.zoom } : {}),
+        ...(typeof args.pitch === "number" ? { pitch: args.pitch } : {}),
+        ...(typeof args.bearing === "number" ? { bearing: args.bearing } : {}),
+    };
+}
+function numberTuple(value, length) {
+    if (!Array.isArray(value) || value.length !== length)
+        return undefined;
+    return value.every((entry) => typeof entry === "number" && Number.isFinite(entry))
+        ? value
+        : undefined;
+}
+function extentFromBbox(bbox) {
+    return bbox ? { xmin: bbox[0], ymin: bbox[1], xmax: bbox[2], ymax: bbox[3] } : undefined;
+}
+function pairLabel(interaction) {
+    return `${interaction.on.event} -> ${interaction.do.verb}`;
+}