@honua/react 0.0.20-alpha.0

package/exploration/context.js

@@ -0,0 +1,396 @@
+/**
+ * `ExplorationContext` runtime — a thin coalescing event bus over the
+ * pure reducer in `./reducer.ts`.
+ *
+ * State is updated synchronously on `dispatch`. Listener callbacks run on
+ * a microtask so a burst of intents within the same tick coalesces into a
+ * single `ChangeEvent` per slice (the merged set of changed slices, the
+ * latest state, and the previous state at the start of the tick).
+ *
+ * The implementation deliberately avoids `Promise.resolve().then` in tests
+ * by using `queueMicrotask`, which integrates with vitest's fake-timer /
+ * `await Promise.resolve()` flushing.
+ *
+ * @module
+ */
+import { HonuaExplorationContextError } from "../core/errors.js";
+import { LINKED_VIEW_PRESETS, propagationFor } from "./presets.js";
+import { reduce } from "./reducer.js";
+import { EMPTY_STATE, } from "./types.js";
+/**
+ * Construct an `ExplorationContext` over a dataset.
+ *
+ * The returned object is the canonical place to read and mutate
+ * exploration state. Bind views with `bind()` and listen to slice changes
+ * via `subscribe()`.
+ */
+export function createExplorationContext(options) {
+    const { datasetId, sourceIds } = options;
+    const sourceIdsCopy = [...sourceIds];
+    // `mergeInitial` resolves the active preset (explicit `options.preset`
+    // overrides `initialState.preset`, which overrides the empty default).
+    // Derive `policy` from the merged state's preset rather than reading
+    // `options.preset` directly so that a caller who seeds the context via
+    // `initialState.preset` (without `options.preset`) still starts with a
+    // policy that matches their intended linked-view behavior.
+    let state = mergeInitial(options.initialState, options.preset);
+    let policy = LINKED_VIEW_PRESETS[state.preset];
+    let disposed = false;
+    const bindings = new Map();
+    const sliceListeners = new Map();
+    // Coalescing state — a microtask is scheduled at most once per tick.
+    // `pendingRawChangedSlices` is the full set of slices the reducer changed
+    // (used to wake `"all"` subscribers per the public slice contract);
+    // `pendingChangedSlices` is the policy-filtered subset used to wake
+    // slice-specific subscribers.
+    let pendingFlush = false;
+    let pendingPrev = state;
+    const pendingRawChangedSlices = new Set();
+    const pendingChangedSlices = new Set();
+    let pendingOrigin;
+    function ensureLive(op) {
+        if (disposed) {
+            throw new HonuaExplorationContextError("disposed", `ExplorationContext("${datasetId}") cannot ${op} after dispose()`);
+        }
+    }
+    function scheduleFlush() {
+        if (pendingFlush)
+            return;
+        pendingFlush = true;
+        queueMicrotask(() => {
+            pendingFlush = false;
+            if (pendingRawChangedSlices.size === 0)
+                return;
+            // `"all"` subscribers see every change the reducer produced, including
+            // those the linked-view policy kept local to the originating view.
+            // Slice-specific subscribers only fire for the filtered subset.
+            const allEvent = {
+                state,
+                previous: pendingPrev,
+                changedSlices: new Set(pendingRawChangedSlices),
+                origin: pendingOrigin,
+            };
+            const filteredChanges = new Set(pendingChangedSlices);
+            pendingRawChangedSlices.clear();
+            pendingChangedSlices.clear();
+            pendingPrev = state;
+            pendingOrigin = undefined;
+            const allListeners = sliceListeners.get("all");
+            if (allListeners) {
+                for (const fn of [...allListeners])
+                    fn(allEvent);
+            }
+            for (const slice of filteredChanges) {
+                const listeners = sliceListeners.get(slice);
+                if (!listeners)
+                    continue;
+                const sliceEvent = {
+                    state: allEvent.state,
+                    previous: allEvent.previous,
+                    changedSlices: filteredChanges,
+                    origin: allEvent.origin,
+                };
+                for (const fn of [...listeners])
+                    fn(sliceEvent);
+            }
+        });
+    }
+    return {
+        datasetId,
+        sourceIds: sourceIdsCopy,
+        get state() {
+            return state;
+        },
+        get policy() {
+            return policy;
+        },
+        bind(view) {
+            ensureLive("bind");
+            const binding = { id: view.id, role: view.role };
+            if (bindings.has(binding.id)) {
+                throw new HonuaExplorationContextError("duplicate-binding", `ExplorationContext("${datasetId}"): a view is already bound with id "${binding.id}"`);
+            }
+            bindings.set(binding.id, binding);
+            let unbound = false;
+            return {
+                id: binding.id,
+                unbind() {
+                    if (unbound)
+                        return;
+                    unbound = true;
+                    bindings.delete(binding.id);
+                },
+            };
+        },
+        connectView(view) {
+            ensureLive("connectView");
+            const context = this;
+            const handle = context.bind(view);
+            const binding = bindings.get(handle.id) ?? { id: handle.id, role: view.role };
+            const subscriptions = new Set();
+            let unbound = false;
+            function ensureBound(op) {
+                ensureLive(op);
+                if (unbound) {
+                    throw new HonuaExplorationContextError("unbound-view", `ExplorationContext("${datasetId}"): view "${binding.id}" cannot ${op} after unbind()`);
+                }
+            }
+            function dispatchFromView(intent) {
+                ensureBound("dispatch");
+                context.dispatch(withViewId(intent, binding.id));
+            }
+            function subscribeFromView(slice, fn, options = {}) {
+                ensureBound("subscribe");
+                const slices = normalizeSubscription(slice);
+                if (slices.length === 0)
+                    return () => { };
+                let active = true;
+                let pendingFlush = false;
+                let pendingEvent;
+                const pendingChangedSlices = new Set();
+                function flushViewEvent() {
+                    pendingFlush = false;
+                    if (!active || !pendingEvent || pendingChangedSlices.size === 0)
+                        return;
+                    const base = pendingEvent;
+                    const changedSlices = new Set(pendingChangedSlices);
+                    pendingEvent = undefined;
+                    pendingChangedSlices.clear();
+                    const event = {
+                        state: base.state,
+                        previous: base.previous,
+                        changedSlices,
+                        origin: base.origin,
+                        view: binding,
+                        selfOrigin: base.origin?.viewId === binding.id,
+                    };
+                    fn(event);
+                }
+                function receive(event) {
+                    if (!active)
+                        return;
+                    const selfOrigin = event.origin?.viewId === binding.id;
+                    if (selfOrigin && !options.includeSelf)
+                        return;
+                    pendingEvent = event;
+                    for (const changed of event.changedSlices)
+                        pendingChangedSlices.add(changed);
+                    if (pendingFlush)
+                        return;
+                    pendingFlush = true;
+                    queueMicrotask(flushViewEvent);
+                }
+                const unsubs = slices.map((entry) => context.subscribe(entry, receive));
+                const unsubscribe = () => {
+                    if (!active)
+                        return;
+                    active = false;
+                    for (const unsub of unsubs)
+                        unsub();
+                    subscriptions.delete(unsubscribe);
+                };
+                subscriptions.add(unsubscribe);
+                return unsubscribe;
+            }
+            const controller = {
+                id: binding.id,
+                role: binding.role,
+                get state() {
+                    return context.state;
+                },
+                get policy() {
+                    return context.policy;
+                },
+                dispatch: dispatchFromView,
+                subscribe: subscribeFromView,
+                setFilter(id, clause) {
+                    dispatchFromView({ kind: "set-filter", id, clause });
+                },
+                clearFilter(id) {
+                    dispatchFromView({ kind: "clear-filter", id });
+                },
+                setSpatialFilter(spatialFilter) {
+                    dispatchFromView({ kind: "set-spatial-filter", spatialFilter });
+                },
+                setExtent(extent) {
+                    dispatchFromView({ kind: "set-extent", extent });
+                },
+                select(ids, options) {
+                    dispatchFromView({ kind: "select", ids, replace: options?.replace });
+                },
+                deselect(ids) {
+                    dispatchFromView({ kind: "deselect", ids });
+                },
+                setSort(sort) {
+                    dispatchFromView({ kind: "set-sort", sort });
+                },
+                setPage(page) {
+                    dispatchFromView({ kind: "set-page", page });
+                },
+                setVisibleFields(fields) {
+                    dispatchFromView({ kind: "set-visible-fields", fields });
+                },
+                setGrouping(grouping) {
+                    dispatchFromView({ kind: "set-grouping", grouping });
+                },
+                setAggregation(aggregation) {
+                    dispatchFromView({ kind: "set-aggregation", aggregation });
+                },
+                applyPreset(preset) {
+                    dispatchFromView({ kind: "apply-preset", preset });
+                },
+                snapshot() {
+                    ensureBound("snapshot");
+                    return context.snapshot();
+                },
+                restore(snapshot) {
+                    ensureBound("restore");
+                    context.restore(snapshot);
+                },
+                unbind() {
+                    if (unbound)
+                        return;
+                    unbound = true;
+                    for (const unsub of [...subscriptions])
+                        unsub();
+                    subscriptions.clear();
+                    handle.unbind();
+                },
+            };
+            return controller;
+        },
+        dispatch(intent) {
+            ensureLive("dispatch");
+            const result = reduce(state, intent);
+            if (result.changedSlices.size === 0)
+                return;
+            const filtered = filterByPolicy(result.changedSlices, intent, policy, bindings);
+            // Always update central state — propagation only filters which slice
+            // listeners are woken, not whether the state itself moves. Record the
+            // raw changed slices so `"all"` subscribers always see the change per
+            // the public slice contract, even when the filtered set is empty.
+            const movedToFreshTick = pendingRawChangedSlices.size === 0;
+            if (movedToFreshTick)
+                pendingPrev = state;
+            state = result.state;
+            for (const slice of result.changedSlices)
+                pendingRawChangedSlices.add(slice);
+            for (const slice of filtered)
+                pendingChangedSlices.add(slice);
+            pendingOrigin = intent;
+            // Sync preset rotation if the intent was apply-preset.
+            if (intent.kind === "apply-preset") {
+                policy = LINKED_VIEW_PRESETS[intent.preset];
+            }
+            else if (intent.kind === "snapshot-restore") {
+                policy = LINKED_VIEW_PRESETS[state.preset];
+            }
+            if (pendingRawChangedSlices.size > 0)
+                scheduleFlush();
+        },
+        subscribe(slice, fn) {
+            ensureLive("subscribe");
+            let listeners = sliceListeners.get(slice);
+            if (!listeners) {
+                listeners = new Set();
+                sliceListeners.set(slice, listeners);
+            }
+            listeners.add(fn);
+            return () => {
+                const set = sliceListeners.get(slice);
+                if (!set)
+                    return;
+                set.delete(fn);
+                if (set.size === 0)
+                    sliceListeners.delete(slice);
+            };
+        },
+        snapshot() {
+            // Detach the snapshot from live state — the contract advertises
+            // snapshots as serializable value objects, so caller-side mutation
+            // must not leak into the context and vice versa.
+            return { version: 1, state: cloneExplorationState(state) };
+        },
+        restore(snapshot) {
+            ensureLive("restore");
+            if (snapshot.version !== 1) {
+                throw new HonuaExplorationContextError("incompatible-snapshot", `ExplorationContext("${datasetId}"): snapshot version ${String(snapshot.version)} is not supported`);
+            }
+            this.dispatch({
+                kind: "snapshot-restore",
+                snapshot: { version: 1, state: cloneExplorationState(snapshot.state) },
+            });
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            bindings.clear();
+            sliceListeners.clear();
+            pendingRawChangedSlices.clear();
+            pendingChangedSlices.clear();
+            pendingFlush = false;
+        },
+    };
+}
+// `EMPTY_STATE` and caller-provided `initialState` both hold live nested
+// objects. Deep-clone the merged result so (a) multiple fresh contexts do not
+// share nested references, and (b) post-construction mutation of the caller's
+// `initialState` cannot bypass `dispatch()` by aliasing into live state.
+function mergeInitial(initial, preset) {
+    const merged = {
+        ...EMPTY_STATE,
+        ...(initial ?? {}),
+        preset: preset ?? initial?.preset ?? EMPTY_STATE.preset,
+    };
+    return structuredClone(merged);
+}
+/**
+ * Deep-copy an `ExplorationState`. Used at the snapshot / restore boundary
+ * so that saved snapshots and the live state do not alias shared arrays or
+ * nested objects — callers may retain, serialize, and mutate snapshots
+ * without side effects on the context, and vice versa.
+ */
+function cloneExplorationState(source) {
+    return structuredClone(source);
+}
+/**
+ * Apply linked-view propagation. Every intent updates central state; the
+ * returned set is the subset of changed slices that should wake listeners
+ * given the originating view's role.
+ *
+ * Rules:
+ *  - If `intent.viewId` is undefined, the intent is "external" — all
+ *    changed slices propagate.
+ *  - If the binding exists and the role's preset entry permits the slice,
+ *    the slice propagates.
+ *  - If the binding does not exist, treat as external.
+ *  - `apply-preset` and `snapshot-restore` always propagate fully so that
+ *    structural changes are visible everywhere.
+ */
+function filterByPolicy(changed, intent, policy, bindings) {
+    if (intent.kind === "apply-preset" || intent.kind === "snapshot-restore") {
+        return changed;
+    }
+    if (!intent.viewId)
+        return changed;
+    const binding = bindings.get(intent.viewId);
+    if (!binding)
+        return changed;
+    const allowed = propagationFor(policy.preset, binding.role);
+    if (allowed.size === 0)
+        return new Set();
+    const out = new Set();
+    for (const slice of changed) {
+        if (allowed.has(slice))
+            out.add(slice);
+    }
+    return out;
+}
+function withViewId(intent, viewId) {
+    return { ...intent, viewId };
+}
+function normalizeSubscription(slice) {
+    const values = Array.isArray(slice) ? slice : [slice];
+    return [...new Set(values)];
+}

