@genome-spy/core 0.67.0 → 0.68.0

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

@@ -19,6 +19,19 @@ export default class Collector extends FlowNode {
      * @returns {() => void}
      */
     observe(listener: (arg0: Collector) => void): () => void;
+    /**
+     * @param {string} domainKey
+     * @param {import("../spec/channel.js").Type} type
+     * @param {import("../types/encoder.js").Accessor} accessor
+     * @returns {import("../utils/domainArray.js").DomainArray}
+     */
+    getDomain(domainKey: string, type: import("../spec/channel.js").Type, accessor: import("../types/encoder.js").Accessor): import("../utils/domainArray.js").DomainArray;
+    /**
+     * @param {string} domainKey
+     * @param {() => void} listener
+     * @returns {() => void}
+     */
+    subscribeDomainChanges(domainKey: string, listener: () => void): () => void;
     /**
      * @returns {Iterable<Datum>}
      */
@@ -38,6 +51,13 @@ export default class Collector extends FlowNode {
      * @param {number} uniqueId
      */
     findDatumByUniqueId(uniqueId: number): import("./flowNode.js").Datum;
+    /**
+     * Uses a lazy index to find a datum by its key fields.
+     *
+     * @param {string[]} keyFields
+     * @param {import("../spec/channel.js").Scalar[]} keyTuple
+     */
+    findDatumByKey(keyFields: string[], keyTuple: import("../spec/channel.js").Scalar[]): import("./flowNode.js").Datum;
     #private;
 }
 import FlowNode from "./flowNode.js";

package/dist/src/data/collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../../src/data/collector.js"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH;IAuCI;;OAEG;IACH,qBAFW,OAAO,sBAAsB,EAAE,aAAa,EAiBtD;IAZG,qDAA2C;IAE3C,4CAA4C;IAC5C,WADW,GAAG,CAAC,CAAS,IAAS,EAAT,SAAS,KAAE,IAAI,CAAC,CACd;IAG1B,yFAAyF;IACzF,cADW,GAAG,CAAC,OAAO,oBAAoB,EAAE,MAAM,EAAE,+BAAO,CACN;IAmFzD;;;OAGG;IACH,kBAHW,CAAS,IAAS,EAAT,SAAS,KAAE,IAAI,GACtB,MAAM,IAAI,CAOtB;IA+BD;;OAEG;IACH,WAFa,QAAQ,+BAAO,CAqB3B;IAED;;;OAGG;IACH,mBAFW,CAAC,KAAK,+BAAO,KAAK,IAAI,QAUhC;IAED;;OAEG;IACH,uBAMC;IA8CD;;;;OAIG;IACH,8BAFW,MAAM,iCA4BhB;;CACJ;qBAxTyD,eAAe"}
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../../src/data/collector.js"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH;IA6CI;;OAEG;IACH,qBAFW,OAAO,sBAAsB,EAAE,aAAa,EAiBtD;IAZG,qDAA2C;IAE3C,4CAA4C;IAC5C,WADW,GAAG,CAAC,CAAS,IAAS,EAAT,SAAS,KAAE,IAAI,CAAC,CACd;IAG1B,yFAAyF;IACzF,cADW,GAAG,CAAC,OAAO,oBAAoB,EAAE,MAAM,EAAE,+BAAO,CACN;IAwFzD;;;OAGG;IACH,kBAHW,CAAS,IAAS,EAAT,SAAS,KAAE,IAAI,GACtB,MAAM,IAAI,CAOtB;IAiCD;;;;;OAKG;IACH,qBALW,MAAM,QACN,OAAO,oBAAoB,EAAE,IAAI,YACjC,OAAO,qBAAqB,EAAE,QAAQ,GACpC,OAAO,yBAAyB,EAAE,WAAW,CAkBzD;IAED;;;;OAIG;IACH,kCAJW,MAAM,YACN,MAAM,IAAI,GACR,MAAM,IAAI,CAItB;IAED;;OAEG;IACH,WAFa,QAAQ,+BAAO,CAqB3B;IAED;;;OAGG;IACH,mBAFW,CAAC,KAAK,+BAAO,KAAK,IAAI,QAUhC;IAED;;OAEG;IACH,uBAMC;IAqDD;;;;OAIG;IACH,8BAFW,MAAM,iCA4BhB;IAED;;;;;OAKG;IACH,0BAHW,MAAM,EAAE,YACR,OAAO,oBAAoB,EAAE,MAAM,EAAE,iCAS/C;;CACJ;qBA9XyD,eAAe"}

package/dist/src/data/collector.js

@@ -7,6 +7,8 @@ import { field } from "../utils/field.js";
 import { asArray } from "../utils/arrayUtils.js";
 import { radixSortIntoLookupArray } from "../utils/radixSort.js";
 import { UNIQUE_ID_KEY } from "./transforms/identifier.js";
