@genome-spy/core 0.67.0 → 0.68.0

package/dist/src/scales/scaleResolution.js

@@ -13,7 +13,7 @@ import { configureDomain } from "../scale/scale.js";
 
 import ScaleInstanceManager from "./scaleInstanceManager.js";
 import { resolveScalePropsBase } from "./scalePropsResolver.js";
-import ScaleDomainAggregator from "./scaleDomainAggregator.js";
+import DomainPlanner from "./domainPlanner.js";
 import ScaleInteractionController from "./scaleInteractionController.js";
 import {
     INDEX,
@@ -23,10 +23,10 @@ import {
     QUANTITATIVE,
 } from "./scaleResolutionConstants.js";
 
+import { getAccessorDomainKey } from "../encoder/accessor.js";
 import { isSecondaryChannel } from "../encoder/encoder.js";
 import { NominalDomain } from "../utils/domainArray.js";
-import { asArray, shallowArrayEquals } from "../utils/arrayUtils.js";
-import { VISIT_SKIP } from "../view/view.js";
+import { shallowArrayEquals } from "../utils/arrayUtils.js";
 import createIndexer from "../utils/indexer.js";
 
 // Register scaleLocus to Vega-Scale.
@@ -44,7 +44,7 @@ export { INDEX, LOCUS, NOMINAL, ORDINAL, QUANTITATIVE };
  * @prop {import("../view/unitView.js").default} view TODO: Get rid of the view reference
  * @prop {T} channel
  * @prop {import("../spec/channel.js").ChannelDefWithScale} channelDef
- * @prop {(channel: ChannelWithScale, type: import("../spec/channel.js").Type) => DomainArray} dataDomainSource
+ * @prop {boolean} contributesToDomain
  */
 /**
  * Resolves a shared scale for a channel by merging scale properties and domains
@@ -53,6 +53,16 @@ export { INDEX, LOCUS, NOMINAL, ORDINAL, QUANTITATIVE };
  * notifications, while delegating domain aggregation, scale instance setup, and
  * interaction logic to focused helpers.
  *
+ * Documentation overview of current concerns this class (and its helpers) deal with:
+ * - Resolution membership and rules (shared/independent/forced/excluded, visibility, registration).
+ * - Scale property aggregation (merge props, channel overrides, unique scale names).
+ * - Domain computation and caching (configured/data unions, defaults, indexer stability, subscriptions).
+ * - Scale instance lifecycle (create, reconfigure props, apply domains, notify changes).
+ * - Interaction and zoom (zoom/pan/reset coordination, snapshots, zoom extents).
+ * - Rendering integration (range textures, axis sizing/positioning).
+ * - Locus-specific conversions (complex intervals, genome extent bindings).
+ * - Diagnostics and edge cases (ordinal unknown, nice/zero/padding, log warnings).
+ *
  * @implements {ScaleResolutionApi}
  */
 export default class ScaleResolution {
@@ -76,6 +86,9 @@ export default class ScaleResolution {
     /** @type {Set<ScaleResolutionMember>} The involved views */
     #members = new Set();
 
+    /** @type {Set<ScaleResolutionMember>} */
+    #dataDomainMembers = new Set();
+
     /**
      * @type {Record<ScaleResolutionEventType, Set<ScaleResolutionListener>>}
      */
@@ -87,7 +100,7 @@ export default class ScaleResolution {
     /** @type {ScaleInstanceManager} */
     #scaleManager;
 
-    /** @type {ScaleDomainAggregator} */
+    /** @type {DomainPlanner} */
     #domainAggregator;
 
     /** @type {ScaleInteractionController} */
@@ -109,8 +122,10 @@ export default class ScaleResolution {
         /** @type {string} An optional unique identifier for the scale */
         this.name = undefined;
 
-        this.#domainAggregator = new ScaleDomainAggregator({
+        this.#domainAggregator = new DomainPlanner({
             getMembers: () => this.#getActiveMembers(),
+            getDataMembers: () =>
+                this.#getActiveMembers(this.#dataDomainMembers),
             getType: () => this.type,
             getLocusExtent: () => this.#getLocusExtent(),
             fromComplexInterval: this.fromComplexInterval.bind(this),
@@ -146,10 +161,13 @@ export default class ScaleResolution {
         return first.view;
     }
 
-    #getActiveMembers() {
+    /**
+     * @param {Set<ScaleResolutionMember>} [members]
+     */
+    #getActiveMembers(members = this.#members) {
         /** @type {Set<ScaleResolutionMember>} */
         const active = new Set();
-        for (const member of this.#members) {
+        for (const member of members) {
             const view = member.view;
             if (!view.isConfiguredVisible()) {
                 continue;
@@ -289,6 +307,10 @@ export default class ScaleResolution {
         }
 
         this.#members.add(newMember);
+        if (newMember.contributesToDomain) {
+            this.#dataDomainMembers.add(newMember);
+        }
+        this.#domainAggregator.invalidateConfiguredDomain();
     }
 
     /**
@@ -299,10 +321,62 @@ export default class ScaleResolution {
         this.#addMember(member);
         return () => {
             const removed = this.#members.delete(member);
+            if (removed) {
+                this.#dataDomainMembers.delete(member);
+                this.#domainAggregator.invalidateConfiguredDomain();
+            }
             return removed && this.#members.size === 0;
         };
     }
 
+    #hasRenderedMember() {
+        for (const member of this.#members) {
+            if (member.view.hasRendered()) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * @param {import("../data/collector.js").default} collector
+     * @param {Iterable<import("../types/encoder.js").ScaleAccessor>} accessors
+     * @returns {() => void}
+     */
+    registerCollectorSubscriptions(collector, accessors) {
+        /** @type {Set<string>} */
+        const domainKeys = new Set();
+
+        for (const accessor of accessors) {
+            if (accessor.channelDef.domainInert) {
+                continue;
+            }
+            domainKeys.add(getAccessorDomainKey(accessor, this.type));
+        }
+
+        if (domainKeys.size === 0) {
+            return () => undefined;
+        }
+
+        const listener = () => {
+            this.reconfigureDomain();
+        };
+
+        /** @type {(() => void)[]} */
+        const unregisters = [];
+        for (const domainKey of domainKeys) {
+            unregisters.push(
+                collector.subscribeDomainChanges(domainKey, listener)
+            );
+        }
+
+        return () => {
+            for (const unregister of unregisters) {
+                unregister();
+            }
+        };
+    }
+
     /**
      * Returns true if the domain has been defined explicitly, i.e. not extracted from the data.
      */
@@ -432,36 +506,108 @@ export default class ScaleResolution {
      * or when scale properties are otherwise re-resolved from the view hierarchy.
      */
     reconfigure() {
-        const props = this.#getScaleProps(true);
-        this.#reconfigureWith(() => this.#scaleManager.reconfigureScale(props));
+        this.#domainAggregator.invalidateConfiguredDomain();
+        const state = this.#computeScaleState(true);
+        if (!state) {
+            return;
+        }
+        this.#applyReconfigure(state, (scale, props) =>
+            this.#scaleManager.reconfigureScale(props)
+        );
+        this.#finalizeReconfigure(state);
     }
 
     /**
      * Reconfigures only the effective domain (configured + data-derived).
      *
      * Use this when data changes but the scale membership and properties are stable.
+     *
      */
     reconfigureDomain() {
-        const props = this.#getScaleProps(true);
-        this.#reconfigureWith(() => {
-            configureDomain(this.#scaleManager.scale, props);
-        });
+        const state = this.#computeScaleState(true, true);
+        if (!state) {
+            return;
+        }
+        const { domainConfig, targetDomain } = state;
+        const domainMatches =
+            targetDomain != null &&
+            shallowArrayEquals(targetDomain, state.scale.domain());
+
+        if (targetDomain != null && !domainMatches) {
+            this.#applyReconfigure(state, (scale) => {
+                scale.domain(targetDomain);
+                if (domainConfig.applyOrdinalUnknown) {
+                    // Keep ordinal unknown handling close to the domain write so
+                    // domainImplicit semantics stay aligned with the applied domain.
+                    /** @type {any} */ (scale).unknown(
+                        domainConfig.ordinalUnknown
+                    );
+                }
+            });
+        }
+        this.#finalizeReconfigure(state);
     }
 
     /**
-     * @param {() => void} apply
+     * @param {boolean} extractDataDomain
+     * @param {boolean} [includeDomainConfig]
+     * @returns {{
+     *     scale: ScaleWithProps,
+     *     props: import("../spec/scale.js").Scale,
+     *     previousDomain: any[],
+     *     domainWasInitialized: boolean,
+     *     domainConfig?: ReturnType<typeof configureDomain>,
+     *     targetDomain?: any[] | null,
+     * } | undefined}
      */
-    #reconfigureWith(apply) {
+    #computeScaleState(extractDataDomain, includeDomainConfig = false) {
         const scale = this.#scaleManager.scale;
 
         if (!scale || scale.type == "null") {
             return;
         }
 
-        const domainWasInitialized = this.#isDomainInitialized();
-        const previousDomain = scale.domain();
+        const state = {
+            scale,
+            props: this.#getScaleProps(extractDataDomain),
+            previousDomain: scale.domain(),
+            domainWasInitialized: this.#isDomainInitialized(),
+        };
+
+        if (includeDomainConfig) {
+            const domainConfig = configureDomain(scale, state.props);
+            return {
+                ...state,
+                domainConfig,
+                targetDomain: domainConfig.domain,
+            };
+        }
 
-        this.#scaleManager.withDomainNotificationsSuppressed(apply);
+        return state;
+    }
+
+    /**
+     * @param {{
+     *     scale: ScaleWithProps,
+     *     props: import("../spec/scale.js").Scale,
+     * }} inputs
+     * @param {(scale: ScaleWithProps, props: import("../spec/scale.js").Scale) => void} apply
+     */
+    #applyReconfigure(inputs, apply) {
+        this.#scaleManager.withDomainNotificationsSuppressed(() => {
+            apply(inputs.scale, inputs.props);
+        });
+    }
+
+    /**
+     * @param {{
+     *     scale: ScaleWithProps,
+     *     previousDomain: any[],
+     *     domainWasInitialized: boolean,
+     * }} inputs
+     */
+    #finalizeReconfigure(inputs) {
+        const { scale, previousDomain, domainWasInitialized } = inputs;
 
         if (
             this.#domainAggregator.captureInitialDomain(
@@ -475,13 +621,18 @@ export default class ScaleResolution {
         }
 
         const newDomain = scale.domain();
-        if (!shallowArrayEquals(newDomain, previousDomain)) {
-            if (this.isZoomable()) {
-                // Don't mess with zoomed views, restore the previous domain
-                this.#scaleManager.withDomainNotificationsSuppressed(() => {
-                    scale.domain(previousDomain);
-                });
-            } else if (this.#interactionController.isZoomingSupported()) {
+        const action = this.#interactionController.getDomainChangeAction(
+            previousDomain,
+            newDomain
+        );
+
+        if (action === "restore") {
+            // Don't mess with zoomed views, restore the previous domain
+            this.#scaleManager.withDomainNotificationsSuppressed(() => {
+                scale.domain(previousDomain);
+            });
+        } else if (action === "animate") {
+            if (this.#hasRenderedMember()) {
                 // It can be zoomed, so lets make a smooth transition.
                 // Restore the previous domain and zoom smoothly to the new domain.
                 this.#scaleManager.withDomainNotificationsSuppressed(() => {
@@ -489,10 +640,12 @@ export default class ScaleResolution {
                 });
                 this.zoomTo(newDomain, 500); // TODO: Configurable duration
             } else {
-                // Update immediately if the previous domain was the initial domain [0, 0]
-                // Notifications were suppressed during reconfigure; notify explicitly.
                 this.#notifyListeners("domain");
             }