package/exploration/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@honua/sdk-js/exploration` — protocol-neutral state container shared across
+ * linked views (map / table / chart). Provides `createExplorationContext()`
+ * with preset link policies (`globalLinked`, `mapDriven`, `gridDriven`,
+ * `chartDriven`, `decoupled`). See `docs/exploration-context.md` for the
+ * full design.
+ *
+ * @example
+ * ```ts
+ * import { createExplorationContext } from "@honua/sdk-js/exploration";
+ *
+ * const ctx = createExplorationContext({ dataset, preset: "globalLinked" });
+ * ctx.dispatch({ type: "set-extent", extent });
+ * const unsubscribe = ctx.subscribe(["selection"], (state) => render(state));
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { EMPTY_STATE, SLICES, } from "./types.js";
+export type { ApplyPresetIntent, ChangeEvent, ClearFilterIntent, CreateExplorationContextOptions, DeselectIntent, ExplorationContext, ExplorationIntent, ExplorationSlice, ExplorationState, ExplorationStateSnapshot, ExplorationViewChangeEvent, ExplorationViewController, ExplorationViewIntent, ExplorationViewListener, ExplorationViewSubscribeOptions, ExplorationViewSubscription, FeatureSelectionTarget, FilterClause, FilterOperator, LinkedViewPolicy, LinkedViewPresetName, LinkedViewRule, Listener, SelectIntent, SetAggregationIntent, SetExtentIntent, SetFilterIntent, SetGroupingIntent, SetPageIntent, SetSortIntent, SetSpatialFilterIntent, SetVisibleFieldsIntent, SnapshotRestoreIntent, SourceQualifiedFeatureSelectionTarget, Unsubscribe, ViewBinding, ViewHandle, ViewRole, } from "./types.js";
+export { LINKED_VIEW_PRESETS, propagationFor } from "./presets.js";
+export { reduce, type ReducerResult } from "./reducer.js";
+export { createExplorationContext } from "./context.js";
+export { featureSelectionKey, isSourceQualifiedSelectionTarget, sourceFeatureSelectionTarget } from "./selection.js";
+export { extentToSpatialFilter, selectLinkedViewQueryProjection, subscribeExplorationSelector, } from "./selectors.js";
+export type { ExplorationSelector, ExplorationSelectorListener, ExplorationSelectorSubscribeOptions, LinkedViewQueryProjection, LinkedViewQueryProjectionOptions, LinkedViewSpatialMode, } from "./selectors.js";
+//# sourceMappingURL=index.d.ts.map