+import createDomain from "../utils/domainArray.js";
+import KeyIndex from "./keyIndex.js";
 
 /**
  * Collects (materializes) the data that flows through this node.
@@ -33,6 +35,9 @@ export default class Collector extends FlowNode {
      */
     #uniqueIdIndex = [];
 
+    /** @type {KeyIndex} */
+    #keyIndex = new KeyIndex();
+
     /**
      * Start and end indices of all facets if they are concatenated into a single array.
      * Used together with the uniqueIdIndex for looking up data items by their unique id.
@@ -45,6 +50,9 @@ export default class Collector extends FlowNode {
      */
     #comparator;
 
+    /** @type {DomainCache} */
+    #domainCache = new DomainCache();
+
     get behavior() {
         return BEHAVIOR_COLLECTS;
     }
@@ -76,6 +84,7 @@ export default class Collector extends FlowNode {
     #init() {
         this.#buffer = [];
         this.#uniqueIdIndex = [];
+        this.#keyIndex.invalidate();
 
         this.facetBatches.clear();
         this.facetBatches.set(undefined, this.#buffer);
@@ -97,6 +106,8 @@ export default class Collector extends FlowNode {
      * @param {import("../types/flowBatch.js").FlowBatch} flowBatch
      */
     beginBatch(flowBatch) {
+        this.#keyIndex.invalidate();
+
         if (isFacetBatch(flowBatch)) {
             this.#buffer = [];
             this.facetBatches.set(asArray(flowBatch.facetId), this.#buffer);
@@ -144,6 +155,8 @@ export default class Collector extends FlowNode {
 
         super.complete();
 
+        this.#invalidateDomains();
+
         for (const observer of this.observers) {
             observer(this);
         }
@@ -187,6 +200,41 @@ export default class Collector extends FlowNode {
         for (const child of this.children) {
             child.complete();
         }
+
+        this.#invalidateDomains();
+    }
+
+    /**
+     * @param {string} domainKey
+     * @param {import("../spec/channel.js").Type} type
+     * @param {import("../types/encoder.js").Accessor} accessor
+     * @returns {import("../utils/domainArray.js").DomainArray}
+     */
+    getDomain(domainKey, type, accessor) {
+        return this.#domainCache.getDomain(domainKey, () => {
+            const domain = createDomain(type);
+
+            if (accessor.constant) {
+                domain.extend(accessor({}));
+            } else if (this.completed) {
+                for (const data of this.facetBatches.values()) {
+                    for (let i = 0, n = data.length; i < n; i++) {
+                        domain.extend(accessor(data[i]));
+                    }
+                }
+            }
+
+            return domain;
+        });
+    }
+
+    /**
+     * @param {string} domainKey
+     * @param {() => void} listener
+     * @returns {() => void}
+     */
+    subscribeDomainChanges(domainKey, listener) {
+        return this.#domainCache.subscribe(domainKey, listener);
     }
 
     /**
@@ -246,6 +294,13 @@ export default class Collector extends FlowNode {
         }
     }
 
+    #invalidateDomains() {
+        if (this.#domainCache.hasCachedDomains()) {
+            this.#domainCache.clear();
+        }
+        this.#domainCache.notify();
+    }
+
     /**
      * Builds an index for looking up data items by their unique id.
      * Using a sorted index and binary search for O(log n) complexity.
@@ -314,6 +369,99 @@ export default class Collector extends FlowNode {
             }
         }
     }
+
+    /**
+     * Uses a lazy index to find a datum by its key fields.
+     *
+     * @param {string[]} keyFields
+     * @param {import("../spec/channel.js").Scalar[]} keyTuple
+     */
+    findDatumByKey(keyFields, keyTuple) {
+        this.#checkStatus();
+        return this.#keyIndex.findDatum(
+            keyFields,
+            keyTuple,
+            this.facetBatches.values()
+        );
+    }
+}
+
+/**
+ * Manages cached domains and subscriptions for invalidation.
+ */
+class DomainCache {
+    /** @type {Map<string, import("../utils/domainArray.js").DomainArray>} */
+    #cache = new Map();
+
+    /** @type {Map<string, Set<() => void>>} */
+    #observers = new Map();
+
+    hasCachedDomains() {
+        return this.#cache.size > 0;
+    }
+
+    clear() {
+        this.#cache.clear();
+    }
+
+    /**
+     * @param {string} domainKey
+     * @param {() => import("../utils/domainArray.js").DomainArray} build
+     * @returns {import("../utils/domainArray.js").DomainArray}
+     */
+    getDomain(domainKey, build) {
+        const cached = this.#cache.get(domainKey);
+        if (cached) {
+            return cached;
+        } else {
+            const domain = build();
+            this.#cache.set(domainKey, domain);
+            return domain;
+        }
+    }
+
+    /**
+     * @param {string} domainKey
+     * @param {() => void} listener
+     * @returns {() => void}
+     */
+    subscribe(domainKey, listener) {
+        let listeners = this.#observers.get(domainKey);
+        if (!listeners) {
+            listeners = new Set();
+            this.#observers.set(domainKey, listeners);
+        }
+        listeners.add(listener);
+
+        return () => {
+            const entry = this.#observers.get(domainKey);
+            if (!entry) {
+                return;
+            }
+            entry.delete(listener);
+            if (entry.size === 0) {
+                this.#observers.delete(domainKey);
+            }
+        };
+    }
+
+    notify() {
+        if (this.#observers.size === 0) {
+            return;
+        }
+
+        /** @type {Set<() => void>} */
+        const listeners = new Set();
+        for (const observers of this.#observers.values()) {
+            for (const observer of observers) {
+                listeners.add(observer);
+            }
+        }
+
+        for (const listener of listeners) {
+            listener();
+        }
+    }
 }
 
 /**

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

@@ -2,6 +2,12 @@
  * DataFlow holds data sources and collectors for optimization and initialization.
  */
 export default class DataFlow {
+    /**
+     * Registry for per-view loading status. The host may replace this.
+     *
+     * @type {import("../genomeSpy/loadingStatusRegistry.js").default}
+     */
+    loadingStatusRegistry: import("../genomeSpy/loadingStatusRegistry.js").default;
     get dataSources(): DataSource[];
     get collectors(): import("./collector.js").default[];
     /**

package/dist/src/data/dataFlow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataFlow.d.ts","sourceRoot":"","sources":["../../../src/data/dataFlow.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;IAeI,gCAEC;IAED,qDAEC;IAED;;OAEG;IACH,gCAFW,QAAQ,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,QAI7D;IAED;;OAEG;IACH,0BAFW,OAAO,yBAAyB,EAAE,OAAO,QAInD;IAED;;OAEG;IACH,6BAFW,OAAO,yBAAyB,EAAE,OAAO,QAInD;IAED;;OAEG;IACH,wBAFW,OAAO,gBAAgB,EAAE,OAAO,QAI1C;IAED;;OAEG;IACH,2BAFW,OAAO,gBAAgB,EAAE,OAAO,QAK1C;IAED;;;;OAIG;IACH,gCAFW,OAAO,gBAAgB,EAAE,OAAO,QAiB1C;IAED;;OAEG;IACH,0BAFW,MAAM;;MA2BhB;;CAGJ;uBAtHsB,yBAAyB;wBACxB,0BAA0B"}
+{"version":3,"file":"dataFlow.d.ts","sourceRoot":"","sources":["../../../src/data/dataFlow.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IAOI;;;;OAIG;IACH,uBAFU,OAAO,uCAAuC,EAAE,OAAO,CAE3C;IAYtB,gCAEC;IAED,qDAEC;IAED;;OAEG;IACH,gCAFW,QAAQ,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,QAI7D;IAED;;OAEG;IACH,0BAFW,OAAO,yBAAyB,EAAE,OAAO,QAInD;IAED;;OAEG;IACH,6BAFW,OAAO,yBAAyB,EAAE,OAAO,QAInD;IAED;;OAEG;IACH,wBAFW,OAAO,gBAAgB,EAAE,OAAO,QAI1C;IAED;;OAEG;IACH,2BAFW,OAAO,gBAAgB,EAAE,OAAO,QAK1C;IAED;;;;OAIG;IACH,gCAFW,OAAO,gBAAgB,EAAE,OAAO,QAiB1C;IAED;;OAEG;IACH,0BAFW,MAAM;;MA2BhB;;CAGJ;uBA/HsB,yBAAyB;wBACxB,0BAA0B"}

package/dist/src/data/dataFlow.js

@@ -1,3 +1,4 @@
+import LoadingStatusRegistry from "../genomeSpy/loadingStatusRegistry.js";
 import DataSource from "./sources/dataSource.js";
 import NamedSource from "./sources/namedSource.js";
 
@@ -11,12 +12,21 @@ export default class DataFlow {
     /** @type {Set<import("./collector.js").default>} */
     #collectors;
 
+    /**
+     * Registry for per-view loading status. The host may replace this.
+     *
+     * @type {import("../genomeSpy/loadingStatusRegistry.js").default}
+     */
+    loadingStatusRegistry;
+
     constructor() {
         /** @type {Set<import("./sources/dataSource.js").default>} */
         this.#dataSources = new Set();
 
         /** @type {Set<import("./collector.js").default>} */
         this.#collectors = new Set();
+
+        this.loadingStatusRegistry = new LoadingStatusRegistry();
     }
 
     get dataSources() {

package/dist/src/data/flowInit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flowInit.d.ts","sourceRoot":"","sources":["../../../src/data/flowInit.js"],"names":[],"mappings":"AAyDA;;;;;GAKG;AACH,sCAHW,OAAO,iBAAiB,EAAE,OAAO,qBACjC,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,EAAE,OAAO,yBAAyB,EAAE,OAAO,CAAC,QAcnG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,mDAXW,OAAO,iBAAiB,EAAE,OAAO,QACjC,OAAO,eAAe,EAAE,OAAO,eAC/B,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,OAAO,KAAK,OAAO,gCACpD,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,OAAO,KAAK,OAAO,GAClD;IACN,QAAQ,EAAE,OAAO,eAAe,EAAE,OAAO,CAAC;IAC1C,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,WAAW,EAAE,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,CAAC;IAC5D,gBAAgB,EAAE,OAAO,CAAC,OAAO,kBAAkB,EAAE,OAAO,CAAC,EAAE,CAAA;CAClE,CA4FH;AAED;;;;;;;GAOG;AACH,2DAJW,OAAO,iBAAiB,EAAE,OAAO,GAAG,OAAO,iBAAiB,EAAE,OAAO,EAAE,eACvE,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,OAAO,KAAK,OAAO,GAClD,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,CAsB1D;AAED;;;;;;;GAOG;AACH,kEAJW,OAAO,iBAAiB,EAAE,OAAO,eACjC,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,OAAO,KAAK,OAAO,GAClD,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,CAe1D;AAED;;;;;;;;;GASG;AACH,iDANW,OAAO,iBAAiB,EAAE,OAAO,gBACjC,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,eAC9C,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,OAAO,KAAK,OAAO,gBACpD;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GACvB,OAAO,CAAC,IAAI,EAAE,CAAC,CAuB3B;qBA5SoB,qBAAqB"}
+{"version":3,"file":"flowInit.d.ts","sourceRoot":"","sources":["../../../src/data/flowInit.js"],"names":[],"mappings":"AAwDA;;;;;GAKG;AACH,sCAHW,OAAO,iBAAiB,EAAE,OAAO,qBACjC,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,EAAE,OAAO,yBAAyB,EAAE,OAAO,CAAC,QAcnG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,mDAXW,OAAO,iBAAiB,EAAE,OAAO,QACjC,OAAO,eAAe,EAAE,OAAO,eAC/B,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,OAAO,KAAK,OAAO,gCACpD,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,OAAO,KAAK,OAAO,GAClD;IACN,QAAQ,EAAE,OAAO,eAAe,EAAE,OAAO,CAAC;IAC1C,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,WAAW,EAAE,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,CAAC;IAC5D,gBAAgB,EAAE,OAAO,CAAC,OAAO,kBAAkB,EAAE,OAAO,CAAC,EAAE,CAAA;CAClE,CA6FH;AAED;;;;;;;GAOG;AACH,2DAJW,OAAO,iBAAiB,EAAE,OAAO,GAAG,OAAO,iBAAiB,EAAE,OAAO,EAAE,eACvE,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,OAAO,KAAK,OAAO,GAClD,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,CAsB1D;AAED;;;;;;;GAOG;AACH,kEAJW,OAAO,iBAAiB,EAAE,OAAO,eACjC,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,OAAO,KAAK,OAAO,GAClD,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,CAe1D;AAED;;;;;;;;;GASG;AACH,iDANW,OAAO,iBAAiB,EAAE,OAAO,gBACjC,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,eAC9C,CAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,OAAO,KAAK,OAAO,gBACpD;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GACvB,OAAO,CAAC,IAAI,EAAE,CAAC,CAsB3B;qBA3SoB,qBAAqB"}

package/dist/src/data/flowInit.js

@@ -2,7 +2,6 @@ import UnitView from "../view/unitView.js";
 import { buildDataFlow } from "../view/flowBuilder.js";
 import { optimizeDataFlow } from "./flowOptimizer.js";
 import { VISIT_SKIP } from "../view/view.js";
-import { reconfigureScaleDomains } from "../scales/scaleResolution.js";
 
 /** @type {WeakMap<import("./sources/dataSource.js").default, Promise<void>>} */
 const inFlightLoads = new WeakMap();
@@ -163,7 +162,7 @@ export function initializeViewSubtree(
 
     // Initialize flow nodes for the sources that belong to this subtree.
     for (const dataSource of dataSources) {
-        dataSource.visit((node) => node.initialize());
+        dataSource.visit((node) => node.initializeOnce());
     }
 
     /** @type {UnitView[]} */
@@ -180,6 +179,7 @@ export function initializeViewSubtree(
         const mark = view.mark;
         // Encoders can be initialized immediately; graphics need a GL context.
         mark.initializeEncoders();
+        view.registerDomainSubscriptions();
         if (canInitializeGraphics) {
             graphicsPromises.push(mark.initializeGraphics().then(() => mark));
         }
@@ -294,7 +294,6 @@ export function loadViewSubtreeData(
             loadDataSourceOnce(dataSource, loadOptions)
         )
     ).then((results) => {
-        reconfigureScaleDomains(subtreeRoot, viewFilter);
         broadcastSubtreeDataReady(subtreeRoot);
         return results;
     });

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

@@ -69,8 +69,16 @@ export default class FlowNode {
     /**
      * Allows for doing final initialization after the flow structure has been
      * built and optimized. Must be called before any data are to be propagated.
+     * Note: Some transforms call initialize() from reset() to rebuild internal
+     * fast paths per batch. Use initializeOnce() for graph-level init to avoid
+     * double-initialization issues.
      */
     initialize(): void;
+    /**
+     * Calls initialize() once per node instance. Intended for graph-level init
+     * passes that should not rerun when reusing existing branches.
+     */
+    initializeOnce(): void;
     /**
      * @param {Datum} datum
      * @protected

package/dist/src/data/flowNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flowNode.d.ts","sourceRoot":"","sources":["../../../src/data/flowNode.js"],"names":[],"mappings":"AAuUA;;;GAGG;AACH,uCAHW,OAAO,uBAAuB,EAAE,SAAS,GACvC,SAAS,IAAI,OAAO,uBAAuB,EAAE,SAAS,CAIlE;AAED;;;GAGG;AACH,wCAHW,OAAO,uBAAuB,EAAE,SAAS,GACvC,SAAS,IAAI,OAAO,uBAAuB,EAAE,UAAU,CAInE;AAnVD;;;GAGG;AACH,qCAAsC;AAEtC;;;GAGG;AACH,uCAAwC;AAExC;;;GAGG;AACH,uCAAwC;AAExC;;GAEG;AAEH;;;;;GAKG;AACH;IA2BI;;OAEG;IACH,oCAFW,qBAAqB,EAa/B;IAxCD;;QAEI,oBAAoB;eAAT,KAAK;MAElB;IAEF;;;;OAIG;IACH,uBAFU,qBAAqB,CAEF;IAE7B,uBAEC;IAED;;;;OAIG;IACH,aAFa,MAAM,CAIlB;IAQG,yBAAyB;IACzB,UADW,QAAQ,EAAE,CACH;IAElB,uBAAuB;IACvB,QADW,QAAQ,CACI;IAEvB,2CAA2C;IAC3C,mBAAsB;IAG1B;;;OAGG;IACH,cASC;IAED;;;OAGG;IACH,mBAEC;IAgOD;;;OAGG;IACH,4BAHW,KAAK,QAKf;IA7MD;;;OAGG;IACH,kBAFW,QAAQ,QAIlB;IAED;;;OAGG;IACH,gBAFW,QAAQ,QAUlB;IAED;;OAEG;IACH,YAFW,QAAQ,QAQlB;IAED;;OAEG;IACH,6BAFW,QAAQ,QAMlB;IAED;;OAEG;IACH,0BAFW,QAAQ,QAalB;IAED;;;OAGG;IACH,mBAFW,QAAQ,QAWlB;IAED;;OAEG;IACH,eAiBC;IAED,kBAEC;IAED,uBAEC;IAED,sBAEC;IAED;;;;OAIG;IACH,eAFW,CAAC,CAAS,IAAQ,EAAR,QAAQ,KAAE,IAAI,CAAC,GAAG;QAAE,aAAa,CAAC,EAAE,CAAS,IAAQ,EAAR,QAAQ,KAAE,IAAI,CAAA;KAAC,QAchF;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,MAAM,CAWlB;IAED;;;OAGG;IACH,cAFW,KAAK,QAKf;IAED,iBAMC;IAED;;;;OAIG;IACH,sBAFW,OAAO,uBAAuB,EAAE,SAAS,QAMnD;IAED;;;OAGG;IACH,+BAHa,OAAO,0BAA0B,EAAE,OAAO,CAYtD;IAED;;;;OAIG;IACH,8BAQC;;CASJ;oCAhTY;IAAC,aAAa,EAAE,OAAO,0BAA0B,EAAE,OAAO,CAAA;CAAC;;;;oBAM3D,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;mBACnB,KAAK,EAAE"}
+{"version":3,"file":"flowNode.d.ts","sourceRoot":"","sources":["../../../src/data/flowNode.js"],"names":[],"mappings":"AAyVA;;;GAGG;AACH,uCAHW,OAAO,uBAAuB,EAAE,SAAS,GACvC,SAAS,IAAI,OAAO,uBAAuB,EAAE,SAAS,CAIlE;AAED;;;GAGG;AACH,wCAHW,OAAO,uBAAuB,EAAE,SAAS,GACvC,SAAS,IAAI,OAAO,uBAAuB,EAAE,UAAU,CAInE;AArWD;;;GAGG;AACH,qCAAsC;AAEtC;;;GAGG;AACH,uCAAwC;AAExC;;;GAGG;AACH,uCAAwC;AAExC;;GAEG;AAEH;;;;;GAKG;AACH;IA8BI;;OAEG;IACH,oCAFW,qBAAqB,EAa/B;IA3CD;;QAEI,oBAAoB;eAAT,KAAK;MAElB;IAKF;;;;OAIG;IACH,uBAFU,qBAAqB,CAEF;IAE7B,uBAEC;IAED;;;;OAIG;IACH,aAFa,MAAM,CAIlB;IAQG,yBAAyB;IACzB,UADW,QAAQ,EAAE,CACH;IAElB,uBAAuB;IACvB,QADW,QAAQ,CACI;IAEvB,2CAA2C;IAC3C,mBAAsB;IAG1B;;;OAGG;IACH,cASC;IAED;;;;;;OAMG;IACH,mBAEC;IAED;;;OAGG;IACH,uBAMC;IAgOD;;;OAGG;IACH,4BAHW,KAAK,QAKf;IA7MD;;;OAGG;IACH,kBAFW,QAAQ,QAIlB;IAED;;;OAGG;IACH,gBAFW,QAAQ,QAUlB;IAED;;OAEG;IACH,YAFW,QAAQ,QAQlB;IAED;;OAEG;IACH,6BAFW,QAAQ,QAMlB;IAED;;OAEG;IACH,0BAFW,QAAQ,QAalB;IAED;;;OAGG;IACH,mBAFW,QAAQ,QAWlB;IAED;;OAEG;IACH,eAiBC;IAED,kBAEC;IAED,uBAEC;IAED,sBAEC;IAED;;;;OAIG;IACH,eAFW,CAAC,CAAS,IAAQ,EAAR,QAAQ,KAAE,IAAI,CAAC,GAAG;QAAE,aAAa,CAAC,EAAE,CAAS,IAAQ,EAAR,QAAQ,KAAE,IAAI,CAAA;KAAC,QAchF;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,MAAM,CAWlB;IAED;;;OAGG;IACH,cAFW,KAAK,QAKf;IAED,iBAMC;IAED;;;;OAIG;IACH,sBAFW,OAAO,uBAAuB,EAAE,SAAS,QAMnD;IAED;;;OAGG;IACH,+BAHa,OAAO,0BAA0B,EAAE,OAAO,CAYtD;IAED;;;;OAIG;IACH,8BAQC;;CASJ;oCAlUY;IAAC,aAAa,EAAE,OAAO,0BAA0B,EAAE,OAAO,CAAA;CAAC;;;;oBAM3D,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;mBACnB,KAAK,EAAE"}

package/dist/src/data/flowNode.js

@@ -35,6 +35,9 @@ export default class FlowNode {
         first: null,
     };
 
+    /** @type {boolean} */
+    #initialized = false;
+
     /**
      * An object that provides a paramMediator. (Most likely a View)
      *
@@ -89,11 +92,26 @@ export default class FlowNode {
     /**
      * Allows for doing final initialization after the flow structure has been
      * built and optimized. Must be called before any data are to be propagated.
+     * Note: Some transforms call initialize() from reset() to rebuild internal
+     * fast paths per batch. Use initializeOnce() for graph-level init to avoid
+     * double-initialization issues.
      */
     initialize() {
         // override
     }
 
+    /**
+     * Calls initialize() once per node instance. Intended for graph-level init
+     * passes that should not rerun when reusing existing branches.
+     */
+    initializeOnce() {
+        if (this.#initialized) {
+            return;
+        }
+        this.initialize();
+        this.#initialized = true;
+    }
+
     /**
      * Dynamically updates the propagator method to allow the JavaScript engine
      * to employ optimizations such as inlining.

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

@@ -0,0 +1,18 @@
+/**
+ * Lazily builds and caches lookup indexes for `encoding.key` fields so that
+ * bookmarked point selections can be resolved back to datums efficiently.
+ *
+ * TODO: Use requestIdleCallback to warm up the index to prevent jank on first access.
+ */
+export default class KeyIndex {
+    invalidate(): void;
+    /**
+     * @param {string[]} keyFields
+     * @param {import("../spec/channel.js").Scalar[]} keyTuple
+     * @param {Iterable<Data>} facetBatches
+     * @returns {Datum | undefined}
+     */
+    findDatum(keyFields: string[], keyTuple: import("../spec/channel.js").Scalar[], facetBatches: Iterable<import("./flowNode.js").Data>): import("./flowNode.js").Datum | undefined;
+    #private;
+}
+//# sourceMappingURL=keyIndex.d.ts.map

package/dist/src/data/keyIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyIndex.d.ts","sourceRoot":"","sources":["../../../src/data/keyIndex.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH;IAeI,mBAIC;IAED;;;;;OAKG;IACH,qBALW,MAAM,EAAE,YACR,OAAO,oBAAoB,EAAE,MAAM,EAAE,gBACrC,QAAQ,8BAAM,GACZ,gCAAQ,SAAS,CAwC7B;;CAgGJ"}

package/dist/src/data/keyIndex.js

@@ -0,0 +1,241 @@
+import { field } from "../utils/field.js";
+
+const MULTI_KEY_SEPARATOR = "|";
+const MULTI_KEY_ESCAPE = "\\";
+
+/**
+ * Lazily builds and caches lookup indexes for `encoding.key` fields so that
+ * bookmarked point selections can be resolved back to datums efficiently.
+ *
+ * TODO: Use requestIdleCallback to warm up the index to prevent jank on first access.
+ */
+export default class KeyIndex {
+    /**
+     * @typedef {import("./flowNode.js").Datum} Datum
+     * @typedef {import("./flowNode.js").Data} Data
+     */
+
+    /** @type {Map<import("../spec/channel.js").Scalar | string, Datum> | null} */
+    #index = null;
+
+    /** @type {string[] | null} */
+    #keyFields = null;
+
+    /** @type {boolean} */
+    #usesCompositeKey = false;
+
+    invalidate() {
+        this.#index = null;
+        this.#keyFields = null;
+        this.#usesCompositeKey = false;
+    }
+
+    /**
+     * @param {string[]} keyFields
+     * @param {import("../spec/channel.js").Scalar[]} keyTuple
+     * @param {Iterable<Data>} facetBatches
+     * @returns {Datum | undefined}
+     */
+    findDatum(keyFields, keyTuple, facetBatches) {
+        if (!keyFields || keyFields.length === 0) {
+            return;
+        }
+
+        const fieldList = keyFields.join(", ");
+        if (keyFields.length !== keyTuple.length) {
+            throw new Error(
+                `Key tuple length ${keyTuple.length} does not match fields [${fieldList}]`
+            );
+        }
+
+        if (!this.#index || !this.#matchesKeyFields(keyFields)) {
+            this.#buildIndex(keyFields, facetBatches);
+        }
+
+        const canonicalFields = /** @type {string[]} */ (this.#keyFields);
+        /** @type {import("../spec/channel.js").Scalar | string} */
+        let key;
+        if (!this.#usesCompositeKey) {
+            const fieldName = canonicalFields[0];
+            key = validateKeyComponent(keyTuple[0], fieldName);
+        } else {
+            let compositeKey = "";
+            for (let i = 0; i < keyTuple.length; i++) {
+                if (i > 0) {
+                    compositeKey += MULTI_KEY_SEPARATOR;
+                }
+
+                const fieldName = canonicalFields[i];
+                const value = validateKeyComponent(keyTuple[i], fieldName);
+
+                compositeKey += encodeKeyPart(value);
+            }
+            key = compositeKey;
+        }
+
+        return this.#index.get(key);
+    }
+
+    /**
+     * @param {string[]} keyFields
+     * @param {Iterable<Data>} facetBatches
+     */
+    #buildIndex(keyFields, facetBatches) {
+        /** @type {Array<(datum: Datum) => import("../spec/channel.js").Scalar>} */
+        const accessors = keyFields.map((fieldName) => field(fieldName));
+        /** @type {Map<import("../spec/channel.js").Scalar | string, Datum>} */
+        const index = new Map();
+        const fieldList = keyFields.join(", ");
+
+        const usesCompositeKey = keyFields.length !== 1;
+
+        if (!usesCompositeKey) {
+            const accessor = accessors[0];
+            const fieldName = keyFields[0];
+            for (const data of facetBatches) {
+                for (let i = 0, n = data.length; i < n; i++) {
+                    const datum = data[i];
+                    const key = validateKeyComponent(
+                        accessor(datum),
+                        fieldName
+                    );
+
+                    const previous = index.get(key);
+                    if (previous !== undefined) {
+                        throw new Error(
+                            `Duplicate key detected for fields [${fieldList}]: ${JSON.stringify(key)}`
+                        );
+                    }
+
+                    index.set(key, datum);
+                }
+            }
+        } else {
+            for (const data of facetBatches) {
+                for (let i = 0, n = data.length; i < n; i++) {
+                    const datum = data[i];
+                    let compositeKey = "";
+                    for (let j = 0; j < accessors.length; j++) {
+                        if (j > 0) {
+                            compositeKey += MULTI_KEY_SEPARATOR;
+                        }
+
+                        const fieldName = keyFields[j];
+                        const value = validateKeyComponent(
+                            accessors[j](datum),
+                            fieldName
+                        );
+
+                        compositeKey += encodeKeyPart(value);
+                    }
+
+                    const previous = index.get(compositeKey);
+                    if (previous !== undefined) {
+                        const duplicateTuple = accessors.map((accessor) =>
+                            accessor(datum)
+                        );
+                        throw new Error(
+                            `Duplicate key detected for fields [${fieldList}]: ${JSON.stringify(duplicateTuple)}`
+                        );
+                    }
+
+                    index.set(compositeKey, datum);
+                }
+            }
+        }
+
+        this.#index = index;
+        this.#keyFields = [...keyFields];
+        this.#usesCompositeKey = usesCompositeKey;
+    }
+
+    /**
+     * @param {string[]} keyFields
+     * @returns {boolean}
+     */
+    #matchesKeyFields(keyFields) {
+        if (!this.#keyFields) {
+            return false;
+        }
+
+        if (this.#keyFields.length !== keyFields.length) {
+            return false;
+        }
+
+        for (let i = 0; i < keyFields.length; i++) {
+            if (this.#keyFields[i] !== keyFields[i]) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} fieldName
+ * @returns {import("../spec/channel.js").Scalar}
+ */
+function validateKeyComponent(value, fieldName) {
+    if (value === undefined) {
+        throw new Error(
+            `Key field "${fieldName}" is undefined. Ensure all key fields are present in the data.`
+        );
+    }
+
+    if (value === null) {
+        throw new Error(
+            `Key field "${fieldName}" is null. Ensure all key fields are present in the data.`
+        );
+    }
+
+    if (
+        typeof value !== "string" &&
+        typeof value !== "number" &&
+        typeof value !== "boolean"
+    ) {
+        throw new Error(
+            `Key field "${fieldName}" must be a scalar value (string, number, or boolean).`
+        );
+    }
+
+    return value;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeKeyString(value) {
+    const needsEscaping =
+        value.indexOf(MULTI_KEY_ESCAPE) !== -1 ||
+        value.indexOf(MULTI_KEY_SEPARATOR) !== -1;
+
+    if (!needsEscaping) {
+        return value;
+    }
+
+    let escaped = "";
+    for (let i = 0; i < value.length; i++) {
+        const char = value[i];
+        if (char === MULTI_KEY_ESCAPE || char === MULTI_KEY_SEPARATOR) {
+            escaped += MULTI_KEY_ESCAPE;
+        }
+        escaped += char;
+    }
+
+    return escaped;
+}
+
+/**
+ * @param {import("../spec/channel.js").Scalar} scalar
+ * @returns {string}
+ */
+function encodeKeyPart(scalar) {
+    if (typeof scalar === "string") {
+        return escapeKeyString(scalar);
+    }
+
+    return String(scalar);
+}

package/dist/src/data/keyIndex.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=keyIndex.test.d.ts.map

package/dist/src/data/keyIndex.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyIndex.test.d.ts","sourceRoot":"","sources":["../../../src/data/keyIndex.test.js"],"names":[],"mappings":""}

package/dist/src/data/sources/dataSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataSource.d.ts","sourceRoot":"","sources":["../../../../src/data/sources/dataSource.js"],"names":[],"mappings":"AAEA;IAMI;;OAEG;IACH,kBAFW,OAAO,oBAAoB,EAAE,OAAO,EAM9C;IAZD;;OAEG;IACH,MAFU,OAAO,oBAAoB,EAAE,OAAO,CAEzC;IAWL;;;;;OAKG;IACH,kBAFY,MAAM,CAIjB;IAED;;;;;;OAMG;IACH,mCAJW,OAAO,4BAA4B,EAAE,iBAAiB,WACtD,MAAM,QAKhB;IAcD,sBAEC;CAKJ;qBAzDoB,gBAAgB"}
+{"version":3,"file":"dataSource.d.ts","sourceRoot":"","sources":["../../../../src/data/sources/dataSource.js"],"names":[],"mappings":"AAEA;IAMI;;OAEG;IACH,kBAFW,OAAO,oBAAoB,EAAE,OAAO,EAM9C;IAZD;;OAEG;IACH,MAFU,OAAO,oBAAoB,EAAE,OAAO,CAEzC;IAWL;;;;;OAKG;IACH,kBAFY,MAAM,CAIjB;IAED;;;;;;OAMG;IACH,mCAJW,OAAO,4BAA4B,EAAE,iBAAiB,WACtD,MAAM,QAShB;IAcD,sBAEC;CAKJ;qBA7DoB,gBAAgB"}