+        } else if (action === "notify") {
+            // Update immediately if the previous domain was the initial domain [0, 0]
+            // Notifications were suppressed during reconfigure; notify explicitly.
+            this.#notifyListeners("domain");
         }
     }
 
@@ -688,45 +841,3 @@ export default class ScaleResolution {
         return /** @type {number[]} */ (interval);
     }
 }
-
-/**
- * Reconfigures scale domains for resolutions used by the given view(s).
- *
- * Use this for data-driven updates where only domains need refreshing.
- *
- * TODO: This should be made unnecessary. Collectors should trigger the reconfiguration
- * for those views that get their data from the collector.
- *
- * TODO: This may reconfigure channels that are not affected by the change.
- * Causes performance issues with domains that are extracted from data.
- *
- * @param {import("../view/view.js").default | import("../view/view.js").default[]} fromViews
- * @param {(view: import("../view/view.js").default) => boolean} [viewFilter]
- */
-export function reconfigureScaleDomains(fromViews, viewFilter) {
-    /** @type {Set<ScaleResolution>} */
-    const uniqueResolutions = new Set();
-
-    /** @param {import("../view/view.js").default} view */
-    function collectResolutions(view) {
-        for (const resolution of Object.values(view.resolutions.scale)) {
-            uniqueResolutions.add(resolution);
-        }
-    }
-
-    /** @type {import("../view/view.js").VisitorCallback} */
-    function collectVisibleResolutions(view) {
-        if (viewFilter && !viewFilter(view)) {
-            return VISIT_SKIP;
-        }
-        if (view.options.contributesToScaleDomain) {
-            collectResolutions(view);
-        }
-    }
-
-    for (const fromView of asArray(fromViews)) {
-        fromView.visit(collectVisibleResolutions);
-    }
-
-    uniqueResolutions.forEach((resolution) => resolution.reconfigureDomain());
-}