package/exploration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/exploration/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,WAAW,EACX,MAAM,GACP,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,+BAA+B,EAC/B,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,qBAAqB,EACrB,uBAAuB,EACvB,+BAA+B,EAC/B,2BAA2B,EAC3B,sBAAsB,EACtB,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,qCAAqC,EACrC,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,gCAAgC,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AACrH,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,mBAAmB,EACnB,2BAA2B,EAC3B,mCAAmC,EACnC,yBAAyB,EACzB,gCAAgC,EAChC,qBAAqB,GACtB,MAAM,gBAAgB,CAAC"}

package/exploration/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@honua/sdk-js/exploration` — protocol-neutral state container shared across
+ * linked views (map / table / chart). Provides `createExplorationContext()`
+ * with preset link policies (`globalLinked`, `mapDriven`, `gridDriven`,
+ * `chartDriven`, `decoupled`). See `docs/exploration-context.md` for the
+ * full design.
+ *
+ * @example
+ * ```ts
+ * import { createExplorationContext } from "@honua/sdk-js/exploration";
+ *
+ * const ctx = createExplorationContext({ dataset, preset: "globalLinked" });
+ * ctx.dispatch({ type: "set-extent", extent });
+ * const unsubscribe = ctx.subscribe(["selection"], (state) => render(state));
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { EMPTY_STATE, SLICES, } from "./types.js";
+export { LINKED_VIEW_PRESETS, propagationFor } from "./presets.js";
+export { reduce } from "./reducer.js";
+export { createExplorationContext } from "./context.js";
+export { featureSelectionKey, isSourceQualifiedSelectionTarget, sourceFeatureSelectionTarget } from "./selection.js";
+export { extentToSpatialFilter, selectLinkedViewQueryProjection, subscribeExplorationSelector, } from "./selectors.js";

