@honua/app-platform 0.1.4-beta.0 → 0.1.7-beta.0

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}`;
+}

package/interactions/feature-state.d.ts

@@ -61,6 +61,13 @@ export interface HoverHandlerOptions {
     stateKey?: string;
     /** Source layer (required for vector-tile sources). */
     sourceLayer?: string;
+    /**
+     * Called whenever the hovered feature changes, with the source-qualified
+     * target or `undefined` when the pointer leaves the layer. Mirrors
+     * {@link SelectionHandlerOptions.onSelectionTargetsChange} so a hover, like
+     * a selection, can be published without re-reading `hoveredId` on a timer.
+     */
+    onHoverTargetChange?: (hovered: SourceQualifiedFeatureSelectionTarget | undefined) => void;
 }
 /** Handle returned by {@link createHoverHandler} for cleanup. */
 export interface HoverHandle {

package/interactions/feature-state.d.ts.map

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

package/interactions/feature-state.js

@@ -50,23 +50,31 @@ export function removeFeatureState(map, source, id, key, sourceLayer) {
  * ```
  */
 export function createHoverHandler(map, options) {
-    const { source, layer, stateKey = "hover", sourceLayer } = options;
+    const { source, layer, stateKey = "hover", sourceLayer, onHoverTargetChange } = options;
     let hoveredId;
     function onMouseMove(...args) {
         const e = args[0];
         const featureId = e?.features?.[0]?.id;
         if (featureId === undefined || featureId === null)
             return;
-        if (hoveredId !== undefined && hoveredId !== featureId) {
+        const changed = hoveredId !== featureId;
+        if (hoveredId !== undefined && changed) {
             map.setFeatureState({ source, id: hoveredId, sourceLayer }, { [stateKey]: false });
         }
         hoveredId = featureId;
         map.setFeatureState({ source, id: hoveredId, sourceLayer }, { [stateKey]: true });
+        // Feature-state is re-set idempotently on every mousemove (unchanged
+        // behavior); the callback fires only on an actual hover *change* so a
+        // declarative binding sees one event per hovered feature, not one per
+        // pointer sample.
+        if (changed)
+            onHoverTargetChange?.(sourceFeatureSelectionTarget(source, featureId, { sourceLayer }));
     }
     function onMouseLeave() {
         if (hoveredId !== undefined) {
             map.setFeatureState({ source, id: hoveredId, sourceLayer }, { [stateKey]: false });
             hoveredId = undefined;
+            onHoverTargetChange?.(undefined);
         }
     }
     map.on("mousemove", layer, onMouseMove);

package/map/maplibre-target.js

@@ -89,7 +89,7 @@ export function createHonuaMapLibreStyle(options = {}) {
         ...(options.name ? { name: options.name } : {}),
         ...(options.center ? { center: options.center } : {}),
         ...(options.zoom !== undefined ? { zoom: options.zoom } : {}),
-        metadata: options.basemap ? { "honua:arcgis-basemap": options.basemap } : undefined,
+        ...(options.basemap ? { metadata: { "honua:arcgis-basemap": options.basemap } } : {}),
         sources,
         layers,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@honua/app-platform",
-  "version": "0.1.4-beta.0",
+  "version": "0.1.7-beta.0",
   "description": "Honua application-platform surfaces: app-shell, workspace, scene, operator, studio, and hosted-product clients",
   "keywords": [
     "gis",
@@ -119,7 +119,7 @@
     "proj4": "^2.20.9"
   },
   "peerDependencies": {
-    "@honua/sdk": "0.1.4-beta.0",
+    "@honua/sdk": "0.1.7-beta.0",
     "maplibre-gl": "^5.0.0 || ^6.0.0",
     "cesium": "^1.139.0"
   },

package/realtime/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/realtime/sse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,wBAAwB,EAExB,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1D,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzC,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACvF,mBAAmB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;CAC3F;AAED,MAAM,MAAM,oCAAoC,GAAG,CACjD,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,eAAe,KACnB,6BAA6B,CAAC;AAEnC,MAAM,WAAW,wCAAwC,CAAC,QAAQ,GAAG,OAAO;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,oCAAoC,CAAC;IACnE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,oBAAoB,CAAC,QAAQ,CAAC,CAAC;CAC7E;AAID,wBAAgB,uCAAuC,CAAC,QAAQ,GAAG,OAAO,EACxE,OAAO,EAAE,wCAAwC,CAAC,QAAQ,CAAC,GAC1D,wBAAwB,CAAC,QAAQ,CAAC,CAgGpC;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,2BAA2B,GAAG,GAAG,CAsBhG;AAED,wBAAgB,6BAA6B,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAElH"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/realtime/sse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,wBAAwB,EAExB,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1D,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzC,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACvF,mBAAmB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;CAC3F;AAED,MAAM,MAAM,oCAAoC,GAAG,CACjD,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,eAAe,KACnB,6BAA6B,CAAC;AAEnC,MAAM,WAAW,wCAAwC,CAAC,QAAQ,GAAG,OAAO;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,oCAAoC,CAAC;IACnE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,oBAAoB,CAAC,QAAQ,CAAC,CAAC;CAC7E;AAID,wBAAgB,uCAAuC,CAAC,QAAQ,GAAG,OAAO,EACxE,OAAO,EAAE,wCAAwC,CAAC,QAAQ,CAAC,GAC1D,wBAAwB,CAAC,QAAQ,CAAC,CAqGpC;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,2BAA2B,GAAG,GAAG,CAsBhG;AAED,wBAAgB,6BAA6B,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAElH"}

package/realtime/sse.js

@@ -66,7 +66,13 @@ export function createRealtimeServerSentEventsTransport(options) {
             for (const type of options.eventTypes ?? DEFAULT_EVENT_TYPES) {
                 if (!source.addEventListener)
                     break;
-                const listener = (event) => emitPayload(event.data);
+                const listener = (event) => {
+                    // EventSource also dispatches its native connection-error Event
+                    // under the name "error". It has no data payload and must remain
+                    // the responsibility of `source.onerror` below.
+                    if (typeof event.data === "string")
+                        emitPayload(event.data);
+                };
                 source.addEventListener(type, listener);
                 listeners.push([type, listener]);
             }

package/runtime/style-compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"style-compose.d.ts","sourceRoot":"","sources":["../../../src/runtime/style-compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAA2B,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAElG,OAAO,KAAK,EACV,eAAe,EACf,wBAAwB,EACxB,iBAAiB,EAElB,MAAM,kBAAkB,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAElG,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;AAEnF,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,4DAA4D;AAC5D,wBAAsB,YAAY,CAChC,GAAG,EAAE,eAAe,EACpB,kBAAkB,EAAE,uBAAuB,EAC3C,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,uBAAuB,CAAC,CAalC;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,uBAAuB,EAC7B,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CAuBlC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,uBAAuB,EAAE,KAAK,EAAE,wBAAwB,GAAG,uBAAuB,CAMnH"}
+{"version":3,"file":"style-compose.d.ts","sourceRoot":"","sources":["../../../src/runtime/style-compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAA2B,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAElG,OAAO,KAAK,EACV,eAAe,EACf,wBAAwB,EACxB,iBAAiB,EAElB,MAAM,kBAAkB,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAElG,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;AAEnF,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,4DAA4D;AAC5D,wBAAsB,YAAY,CAChC,GAAG,EAAE,eAAe,EACpB,kBAAkB,EAAE,uBAAuB,EAC3C,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,uBAAuB,CAAC,CAclC;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,uBAAuB,EAC7B,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CAuBlC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,uBAAuB,EAAE,KAAK,EAAE,wBAAwB,GAAG,uBAAuB,CAMnH"}