package/dist/src/scales/scaleResolution.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaleResolution.test.d.ts","sourceRoot":"","sources":["../../../src/scales/scaleResolution.test.js"],"names":[],"mappings":"sBAYa,OAAO,oBAAoB,EAAE,OAAO"}
+{"version":3,"file":"scaleResolution.test.d.ts","sourceRoot":"","sources":["../../../src/scales/scaleResolution.test.js"],"names":[],"mappings":"sBAWa,OAAO,oBAAoB,EAAE,OAAO"}

package/dist/src/selection/selection.d.ts

@@ -8,6 +8,27 @@ export function createSinglePointSelection(datum: import("../data/flowNode.js").
  * @returns {import("../types/selectionTypes.js").MultiPointSelection}
  */
 export function createMultiPointSelection(data?: import("../data/flowNode.js").Datum[]): import("../types/selectionTypes.js").MultiPointSelection;
+/**
+ * Returns key tuples for a point selection.
+ *
+ * @param {import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection} selection
+ * @param {string[]} keyFields
+ * @returns {import("../spec/channel.js").Scalar[][] | undefined}
+ */
+export function getPointSelectionKeyTuples(selection: import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection, keyFields: string[]): import("../spec/channel.js").Scalar[][] | undefined;
+/**
+ * Resolves key tuples to a point selection value object.
+ *
+ * @param {"single" | "multi"} type
+ * @param {string[]} keyFields
+ * @param {import("../spec/channel.js").Scalar[][]} keyTuples
+ * @param {(keyFields: string[], keyTuple: import("../spec/channel.js").Scalar[]) => import("../data/flowNode.js").Datum | undefined} resolveDatum
+ * @returns {{ selection: import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection, unresolved: import("../spec/channel.js").Scalar[][] } | undefined}
+ */
+export function resolvePointSelectionFromKeyTuples(type: "single" | "multi", keyFields: string[], keyTuples: import("../spec/channel.js").Scalar[][], resolveDatum: (keyFields: string[], keyTuple: import("../spec/channel.js").Scalar[]) => import("../data/flowNode.js").Datum | undefined): {
+    selection: import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection;
+    unresolved: import("../spec/channel.js").Scalar[][];
+} | undefined;
 /**
  *
  * @param {import("../spec/channel.js").ChannelWithScale[]} channels

package/dist/src/selection/selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../../src/selection/selection.js"],"names":[],"mappings":"AAOA;;;GAGG;AACH,kDAHW,OAAO,qBAAqB,EAAE,KAAK,GACjC,OAAO,4BAA4B,EAAE,oBAAoB,CAQrE;AAED;;;GAGG;AACH,iDAHW,OAAO,qBAAqB,EAAE,KAAK,EAAE,GACnC,OAAO,4BAA4B,EAAE,mBAAmB,CAQpE;AAED;;;;GAIG;AACH,kDAHW,OAAO,oBAAoB,EAAE,gBAAgB,EAAE,GAC7C,OAAO,4BAA4B,EAAE,iBAAiB,CASlE;AAED;;;;;;;GAOG;AACH,qDAJW,OAAO,4BAA4B,EAAE,mBAAmB,2BACxD,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,QAAQ,GAAG,QAAQ,EAAE,QAAQ,CAAC,OAAO,qBAAqB,EAAE,KAAK,CAAC,CAAC,CAAC,GACzF,OAAO,4BAA4B,EAAE,mBAAmB,CA2BpE;AAED;;;;;GAKG;AACH,oDAHW,OAAO,sBAAsB,EAAE,qBAAqB,aACpD,OAAO,4BAA4B,EAAE,SAAS,UAgExD;AAED;;;GAGG;AACH,+CAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,iBAAiB,CAI/E;AAED;;;GAGG;AACH,kDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,oBAAoB,CAIlF;AAED;;;GAGG;AACH,iDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,mBAAmB,CAIjF;AAED;;;GAGG;AACH,gDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,kBAAkB,CAIhF;AAED;;;GAGG;AACH,gDAHW,OAAO,sBAAsB,EAAE,qBAAqB,GAClD,OAAO,sBAAsB,EAAE,eAAe,CA4B1D;AAED;;;GAGG;AACH,+CAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,MAAM,IAAI,OAAO,sBAAsB,EAAE,oBAAoB,CAIzE;AAED;;;;GAIG;AACH,kDAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,MAAM,IAAI,OAAO,sBAAsB,EAAE,uBAAuB,CAI5E;AAED;;GAEG;AACH,qDAFW,OAAO,4BAA4B,EAAE,iBAAiB,WAMhE;AAED;;;;;GAKG;AACH,kDAHW,iBAAiB,SACjB,aAAa,WAUvB;AAED;;;GAGG;AACH,yCAHW,OAAO,sBAAsB,EAAE,eAAe,CAAC,IAAI,CAAC,GAClD,OAAO,sBAAsB,EAAE,WAAW,CAsBtD;gCAvCY,OAAO,4BAA4B,EAAE,iBAAiB;4BACtD,OAAO,CAAC,MAAM,CAAC,MAAM,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC"}
+{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../../src/selection/selection.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH,kDAHW,OAAO,qBAAqB,EAAE,KAAK,GACjC,OAAO,4BAA4B,EAAE,oBAAoB,CAQrE;AAED;;;GAGG;AACH,iDAHW,OAAO,qBAAqB,EAAE,KAAK,EAAE,GACnC,OAAO,4BAA4B,EAAE,mBAAmB,CAQpE;AAED;;;;;;GAMG;AACH,sDAJW,OAAO,4BAA4B,EAAE,oBAAoB,GAAG,OAAO,4BAA4B,EAAE,mBAAmB,aACpH,MAAM,EAAE,GACN,OAAO,oBAAoB,EAAE,MAAM,EAAE,EAAE,GAAG,SAAS,CA2B/D;AAED;;;;;;;;GAQG;AACH,yDANW,QAAQ,GAAG,OAAO,aAClB,MAAM,EAAE,aACR,OAAO,oBAAoB,EAAE,MAAM,EAAE,EAAE,gBACvC,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,oBAAoB,EAAE,MAAM,EAAE,KAAK,OAAO,qBAAqB,EAAE,KAAK,GAAG,SAAS,GACvH;IAAE,SAAS,EAAE,OAAO,4BAA4B,EAAE,oBAAoB,GAAG,OAAO,4BAA4B,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE,OAAO,oBAAoB,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,GAAG,SAAS,CAsChN;AAED;;;;GAIG;AACH,kDAHW,OAAO,oBAAoB,EAAE,gBAAgB,EAAE,GAC7C,OAAO,4BAA4B,EAAE,iBAAiB,CASlE;AAED;;;;;;;GAOG;AACH,qDAJW,OAAO,4BAA4B,EAAE,mBAAmB,2BACxD,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,QAAQ,GAAG,QAAQ,EAAE,QAAQ,CAAC,OAAO,qBAAqB,EAAE,KAAK,CAAC,CAAC,CAAC,GACzF,OAAO,4BAA4B,EAAE,mBAAmB,CA2BpE;AAED;;;;;GAKG;AACH,oDAHW,OAAO,sBAAsB,EAAE,qBAAqB,aACpD,OAAO,4BAA4B,EAAE,SAAS,UAgExD;AAED;;;GAGG;AACH,+CAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,iBAAiB,CAI/E;AAED;;;GAGG;AACH,kDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,oBAAoB,CAIlF;AAED;;;GAGG;AACH,iDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,mBAAmB,CAIjF;AAED;;;GAGG;AACH,gDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,kBAAkB,CAIhF;AAED;;;GAGG;AACH,gDAHW,OAAO,sBAAsB,EAAE,qBAAqB,GAClD,OAAO,sBAAsB,EAAE,eAAe,CA4B1D;AAED;;;GAGG;AACH,+CAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,MAAM,IAAI,OAAO,sBAAsB,EAAE,oBAAoB,CAIzE;AAED;;;;GAIG;AACH,kDAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,MAAM,IAAI,OAAO,sBAAsB,EAAE,uBAAuB,CAI5E;AAED;;GAEG;AACH,qDAFW,OAAO,4BAA4B,EAAE,iBAAiB,WAMhE;AAED;;;;;GAKG;AACH,kDAHW,iBAAiB,SACjB,aAAa,WAUvB;AAED;;;GAGG;AACH,yCAHW,OAAO,sBAAsB,EAAE,eAAe,CAAC,IAAI,CAAC,GAClD,OAAO,sBAAsB,EAAE,WAAW,CAsBtD;gCAvCY,OAAO,4BAA4B,EAAE,iBAAiB;4BACtD,OAAO,CAAC,MAAM,CAAC,MAAM,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC"}

package/dist/src/selection/selection.js

@@ -4,6 +4,7 @@ import {
     isPrimaryPositionalChannel,
 } from "../encoder/encoder.js";
 import { validateParameterName } from "../view/paramMediator.js";
+import { field } from "../utils/field.js";
 
 /**
  * @param {import("../data/flowNode.js").Datum} datum
@@ -29,6 +30,87 @@ export function createMultiPointSelection(data) {
     };
 }
 
+/**
+ * Returns key tuples for a point selection.
+ *
+ * @param {import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection} selection
+ * @param {string[]} keyFields
+ * @returns {import("../spec/channel.js").Scalar[][] | undefined}
+ */
+export function getPointSelectionKeyTuples(selection, keyFields) {
+    if (!keyFields || keyFields.length === 0) {
+        return;
+    }
+
+    const accessors = keyFields.map((fieldName) => field(fieldName));
+    const toTuple = (
+        /** @type {import("../data/flowNode.js").Datum} */ datum
+    ) => accessors.map((accessor) => accessor(datum));
+
+    if (isSinglePointSelection(selection)) {
+        if (!selection.datum) {
+            return [];
+        }
+
+        return [toTuple(selection.datum)];
+    }
+
+    if (isMultiPointSelection(selection)) {
+        return [...selection.data.values()].map(toTuple);
+    }
+
+    throw new Error(
+        `Expected a point selection, got: ${JSON.stringify(selection)}`
+    );
+}
+
+/**
+ * Resolves key tuples to a point selection value object.
+ *
+ * @param {"single" | "multi"} type
+ * @param {string[]} keyFields
+ * @param {import("../spec/channel.js").Scalar[][]} keyTuples
+ * @param {(keyFields: string[], keyTuple: import("../spec/channel.js").Scalar[]) => import("../data/flowNode.js").Datum | undefined} resolveDatum
+ * @returns {{ selection: import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection, unresolved: import("../spec/channel.js").Scalar[][] } | undefined}
+ */
+export function resolvePointSelectionFromKeyTuples(
+    type,
+    keyFields,
+    keyTuples,
+    resolveDatum
+) {
+    if (!keyFields || keyFields.length === 0) {
+        return;
+    }
+
+    if (type === "single" && keyTuples.length > 1) {
+        throw new Error(
+            "Single point selections expect at most one key tuple."
+        );
+    }
+
+    /** @type {import("../data/flowNode.js").Datum[]} */
+    const datums = [];
+    /** @type {import("../spec/channel.js").Scalar[][]} */
+    const unresolved = [];
+
+    for (const tuple of keyTuples) {
+        const datum = resolveDatum(keyFields, tuple);
+        if (datum) {
+            datums.push(datum);
+        } else {
+            unresolved.push(tuple);
+        }
+    }
+
+    const selection =
+        type === "single"
+            ? createSinglePointSelection(datums[0] ?? null)
+            : createMultiPointSelection(datums);
+
+    return { selection, unresolved };
+}
+
 /**
  *
  * @param {import("../spec/channel.js").ChannelWithScale[]} channels

package/dist/src/spec/channel.d.ts

@@ -46,6 +46,7 @@ export type ChannelWithoutScale =
     | "uniqueId"
     | "search"
     | "text"
+    | "key"
     | "facetIndex"
     | "semanticScore"
     | "uniqueId"
@@ -121,9 +122,13 @@ export type TypedFieldDef<T extends Type = Type> = FieldDefBase &
     TitleMixins &
     TypeMixins<T>;
 
-export type ScaleFieldDef<T extends Type> = TypedFieldDef<T> & ScaleMixins;
+export type ScaleFieldDef<T extends Type> = TypedFieldDef<T> &
+    ScaleMixins &
+    DomainContributionMixins;
 
 export type FieldDefWithoutScale = FieldDefBase & TitleMixins;
+export type KeyDef = FieldDefWithoutScale | FieldDefWithoutScale[];
+export type SearchDef = FieldDefWithoutScale | FieldDefWithoutScale[];
 
 export interface ScaleMixins {
     /**
@@ -145,15 +150,18 @@ export interface ScaleMixins {
      * @internal
      */
     resolutionChannel?: ChannelWithScale;
+}
 
