@genome-spy/core 0.64.0 → 0.66.1

package/dist/schema.json

@@ -2353,7 +2353,9 @@
       "type": "object"
     },
     "FieldOrDatumDefWithCondition<MarkPropFieldDef<Type>,(string|null)>": {
-      "additionalProperties": false,
+      "additionalProperties": {
+        "not": {}
+      },
       "description": "A FieldDef with Condition<ValueDef> {   condition: {value: ...},   field: ...,   ... }",
       "properties": {
         "condition": {
@@ -2410,7 +2412,9 @@
       "type": "object"
     },
     "FieldOrDatumDefWithCondition<MarkPropFieldDef<Type>,number>": {
-      "additionalProperties": false,
+      "additionalProperties": {
+        "not": {}
+      },
       "description": "A FieldDef with Condition<ValueDef> {   condition: {value: ...},   field: ...,   ... }",
       "properties": {
         "condition": {
@@ -2467,7 +2471,9 @@
       "type": "object"
     },
     "FieldOrDatumDefWithCondition<MarkPropFieldDef<TypeForShape>,(string|null)>": {
-      "additionalProperties": false,
+      "additionalProperties": {
+        "not": {}
+      },
       "description": "A FieldDef with Condition<ValueDef> {   condition: {value: ...},   field: ...,   ... }",
       "properties": {
         "condition": {
@@ -8183,7 +8189,7 @@
           "type": "string"
         },
         "type": {
-          "$ref": "#/definitions/Type",
+          "$ref": "#/definitions/SampleAttributeType",
           "description": "The attribute type. One of `\"nominal\"`, `\"ordinal\"`, or `\"quantitative\"`."
         },
         "visible": {
@@ -8197,6 +8203,14 @@
       },
       "type": "object"
     },
+    "SampleAttributeType": {
+      "enum": [
+        "nominal",
+        "ordinal",
+        "quantitative"
+      ],
+      "type": "string"
+    },
     "SampleDef": {
       "additionalProperties": false,
       "properties": {
@@ -8659,6 +8673,10 @@
           "description": "The alignment of the steps within the scale range.\n\nThis value must lie in the range `[0,1]`. A value of `0.5` indicates that the steps should be centered within the range. A value of `0` or `1` may be used to shift the bands to one side, say to position them adjacent to an axis.\n\n__Default value:__ `0.5`",
           "type": "number"
         },
+        "assembly": {
+          "description": "The genome assembly name for locus scales. If undefined, the default genome from the genome store is used.",
+          "type": "string"
+        },
         "base": {
           "description": "The logarithm base of the `log` scale (default `10`).",
           "type": "number"

package/dist/src/config/scaleDefaults.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @param {import("../spec/channel.js").Channel} channel
+ * @param {import("../spec/channel.js").Type} dataType
+ * @param {boolean} isExplicitDomain
+ * @returns {import("../spec/scale.js").Scale}
+ */
+export function getDefaultScaleProperties(channel: import("../spec/channel.js").Channel, dataType: import("../spec/channel.js").Type, isExplicitDomain: boolean): import("../spec/scale.js").Scale;
+//# sourceMappingURL=scaleDefaults.d.ts.map

package/dist/src/config/scaleDefaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaleDefaults.d.ts","sourceRoot":"","sources":["../../../src/config/scaleDefaults.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,mDALW,OAAO,oBAAoB,EAAE,OAAO,YACpC,OAAO,oBAAoB,EAAE,IAAI,oBACjC,OAAO,GACL,OAAO,kBAAkB,EAAE,KAAK,CAiC5C"}

package/dist/src/config/scaleDefaults.js

@@ -0,0 +1,45 @@
+import {
+    isColorChannel,
+    isDiscreteChannel,
+    isPositionalChannel,
+} from "../encoder/encoder.js";
+import { NOMINAL, ORDINAL } from "../scales/scaleResolutionConstants.js";
+
+/**
+ * @param {import("../spec/channel.js").Channel} channel
+ * @param {import("../spec/channel.js").Type} dataType
+ * @param {boolean} isExplicitDomain
+ * @returns {import("../spec/scale.js").Scale}
+ */
+export function getDefaultScaleProperties(channel, dataType, isExplicitDomain) {
+    /** @type {import("../spec/scale.js").Scale} */
+    const props = {};
+
+    if (isExplicitDomain) {
+        props.zero = false;
+    }
+
+    if (isPositionalChannel(channel)) {
+        props.nice = !isExplicitDomain;
+    } else if (isColorChannel(channel)) {
+        // TODO: Named ranges
+        props.scheme =
+            dataType == NOMINAL
+                ? "tableau10"
+                : dataType == ORDINAL
+                  ? "blues"
+                  : "viridis";
+    } else if (isDiscreteChannel(channel)) {
+        // Shapes of point mark, for example
+        props.range =
+            channel == "shape"
+                ? ["circle", "square", "triangle-up", "cross", "diamond"]
+                : [];
+    } else if (channel == "size") {
+        props.range = [0, 400]; // TODO: Configurable default. This is currently optimized for points.
+    } else if (channel == "angle") {
+        props.range = [0, 360];
+    }
+
+    return props;
+}

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

@@ -10,10 +10,15 @@ export default class Collector extends FlowNode {
      */
     constructor(params?: import("../spec/transform.js").CollectParams);
     params: import("../spec/transform.js").CollectParams;
-    /** @type {(function(Collector):void)[]} */
-    observers: ((arg0: Collector) => void)[];
+    /** @type {Set<function(Collector):void>} */
+    observers: Set<(arg0: Collector) => void>;
     /** @type {Map<import("../spec/channel.js").Scalar[], Data>} TODO: proper type for key */
     facetBatches: Map<import("../spec/channel.js").Scalar[], import("./flowNode.js").Data>;
+    /**
+     * @param {function(Collector):void} listener
+     * @returns {() => void}
+     */
+    observe(listener: (arg0: Collector) => void): () => void;
     /**
      * @returns {Iterable<Datum>}
      */

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,2CAA2C;IAC3C,WADW,CAAC,CAAS,IAAS,EAAT,SAAS,KAAE,IAAI,CAAC,EAAE,CACpB;IAGnB,yFAAyF;IACzF,cADW,GAAG,CAAC,OAAO,oBAAoB,EAAE,MAAM,EAAE,+BAAO,CACN;IAgHzD;;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;qBA7SyD,eAAe"}
+{"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"}

package/dist/src/data/collector.js

@@ -61,8 +61,8 @@ export default class Collector extends FlowNode {
 
         this.params = params ?? { type: "collect" };
 
-        /** @type {(function(Collector):void)[]} */
-        this.observers = [];
+        /** @type {Set<function(Collector):void>} */
+        this.observers = new Set();
 
         // TODO: Consider nested maps instead of InternMap
         /** @type {Map<import("../spec/channel.js").Scalar[], Data>} TODO: proper type for key */
@@ -149,6 +149,17 @@ export default class Collector extends FlowNode {
         }
     }
 
+    /**
+     * @param {function(Collector):void} listener
+     * @returns {() => void}
+     */
+    observe(listener) {
+        this.observers.add(listener);
+        return () => {
+            this.observers.delete(listener);
+        };
+    }
+
     #propagateToChildren() {
         if (this.children.length) {
             for (const [facetId, data] of this.facetBatches.entries()) {

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

@@ -1,65 +1,43 @@
 /**
- * @template H A key (string, object, whatever) that is used to retrieve
- *      data sources and collectors.
+ * DataFlow holds data sources and collectors for optimization and initialization.
  */
-export default class DataFlow<H> {
-    /** @type {Map<H, import("./sources/dataSource.js").default>} */
-    _dataSourcesByHost: Map<H, import("./sources/dataSource.js").default>;
-    /** @type {Map<H, import("./collector.js").default>} */
-    _collectorsByHost: Map<H, import("./collector.js").default>;
-    /** @type {Map<H, (function(import("./collector.js").default):void)[]>} */
-    _observers: Map<H, ((arg0: import("./collector.js").default) => void)[]>;
-    get dataSources(): import("./sources/dataSource.js").default[];
+export default class DataFlow {
+    get dataSources(): DataSource[];
     get collectors(): import("./collector.js").default[];
     /**
-     * Adds a callback function that will be called when a collector has completed.
-     *
-     * @param {function(import("./collector.js").default):void} callback
-     * @param {H} key
-     */
-    addObserver(callback: (arg0: import("./collector.js").default) => void, key: H): void;
-    /**
-     *
-     * @param {import("./collector.js").default} collector
-     * @param {H} key
+     * @param {Iterable<import("./sources/dataSource.js").default>} dataSources
      */
-    _relayObserverCallback(collector: import("./collector.js").default, key: H): void;
+    replaceDataSources(dataSources: Iterable<import("./sources/dataSource.js").default>): void;
     /**
-     *
      * @param {import("./sources/dataSource.js").default} dataSource
-     * @param {H} key
      */
-    addDataSource(dataSource: import("./sources/dataSource.js").default, key: H): void;
+    addDataSource(dataSource: import("./sources/dataSource.js").default): void;
     /**
-     *
-     * @param {H} key
+     * @param {import("./sources/dataSource.js").default} dataSource
      */
-    findDataSourceByKey(key: H): import("./sources/dataSource.js").default;
+    removeDataSource(dataSource: import("./sources/dataSource.js").default): void;
     /**
-     *
-     * @param {string} name
+     * @param {import("./collector.js").default} collector
      */
-    findNamedDataSource(name: string): {
-        dataSource: NamedSource;
-        hosts: H[];
-    };
+    addCollector(collector: import("./collector.js").default): void;
     /**
-     *
      * @param {import("./collector.js").default} collector
-     * @param {H} key
      */
-    addCollector(collector: import("./collector.js").default, key: H): void;
+    removeCollector(collector: import("./collector.js").default): void;
     /**
+     * Prune a collector branch from the flow graph, removing empty ancestors.
      *
-     * @param {H} key
+     * @param {import("./collector.js").default} collector
      */
-    findCollectorByKey(key: H): import("./collector.js").default;
+    pruneCollectorBranch(collector: import("./collector.js").default): void;
     /**
-     * Allows the flow nodes to perform final initialization after the flow
-     * structure has been built and optimized.
-     * Must be called before any data are to be propagated.
+     * @param {string} name
      */
-    initialize(): void;
+    findNamedDataSource(name: string): {
+        dataSource: NamedSource;
+    };
+    #private;
 }
+import DataSource from "./sources/dataSource.js";
 import NamedSource from "./sources/namedSource.js";
 //# sourceMappingURL=dataFlow.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dataFlow.d.ts","sourceRoot":"","sources":["../../../src/data/dataFlow.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,8BAHa,CAAC;IAKN,gEAAgE;IAChE,oBADW,GAAG,CAAC,CAAC,EAAE,OAAO,yBAAyB,EAAE,OAAO,CAAC,CACzB;IAEnC,uDAAuD;IACvD,mBADW,GAAG,CAAC,CAAC,EAAE,OAAO,gBAAgB,EAAE,OAAO,CAAC,CACjB;IAElC,0EAA0E;IAC1E,YADW,GAAG,CAAC,CAAC,EAAE,CAAC,CAAS,IAAgC,EAAhC,OAAO,gBAAgB,EAAE,OAAO,KAAE,IAAI,CAAC,EAAE,CAAC,CAC3C;IAG/B,+DAEC;IAED,qDAEC;IAED;;;;;OAKG;IACH,sBAHW,CAAS,IAAgC,EAAhC,OAAO,gBAAgB,EAAE,OAAO,KAAE,IAAI,OAC/C,CAAC,QAUX;IAED;;;;OAIG;IACH,kCAHW,OAAO,gBAAgB,EAAE,OAAO,OAChC,CAAC,QAUX;IAED;;;;OAIG;IACH,0BAHW,OAAO,yBAAyB,EAAE,OAAO,OACzC,CAAC,QAIX;IAED;;;OAGG;IACH,yBAFW,CAAC,6CAIX;IAED;;;OAGG;IACH,0BAFW,MAAM;;;MAiChB;IAED;;;;OAIG;IACH,wBAHW,OAAO,gBAAgB,EAAE,OAAO,OAChC,CAAC,QAOX;IAED;;;OAGG;IACH,wBAFW,CAAC,oCAIX;IAED;;;;OAIG;IACH,mBAIC;CACJ;wBA7IuB,0BAA0B"}
+{"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"}

package/dist/src/data/dataFlow.js

@@ -1,92 +1,100 @@
+import DataSource from "./sources/dataSource.js";
 import NamedSource from "./sources/namedSource.js";
 
 /**
- * @template H A key (string, object, whatever) that is used to retrieve
- *      data sources and collectors.
+ * DataFlow holds data sources and collectors for optimization and initialization.
  */
 export default class DataFlow {
-    constructor() {
-        /** @type {Map<H, import("./sources/dataSource.js").default>} */
-        this._dataSourcesByHost = new Map();
+    /** @type {Set<import("./sources/dataSource.js").default>} */
+    #dataSources;
+
+    /** @type {Set<import("./collector.js").default>} */
+    #collectors;
 
-        /** @type {Map<H, import("./collector.js").default>} */
-        this._collectorsByHost = new Map();
+    constructor() {
+        /** @type {Set<import("./sources/dataSource.js").default>} */
+        this.#dataSources = new Set();
 
-        /** @type {Map<H, (function(import("./collector.js").default):void)[]>} */
-        this._observers = new Map();
+        /** @type {Set<import("./collector.js").default>} */
+        this.#collectors = new Set();
     }
 
     get dataSources() {
-        return [...new Set(this._dataSourcesByHost.values()).values()];
+        return [...this.#dataSources];
     }
 
     get collectors() {
-        return [...this._collectorsByHost.values()];
+        return [...this.#collectors];
     }
 
     /**
-     * Adds a callback function that will be called when a collector has completed.
-     *
-     * @param {function(import("./collector.js").default):void} callback
-     * @param {H} key
+     * @param {Iterable<import("./sources/dataSource.js").default>} dataSources
      */
-    addObserver(callback, key) {
-        let arr = this._observers.get(key);
-        if (!arr) {
-            arr = [];
-            this._observers.set(key, arr);
-        }
+    replaceDataSources(dataSources) {
+        this.#dataSources = new Set(dataSources);
+    }
 
-        arr.push(callback);
+    /**
+     * @param {import("./sources/dataSource.js").default} dataSource
+     */
+    addDataSource(dataSource) {
+        this.#dataSources.add(dataSource);
+    }
+
+    /**
+     * @param {import("./sources/dataSource.js").default} dataSource
+     */
+    removeDataSource(dataSource) {
+        this.#dataSources.delete(dataSource);
     }
 
     /**
-     *
      * @param {import("./collector.js").default} collector
-     * @param {H} key
      */
-    _relayObserverCallback(collector, key) {
-        const arr = this._observers.get(key);
-        if (arr) {
-            for (const callback of arr) {
-                // eslint-disable-next-line callback-return
-                callback(collector);
-            }
-        }
+    addCollector(collector) {
+        this.#collectors.add(collector);
     }
 
     /**
-     *
-     * @param {import("./sources/dataSource.js").default} dataSource
-     * @param {H} key
+     * @param {import("./collector.js").default} collector
      */
-    addDataSource(dataSource, key) {
-        this._dataSourcesByHost.set(key, dataSource);
+    removeCollector(collector) {
+        collector.observers.clear();
+        this.#collectors.delete(collector);
     }
 
     /**
+     * Prune a collector branch from the flow graph, removing empty ancestors.
      *
-     * @param {H} key
+     * @param {import("./collector.js").default} collector
      */
-    findDataSourceByKey(key) {
-        return this._dataSourcesByHost.get(key);
+    pruneCollectorBranch(collector) {
+        let parent = collector.parent;
+        if (parent) {
+            parent.removeChild(collector);
+        }
+
+        while (parent && parent.children.length === 0) {
+            const current = parent;
+            parent = current.parent;
+            if (parent) {
+                parent.removeChild(current);
+            } else if (current instanceof DataSource) {
+                this.removeDataSource(current);
+            }
+        }
     }
 
     /**
-     *
      * @param {string} name
      */
     findNamedDataSource(name) {
         /** @type {NamedSource} */
         let namedSource;
-        /** @type {H[]} */
-        let hosts = [];
-
-        // Note: If a named sources with the same name are present at multiple locations in the
-        // view hierarchy, the should actually be exactly the same instance. It's arranged that
-        // way in the data flow optimization phase.
 
-        for (const [host, dataSource] of this._dataSourcesByHost.entries()) {
+        // Note: If named sources with the same name are present at multiple locations in the
+        // view hierarchy, they should actually be exactly the same instance.
+        for (const dataSource of this.#dataSources.values()) {
             if (dataSource instanceof NamedSource) {
                 if (name == dataSource.identifier) {
                     if (namedSource && namedSource !== dataSource) {
@@ -96,7 +104,6 @@ export default class DataFlow {
                         );
                     }
                     namedSource = dataSource;
-                    hosts.push(host);
                 }
             }
         }
@@ -104,39 +111,9 @@ export default class DataFlow {
         if (namedSource) {
             return {
                 dataSource: namedSource,
-                hosts,
             };
         }
     }
 
-    /**
-     *
-     * @param {import("./collector.js").default} collector
-     * @param {H} key
-     */
-    addCollector(collector, key) {
-        this._collectorsByHost.set(key, collector);
-        collector.observers.push((collector) =>
-            this._relayObserverCallback(collector, key)
-        );
-    }
-
-    /**
-     *
-     * @param {H} key
-     */
-    findCollectorByKey(key) {
-        return this._collectorsByHost.get(key);
-    }
-
-    /**
-     * Allows the flow nodes to perform final initialization after the flow
-     * structure has been built and optimized.
-     * Must be called before any data are to be propagated.
-     */
-    initialize() {
-        for (const ds of this.dataSources) {
-            ds.visit((node) => node.initialize());
-        }
-    }
+    // Initialization is handled by subtree helpers to avoid global init order.
 }

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

@@ -0,0 +1,15 @@
+/**
+ * @typedef {object} FlowHandle
+ * @prop {import("./sources/dataSource.js").default} [dataSource]
+ * @prop {import("./collector.js").default} [collector]
+ */
+/**
+ * @param {FlowHandle} [handle]
+ * @returns {FlowHandle}
+ */
+export function createFlowHandle(handle?: FlowHandle): FlowHandle;
+export type FlowHandle = {
+    dataSource?: import("./sources/dataSource.js").default;
+    collector?: import("./collector.js").default;
+};
+//# sourceMappingURL=flowHandle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flowHandle.d.ts","sourceRoot":"","sources":["../../../src/data/flowHandle.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,0CAHW,UAAU,GACR,UAAU,CAItB;;iBAVS,OAAO,yBAAyB,EAAE,OAAO;gBACzC,OAAO,gBAAgB,EAAE,OAAO"}

package/dist/src/data/flowHandle.js

@@ -0,0 +1,13 @@
+/**
+ * @typedef {object} FlowHandle
+ * @prop {import("./sources/dataSource.js").default} [dataSource]
+ * @prop {import("./collector.js").default} [collector]
+ */
+
+/**
+ * @param {FlowHandle} [handle]
+ * @returns {FlowHandle}
+ */
+export function createFlowHandle(handle = {}) {
+    return handle;
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Synchronize flow handles after data flow optimization.
+ *
+ * @param {import("../view/view.js").default} root
+ * @param {Map<import("./sources/dataSource.js").default, import("./sources/dataSource.js").default>} canonicalBySource
+ */
+export function syncFlowHandles(root: import("../view/view.js").default, canonicalBySource: Map<import("./sources/dataSource.js").default, import("./sources/dataSource.js").default>): void;
+/**
+ * Initializes data flow and mark wiring for a subtree without rebuilding the
+ * entire view hierarchy. This is the primary entry point for dynamic view
+ * insertion: build the subtree fully, call this, then attach the subtree to
+ * the live hierarchy.
+ *
+ * What it does:
+ * - builds/extends the dataflow graph for the subtree
+ * - runs flow optimization and syncs flow handles to canonical data sources
+ * - discovers the nearest data sources for views in the subtree
+ * - initializes dataflow nodes (initialize) for those sources
+ * - initializes mark encoders for unit views
+ * - queues graphics initialization (if a GL context exists)
+ * - wires collector observers so marks update on data arrival
+ *
+ * How to use it:
+ * - call after the subtree is fully constructed (post-order build)
+ * - do not attach the subtree to the live hierarchy until after this call
+ * - dispose the old subtree before replacing it to prevent observer leaks
+ * - follow up with finalizeSubtreeGraphics(...) once graphics promises resolve
+ * - reconfigure scales for the subtree when data loads complete
+ *
+ * Considerations:
+ * - this does not trigger data loading; callers decide when to load
+ * - data sources are derived by walking to the nearest ancestor source; nested
+ *   sources should be treated as boundaries (do not walk past them)
+ * - only call updateGraphicsData when graphics are initialized or a GL context
+ *   is available; headless/test contexts must avoid WebGL usage
+ * - loadViewSubtreeData emits a subtree-scoped "subtreeDataReady" broadcast
+ *
+ * TODO:
+ * - promote in-flight load caching to a persistent load-state per source
+ * - replace global dataLoaded usage with subtree-scoped readiness
+ * - integrate with async font readiness for text marks
+ * - unify observer wiring via a disposable registry across view types
+ *
+ * @param {import("../view/view.js").default} subtreeRoot
+ * @param {import("./dataFlow.js").default} flow
+ * @returns {{
+ *     dataFlow: import("./dataFlow.js").default,
+ *     unitViews: UnitView[],
+ *     dataSources: Set<import("./sources/dataSource.js").default>,
+ *     graphicsPromises: Promise<import("../marks/mark.js").default>[]
+ * }}
+ */
+export function initializeViewSubtree(subtreeRoot: import("../view/view.js").default, flow: import("./dataFlow.js").default): {
+    dataFlow: import("./dataFlow.js").default;
+    unitViews: UnitView[];
+    dataSources: Set<import("./sources/dataSource.js").default>;
+    graphicsPromises: Promise<import("../marks/mark.js").default>[];
+};
+/**
+ * Collects data sources needed to initialize all views in the subtree.
+ * This includes sources that are overridden deeper in the hierarchy.
+ *
+ * @param {import("../view/view.js").default | import("../view/view.js").default[]} subtreeRoot
+ * @returns {Set<import("./sources/dataSource.js").default>}
+ */
+export function collectViewSubtreeDataSources(subtreeRoot: import("../view/view.js").default | import("../view/view.js").default[]): Set<import("./sources/dataSource.js").default>;
+/**
+ * Collects the nearest data sources under a subtree root.
+ * These sources define data-ready boundaries for subtree-level loading.
+ *
+ * @param {import("../view/view.js").default} subtreeRoot
+ * @returns {Set<import("./sources/dataSource.js").default>}
+ */
+export function collectNearestViewSubtreeDataSources(subtreeRoot: import("../view/view.js").default): Set<import("./sources/dataSource.js").default>;
+/**
+ * Loads the nearest data sources for a subtree.
+ * Use the returned promise as a subtree-level "data ready" signal.
+ *
+ * @param {import("../view/view.js").default} subtreeRoot
+ * @param {Set<import("./sources/dataSource.js").default>} [dataSources]
+ * @returns {Promise<void[]>}
+ */
+export function loadViewSubtreeData(subtreeRoot: import("../view/view.js").default, dataSources?: Set<import("./sources/dataSource.js").default>): Promise<void[]>;
+import UnitView from "../view/unitView.js";
+//# sourceMappingURL=flowInit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flowInit.d.ts","sourceRoot":"","sources":["../../../src/data/flowInit.js"],"names":[],"mappings":"AAoCA;;;;;GAKG;AACH,sCAHW,OAAO,iBAAiB,EAAE,OAAO,qBACjC,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,EAAE,OAAO,yBAAyB,EAAE,OAAO,CAAC,QAcnG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,mDATW,OAAO,iBAAiB,EAAE,OAAO,QACjC,OAAO,eAAe,EAAE,OAAO,GAC7B;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,CAsDH;AAED;;;;;;GAMG;AACH,2DAHW,OAAO,iBAAiB,EAAE,OAAO,GAAG,OAAO,iBAAiB,EAAE,OAAO,EAAE,GACrE,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,CAmB1D;AAED;;;;;;GAMG;AACH,kEAHW,OAAO,iBAAiB,EAAE,OAAO,GAC/B,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,CAY1D;AAED;;;;;;;GAOG;AACH,iDAJW,OAAO,iBAAiB,EAAE,OAAO,gBACjC,GAAG,CAAC,OAAO,yBAAyB,EAAE,OAAO,CAAC,GAC5C,OAAO,CAAC,IAAI,EAAE,CAAC,CAe3B;qBA7NoB,qBAAqB"}