package/exploration/presets.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Built-in linked-view presets. The presets are declarative — the reducer
+ * uses them to decide whether an intent originating in one view should
+ * propagate to peers.
+ *
+ * Documented in `docs/exploration-context.md`.
+ *
+ * @module
+ */
+import type { ExplorationSlice, LinkedViewPolicy, LinkedViewPresetName, ViewRole } from "./types.js";
+/**
+ * Built-in presets. The role-keyed `propagatesSlices` arrays describe what
+ * a view of that role contributes when it is the originator of an intent.
+ *
+ * Usage by the reducer: when an intent arrives with `viewId`, the reducer
+ * looks up the originator's role and intersects the slices it changed
+ * with the role's `propagatesSlices`. Slices outside the intersection are
+ * still applied to the central state but listeners on peer views' specific
+ * slice subscriptions are not woken.
+ *
+ * `globalLinked` is the default — it is the safe choice for prototypes
+ * and small dashboards where every change should affect every view.
+ */
+export declare const LINKED_VIEW_PRESETS: Readonly<Record<LinkedViewPresetName, LinkedViewPolicy>>;
+/** Lookup the slices a role propagates under a given preset. */
+export declare function propagationFor(preset: LinkedViewPresetName, role: ViewRole): ReadonlySet<ExplorationSlice>;
+//# sourceMappingURL=presets.d.ts.map