+export interface DomainContributionMixins {
     /**
-     * Whether the field or evaluated expr should be included in the scale's domain.
+     * Whether the field or evaluated expr should be excluded from the scale's domain.
+     * Prefer the view-level `domainInert` when an entire subtree should be excluded.
      *
-     * **Default value:** `true`
+     * **Default value:** `false`
      *
      * @internal
      */
-    contributesToScaleDomain?: boolean;
+    domainInert?: boolean;
 }
 
 export interface ValueDefBase<V extends Value = Scalar> {
@@ -190,6 +198,7 @@ export type MarkPropFieldDef<T extends Type = Type> = ScaleFieldDef<T> &
 export type MarkPropExprDef<T extends Type = Type> = ExprDef &
     TypeMixins<T> &
     ScaleMixins &
+    DomainContributionMixins &
     TitleMixins;
 
 export type MarkPropDatumDef<T extends Type> = LegendMixins &
@@ -279,16 +288,18 @@ export type MarkPropFieldOrDatumOrExprDef<T extends Type = Type> =
 
 export type MarkPropDef<V extends Value, T extends Type = Type> =
     | FieldOrDatumDefWithCondition<MarkPropFieldDef<T>, V>
-    | FieldOrDatumDefWithCondition<DatumDef, V>
+    | FieldOrDatumDefWithCondition<ScaleDatumDef, V>
     | ValueDefWithCondition<V>;
 
 export type ColorDef = MarkPropDef<string | null>;
 
-export type SecondaryFieldDef = FieldDefBase & TitleMixins;
+export type SecondaryFieldDef = FieldDefBase &
+    TitleMixins &
+    DomainContributionMixins;
 
 export type NumericValueDef = ValueDef<number>;
 
-export type ScaleDatumDef = ScaleMixins & DatumDef;
+export type ScaleDatumDef = ScaleMixins & DatumDef & DomainContributionMixins;
 
 export type PositionDatumDefBase = ScaleDatumDef & TypeMixins<Type>;
 
@@ -299,7 +310,8 @@ export type PositionDatumDef = PositionDatumDefBase & PositionMixins;
 export type PositionExprDef = ExprDef &
     PositionMixins &
     BandMixins &
-    TypeMixins<Type>;
+    TypeMixins<Type> &
+    DomainContributionMixins;
 
 export type PositionValueDef = NumericValueDef;
 
@@ -344,7 +356,8 @@ export interface ChromPosDefBase extends BandMixins {
 
 export type SecondaryChromPosDef = ChromPosDefBase &
     TitleMixins &
-    PositionMixins;
+    PositionMixins &
+    DomainContributionMixins;
 
 export type ChromPosDef = SecondaryChromPosDef &
     TypeMixins<"locus"> &
@@ -360,8 +373,8 @@ export type PositionDef =
 export type Position2Def =
     | (SecondaryFieldDef & BandMixins)
     | SecondaryChromPosDef
-    | (DatumDef & BandMixins)
-    | (ExprDef & BandMixins)
+    | (ScaleDatumDef & BandMixins)
+    | (ExprDef & BandMixins & DomainContributionMixins)
     | PositionValueDef;
 
 export type NumericMarkPropDef = MarkPropDef<number>;
@@ -372,10 +385,15 @@ export interface StringFieldDef extends FieldDefWithoutScale, FormatMixins {}
 
 export type TextDef = StringFieldDef | StringDatumDef | ExprDef; // TODO: Conditions
 
-export type ChannelDef = Encoding[keyof Encoding];
+export type ChannelDef = Exclude<
+    Encoding[keyof Encoding],
+    FieldDefWithoutScale[]
+>;
 
 // TODO: Does this make sense?
-export type ChannelDefWithScale = ScaleMixins & TypeMixins<Type>;
+export type ChannelDefWithScale = ScaleMixins &
+    TypeMixins<Type> &
+    DomainContributionMixins;
 
 export interface XIndexDef {
     /**
@@ -497,14 +515,33 @@ export interface Encoding {
      */
     sample?: FieldDefWithoutScale;
 
+    /**
+     * One or more data fields that uniquely identify data objects for stable
+     * point selections and bookmarking across sessions. Unlike `uniqueId` (an
+     * implicit surrogate key), key fields must be stable in the source data.
+     *
+     * Use a single field definition for simple keys, or an array of field
+     * definitions for composite keys. For composite keys, field order is
+     * significant.
+     */
+    key?: KeyDef;
+
     /**
      * For internal use
+     * @internal
      */
     // TODO: proper type
     uniqueId?: FieldDefWithoutScale;
 
-    // TODO: proper type
-    search?: FieldDefWithoutScale;
+    /**
+     * One or more fields used by the App's location/search input to match
+     * data objects in this view.
+     *
+     * Use a single field definition for simple search, or an array for
+     * matching against multiple fields. A datum matches when any configured
+     * search field matches the entered term.
+     */
+    search?: SearchDef;
 
     /**
      * For internal use

package/dist/src/spec/data.d.ts

@@ -414,3 +414,7 @@ export interface Gff3Data extends TabixData {
 export interface VcfData extends TabixData {
     type: "vcf";
 }
+
+/**
+ * Testing-only lazy data source. Not intended for production use.
+ */