package/exploration/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../src/exploration/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAiBrG;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,CA6DxF,CAAC;AAcF,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,EAAE,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC,gBAAgB,CAAC,CAI1G"}

package/exploration/presets.js

@@ -0,0 +1,114 @@
+/**
+ * Built-in linked-view presets. The presets are declarative — the reducer
+ * uses them to decide whether an intent originating in one view should
+ * propagate to peers.
+ *
+ * Documented in `docs/exploration-context.md`.
+ *
+ * @module
+ */
+const ALL_SLICES = [
+    "filters",
+    "spatialFilter",
+    "extent",
+    "selection",
+    "sort",
+    "page",
+    "visibleFields",
+    "grouping",
+    "aggregation",
+    "preset",
+];
+const NO_SLICES = [];
+/**
+ * Built-in presets. The role-keyed `propagatesSlices` arrays describe what
+ * a view of that role contributes when it is the originator of an intent.
+ *
+ * Usage by the reducer: when an intent arrives with `viewId`, the reducer
+ * looks up the originator's role and intersects the slices it changed
+ * with the role's `propagatesSlices`. Slices outside the intersection are
+ * still applied to the central state but listeners on peer views' specific
+ * slice subscriptions are not woken.
+ *
+ * `globalLinked` is the default — it is the safe choice for prototypes
+ * and small dashboards where every change should affect every view.
+ */
+export const LINKED_VIEW_PRESETS = {
+    globalLinked: {
+        preset: "globalLinked",
+        rules: roleRules({
+            map: ALL_SLICES,
+            grid: ALL_SLICES,
+            chart: ALL_SLICES,
+            filter: ALL_SLICES,
+            detail: ALL_SLICES,
+            form: ALL_SLICES,
+            custom: ALL_SLICES,
+        }),
+    },
+    mapDriven: {
+        preset: "mapDriven",
+        rules: roleRules({
+            map: ["extent", "spatialFilter", "selection", "filters"],
+            grid: NO_SLICES,
+            chart: NO_SLICES,
+            filter: ["filters", "spatialFilter"],
+            detail: NO_SLICES,
+            form: NO_SLICES,
+            custom: NO_SLICES,
+        }),
+    },
+    gridDriven: {
+        preset: "gridDriven",
+        rules: roleRules({
+            map: NO_SLICES,
+            grid: ["selection", "sort", "page", "filters", "visibleFields"],
+            chart: NO_SLICES,
+            filter: ["filters", "spatialFilter"],
+            detail: NO_SLICES,
+            form: NO_SLICES,
+            custom: NO_SLICES,
+        }),
+    },
+    chartDriven: {
+        preset: "chartDriven",
+        rules: roleRules({
+            map: NO_SLICES,
+            grid: NO_SLICES,
+            chart: ["grouping", "aggregation", "filters", "selection"],
+            filter: ["filters"],
+            detail: NO_SLICES,
+            form: NO_SLICES,
+            custom: NO_SLICES,
+        }),
+    },
+    decoupled: {
+        preset: "decoupled",
+        rules: roleRules({
+            map: NO_SLICES,
+            grid: NO_SLICES,
+            chart: NO_SLICES,
+            filter: NO_SLICES,
+            detail: NO_SLICES,
+            form: NO_SLICES,
+            custom: NO_SLICES,
+        }),
+    },
+};
+function roleRules(table) {
+    return [
+        { role: "map", propagatesSlices: table.map },
+        { role: "grid", propagatesSlices: table.grid },
+        { role: "chart", propagatesSlices: table.chart },
+        { role: "filter", propagatesSlices: table.filter },
+        { role: "detail", propagatesSlices: table.detail },
+        { role: "form", propagatesSlices: table.form },
+        { role: "custom", propagatesSlices: table.custom },
+    ];
+}
+/** Lookup the slices a role propagates under a given preset. */
+export function propagationFor(preset, role) {
+    const policy = LINKED_VIEW_PRESETS[preset];
+    const rule = policy.rules.find((r) => r.role === role);
+    return new Set(rule?.propagatesSlices ?? NO_SLICES);
+}

package/exploration/reducer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure reducer for `ExplorationState`. Every transition returns a new
+ * state object — readers may use referential equality to detect change on
+ * any slice (e.g. `prev.filters !== next.filters`).
+ *
+ * The reducer does not own scheduling, propagation, or events; those live
+ * in `./context.ts`.
+ *
+ * @module
+ */
+import type { ExplorationIntent, ExplorationSlice, ExplorationState } from "./types.js";
+export interface ReducerResult {
+    readonly state: ExplorationState;
+    readonly changedSlices: ReadonlySet<ExplorationSlice>;
+}
+/**
+ * Apply one intent. Returns the next state plus the set of slices that
+ * actually changed (by reference). Callers compare the set rather than
+ * re-deriving it so that "no-op" intents (e.g. setting the same sort)
+ * do not wake listeners.
+ */
+export declare function reduce(state: ExplorationState, intent: ExplorationIntent): ReducerResult;
+//# sourceMappingURL=reducer.d.ts.map

package/exploration/reducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducer.d.ts","sourceRoot":"","sources":["../../../src/exploration/reducer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAGjB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC;CACvD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,iBAAiB,GAAG,aAAa,CA4GxF"}