@genome-spy/core 0.68.0 → 0.69.0

package/dist/src/marks/mark.js

@@ -48,7 +48,10 @@ import coalesceProperties from "../utils/propertyCoalescer.js";
 import { isScalar } from "../utils/variableTools.js";
 import { InternMap } from "internmap";
 import ViewError from "../view/viewError.js";
-import { isExprRef, validateParameterName } from "../view/paramMediator.js";
+import {
+    isExprRef,
+    validateParameterName,
+} from "../paramRuntime/paramUtils.js";
 import { UNIQUE_ID_KEY } from "../data/transforms/identifier.js";
 import {
     isIntervalSelection,
@@ -95,11 +98,6 @@ export default class Mark {
      */
     #callAfterShaderCompilation = [];
 
-    /**
-     * @type {{expr: import("../view/paramMediator.js").ExprRefFunction, listener: () => void}[]}
-     */
-    #exprListeners = [];
-
     /**
      * @param {import("../view/unitView.js").default} unitView
      */
@@ -304,13 +302,13 @@ export default class Mark {
         for (const key of props) {
             const prop = this.properties[key];
             if (prop && isExprRef(prop)) {
-                const fn = this.unitView.paramMediator.createExpression(
-                    prop.expr
+                const fn = this.unitView.paramRuntime.watchExpression(
+                    prop.expr,
+                    () => {
+                        this.updateGraphicsData();
+                        this.unitView.context.animator.requestRender();
+                    }
                 );
-                fn.addListener(() => {
-                    this.updateGraphicsData();
-                    this.unitView.context.animator.requestRender();
-                });
                 // @ts-ignore
                 if (!channels.includes(key)) {
                     Object.defineProperty(exprProps, key, {
@@ -487,8 +485,8 @@ export default class Mark {
 
         for (const predicate of paramPredicates) {
             const param = predicate.param;
-            const paramMediator = this.unitView.paramMediator;
-            const selection = paramMediator.findValue(param);
+            const paramRuntime = this.unitView.paramRuntime;
+            const selection = paramRuntime.findValue(param);
 
             // The selection is supposed to have an empty value at this point
             // so that we can figure out the type of the selection.
@@ -546,7 +544,7 @@ export default class Mark {
 
                     this.selectionTextureOps.push(() => {
                         // Texture is set in the prepareRender method
-                        const selection = paramMediator.getValue(param);
+                        const selection = paramRuntime.getValue(param);
                         const texture = selectionTextures.get(selection);
                         if (!texture) {
                             throw new Error(
@@ -569,11 +567,10 @@ export default class Mark {
                     // Create the initial texture
                     glHelper.createSelectionTexture(selection);
 
-                    const fn = paramMediator.createExpression(param);
-                    fn.addListener(() => {
+                    paramRuntime.watchExpression(param, () => {
                         const selection =
                             /** @type {import("../types/selectionTypes.js").MultiPointSelection} */ (
-                                fn(null)
+                                paramRuntime.getValue(param)
                             );
                         glHelper.createSelectionTexture(selection);
                         this.getContext().animator.requestRender();
@@ -1044,15 +1041,14 @@ export default class Mark {
         };
 
         if (isExprRef(propValue)) {
-            const fn = this.unitView.paramMediator.createExpression(
-                propValue.expr
-            );
-
+            /** @type {import("../paramRuntime/types.js").ExprRefFunction} */
+            let fn;
             const set = () => setter(adjuster(fn(null)));
+            fn = this.unitView.paramRuntime.watchExpression(
+                propValue.expr,
+                set
+            );
 
-            // Register a listener ...
-            fn.addListener(set);
-            this.#exprListeners.push({ expr: fn, listener: set });
             // ... and set the initial value
             set();
         } else {
@@ -1097,10 +1093,6 @@ export default class Mark {
     }
 
     dispose() {
-        for (const { expr, listener } of this.#exprListeners) {
-            expr.removeListener(listener);
-        }
-        this.#exprListeners.length = 0;
         this.deleteGraphicsData();
     }
 
@@ -1177,7 +1169,7 @@ export default class Mark {
     isPickingParticipant() {
         if (
             this.properties.tooltip === null &&
-            !this.unitView.paramMediator.hasPointSelections()
+            !this.unitView.paramRuntime.hasPointSelections()
         ) {
             // Disabled
             return false;

package/dist/src/marks/point.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"point.d.ts","sourceRoot":"","sources":["../../../src/marks/point.js"],"names":[],"mappings":"AAmBA;;GAEG;AACH;IAGI;;OAEG;IACH,sBAFW,OAAO,qBAAqB,EAAE,OAAO,EAmD/C;IA0EO,iDAMC;IAkET,+BAkBC;;CAgDJ;iBAtRgB,WAAW"}
+{"version":3,"file":"point.d.ts","sourceRoot":"","sources":["../../../src/marks/point.js"],"names":[],"mappings":"AAmBA;;GAEG;AACH;IAGI;;OAEG;IACH,sBAFW,OAAO,qBAAqB,EAAE,OAAO,EAiD/C;IA0EO,iDAMC;IAkET,+BAkBC;;CAgDJ;iBApRgB,WAAW"}

package/dist/src/marks/point.js

@@ -10,7 +10,7 @@ import FRAGMENT_SHADER from "./point.fragment.glsl.js";
 import COMMON_SHADER from "./point.common.glsl.js";
 
 import Mark from "./mark.js";
-import { isExprRef } from "../view/paramMediator.js";
+import { isExprRef } from "../paramRuntime/paramUtils.js";
 import { sampleIterable } from "../data/transforms/sample.js";
 import { fixFill, fixStroke } from "./markUtils.js";
 
@@ -58,11 +58,9 @@ export default class PointMark extends Mark {
         const szf = this.properties.semanticZoomFraction;
         if (szf != null) {
             if (isExprRef(szf)) {
-                const fn = this.unitView.paramMediator.createExpression(
-                    szf.expr
-                );
-                fn.addListener(() =>
-                    this.getContext().animator.requestRender()
+                const fn = this.unitView.paramRuntime.watchExpression(
+                    szf.expr,
+                    () => this.getContext().animator.requestRender()
                 );
                 this.#semanticZoomFraction = fn;
             } else {

package/dist/src/paramRuntime/expressionCompiler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {string} expr
+ * @param {Record<string, any>} [globalObject]
+ * @returns {import("../utils/expression.js").ExpressionFunction}
+ */
+export function compileExpression(expr: string, globalObject?: Record<string, any>): import("../utils/expression.js").ExpressionFunction;
+//# sourceMappingURL=expressionCompiler.d.ts.map

package/dist/src/paramRuntime/expressionCompiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressionCompiler.d.ts","sourceRoot":"","sources":["../../../src/paramRuntime/expressionCompiler.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wCAJW,MAAM,iBACN,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjB,OAAO,wBAAwB,EAAE,kBAAkB,CAI/D"}

package/dist/src/paramRuntime/expressionCompiler.js

@@ -0,0 +1,10 @@
+import createFunction from "../utils/expression.js";
+
+/**
+ * @param {string} expr
+ * @param {Record<string, any>} [globalObject]
+ * @returns {import("../utils/expression.js").ExpressionFunction}
+ */
+export function compileExpression(expr, globalObject = {}) {
+    return createFunction(expr, globalObject);
+}

package/dist/src/paramRuntime/expressionRef.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @typedef {{
+ *   expression: import("./types.js").ExprRefFunction,
+ *   dependencies: import("./types.js").ParamRef<any>[]
+ * }} BoundExpression
+ */
+/**
+ * Binds expression globals to parameter refs in a specific scope and equips the
+ * resulting expression function with listener lifecycle helpers.
+ *
+ * @param {string} expr
+ * @param {(name: string) => import("./types.js").ParamRef<any> | undefined} resolve
+ * @returns {BoundExpression}
+ */
+export function bindExpression(expr: string, resolve: (name: string) => import("./types.js").ParamRef<any> | undefined): BoundExpression;
+export type BoundExpression = {
+    expression: import("./types.js").ExprRefFunction;
+    dependencies: import("./types.js").ParamRef<any>[];
+};
+//# sourceMappingURL=expressionRef.d.ts.map

package/dist/src/paramRuntime/expressionRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressionRef.d.ts","sourceRoot":"","sources":["../../../src/paramRuntime/expressionRef.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,qCAJW,MAAM,WACN,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,SAAS,GAC9D,eAAe,CA+E3B;8BA3FY;IACR,UAAU,EAAE,OAAO,YAAY,EAAE,eAAe,CAAC;IACjD,YAAY,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAA;CACnD"}

package/dist/src/paramRuntime/expressionRef.js

@@ -0,0 +1,95 @@
+import { compileExpression } from "./expressionCompiler.js";
+
+/**
+ * @typedef {{
+ *   expression: import("./types.js").ExprRefFunction,
+ *   dependencies: import("./types.js").ParamRef<any>[]
+ * }} BoundExpression
+ */
+
+/**
+ * Binds expression globals to parameter refs in a specific scope and equips the
+ * resulting expression function with listener lifecycle helpers.
+ *
+ * @param {string} expr
+ * @param {(name: string) => import("./types.js").ParamRef<any> | undefined} resolve
+ * @returns {BoundExpression}
+ */
+export function bindExpression(expr, resolve) {
+    const globalObject = {};
+
+    /** @type {import("./types.js").ExprRefFunction} */
+    const expression = /** @type {any} */ (
+        compileExpression(expr, globalObject)
+    );
+
+    /** @type {Map<string, import("./types.js").ParamRef<any>>} */
+    const refsForParams = new Map();
+
+    for (const globalName of expression.globals) {
+        if (refsForParams.has(globalName)) {
+            continue;
+        }
+
+        const ref = resolve(globalName);
+        if (!ref) {
+            throw new Error(
+                'Unknown variable "' + globalName + '" in expression: ' + expr
+            );
+        }
+
+        refsForParams.set(globalName, ref);
+
+        Object.defineProperty(globalObject, globalName, {
+            enumerable: true,
+            get() {
+                return ref.get();
+            },
+        });
+    }
+
+    /** @type {Set<() => void>} */
+    const activeSubscriptions = new Set();
+
+    expression.subscribe = (listener) => {
+        /** @type {(() => void)[]} */
+        const disposers = [];
+        for (const ref of refsForParams.values()) {
+            disposers.push(ref.subscribe(listener));
+        }
+
+        let active = true;
+        const unsubscribe = () => {
+            if (!active) {
+                return;
+            }
+            active = false;
+            activeSubscriptions.delete(unsubscribe);
+            disposers.forEach((dispose) => dispose());
+        };
+        activeSubscriptions.add(unsubscribe);
+
+        return unsubscribe;
+    };
+
+    expression.invalidate = () => {
+        for (const unsubscribe of activeSubscriptions) {
+            unsubscribe();
+        }
+        activeSubscriptions.clear();
+    };
+
+    // Include dependency identities to avoid collisions between structurally
+    // identical expressions in different scopes.
+    expression.identifier = () =>
+        expression.code +
+        "|" +
+        Array.from(refsForParams.values())
+            .map((ref) => ref.id)
+            .join(",");
+
+    return {
+        expression,
+        dependencies: Array.from(refsForParams.values()),
+    };
+}

package/dist/src/paramRuntime/expressionRef.test.d.ts

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

package/dist/src/paramRuntime/expressionRef.test.d.ts.map

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

package/dist/src/paramRuntime/graphRuntime.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Low-level reactive DAG runtime for parameter propagation.
+ *
+ * `GraphRuntime` is the scheduling engine behind `ParamRuntime`. It owns:
+ * 1. Writable source nodes (`base` and `selection`).
+ * 2. Derived/computed nodes with explicit dependencies.
+ * 3. Side-effect nodes that run after computed stabilization.
+ * 4. Transaction-aware batching and deterministic topological flushing.
+ *
+ * Typical usage:
+ * 1. Create writable refs using `createWritable(...)`.
+ * 2. Build derived refs with `computed(...)` from existing refs.
+ * 3. Attach side effects with `effect(...)` when external work is needed.
+ * 4. Batch writes with `runInTransaction(...)` when multiple updates belong to
+ *    one logical state transition.
+ * 5. Await `whenPropagated(...)` when callers need a "graph is settled" barrier.
+ *
+ * Notes:
+ * 1. This class is intended for runtime internals; most call sites should use
+ *    `ParamRuntime` / `ViewParamRuntime`.
+ * 2. Equality is referential (`!==`), so object writes must use new identities
+ *    to trigger propagation.
+ */
+export default class GraphRuntime {
+    /**
+     * Creates a graph runtime.
+     *
+     * @param {object} [options]
+     * @param {import("./lifecycleRegistry.js").default} [options.lifecycleRegistry]
+     *      Optional lifecycle owner registry. When provided, all created nodes
+     *      are bound to owners and disposed automatically on owner disposal.
+     */
+    constructor(options?: {
+        lifecycleRegistry?: import("./lifecycleRegistry.js").default;
+    });
+    /**
+     * Registers a writable source node and returns a writable param ref.
+     *
+     * Write semantics:
+     * 1. A write triggers propagation only when `value !== currentValue`.
+     * 2. If `options.notify` is `false`, local listeners are not notified and
+     *    downstream scheduling is skipped for writes to this ref.
+     * 3. Writing to a disposed ref throws.
+     *
+     * Lifecycle:
+     * 1. The node is owner-bound via `ownerId`.
+     * 2. Owner disposal marks the node disposed and clears listeners.
+     *
+     * @template T
+     * @param {string} ownerId
+     * @param {string} name
+     * @param {"base" | "selection"} kind
+     * @param {T} initialValue
+     * @param {{ notify?: boolean }} [options]
+     * @returns {import("./types.js").WritableParamRef<T>}
+     */
+    createWritable<T>(ownerId: string, name: string, kind: "base" | "selection", initialValue: T, options?: {
+        notify?: boolean;
+    }): import("./types.js").WritableParamRef<T>;
+    /**
+     * Registers a derived node whose value is computed from dependencies.
+     *
+     * Compute semantics:
+     * 1. Initial value is computed eagerly at registration time.
+     * 2. On dependency changes, recomputation is queued (deduplicated per flush).
+     * 3. Downstream listeners are notified only if computed value identity changes.
+     *
+     * Lifecycle:
+     * 1. Dependency subscriptions are created immediately.
+     * 2. Owner disposal unsubscribes dependencies and detaches the node.
+     *
+     * @template T
+     * @param {string} ownerId
+     * @param {string} name
+     * @param {import("./types.js").ParamRef<any>[]} deps
+     * @param {() => T} fn
+     * @returns {import("./types.js").ParamRef<T>}
+     */
+    computed<T>(ownerId: string, name: string, deps: import("./types.js").ParamRef<any>[], fn: () => T): import("./types.js").ParamRef<T>;
+    /**
+     * Registers an effect node that runs after computed propagation.
+     *
+     * Effect semantics:
+     * 1. Effect callbacks are queued on dependency changes.
+     * 2. Effects run after computed nodes for the same flush epoch.
+     * 3. Multiple dependency changes before a flush coalesce to one queued run.
+     *
+     * @param {string} ownerId
+     * @param {import("./types.js").ParamRef<any>[]} deps
+     * @param {() => void} fn
+     * @returns {() => void} explicit disposer for manual teardown
+     */
+    effect(ownerId: string, deps: import("./types.js").ParamRef<any>[], fn: () => void): () => void;
+    /**
+     * Runs `fn` as an atomic update transaction for this runtime graph.
+     *
+     * Transaction intent:
+     * 1. Batch multiple source writes so downstream computeds/effects observe
+     *    the final state for the batch, not each intermediate write.
+     * 2. Defer scheduling/flush until the outermost transaction exits.
+     * 3. Preserve deterministic propagation order by running one flush pass
+     *    after the transaction boundary.
+     *
+     * Semantics:
+     * 1. Nested transactions are supported via depth counting.
+     * 2. Only the outermost transaction exit triggers scheduling.
+     * 3. If `fn` throws, the error is rethrown after transaction depth is
+     *    restored; pending propagation is still scheduled from `finally`.
+     * 4. The scheduled flush runs in a microtask (`queueMicrotask`) after the
+     *    outermost transaction exits.
+     * 5. This method does not force immediate synchronous propagation. Use
+     *    `flushNow()` when the caller explicitly requires immediate flushing.
+     *
+     * @template T
+     * @param {() => T} fn
+     * @returns {T}
+     */
+    runInTransaction<T>(fn: () => T): T;
+    /**
+     * Flushes currently queued computed/effect work immediately.
+     *
+     * Behavior:
+     * 1. No-op if called while a transaction is open.
+     * 2. No-op during re-entrant flush calls.
+     * 3. Runs computeds first, then effects, until the graph reaches a fixed
+     *    point for the current queued work.
+     */
+    flushNow(): void;
+    /**
+     * Returns a promise that resolves when currently pending graph propagation
+     * has completed (computed queue and effect queue are settled).
+     *
+     * This is a synchronization barrier for reactive propagation only. It does
+     * not include animation/time-based convergence semantics.
+     *
+     * @param {{ signal?: AbortSignal, timeoutMs?: number }} [options]
+     *      Optional cancellation/timeout controls for waiting callers.
+     * @returns {Promise<void>}
+     */
+    whenPropagated(options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<void>;
+    #private;
+}
+export type SubscribeFn = (listener: () => void) => () => void;
+export type RuntimeNodeBase = {
+    id: string;
+    rank: number;
+    disposed: boolean;
+    listeners: Set<() => void>;
+    subscribe: SubscribeFn;
+};
+export type WritableNode<T> = RuntimeNodeBase & {
+    value: T;
+    kind: "base" | "selection";
+    name: string;
+};
+export type ComputedNode<T> = RuntimeNodeBase & {
+    value: T;
+    kind: "derived";
+    name: string;
+    fn: () => T;
+};
+export type EffectNode = {
+    id: string;
+    rank: number;
+    disposed: boolean;
+    fn: () => void;
+};
+/**
+ * @param {import("./types.js").ParamRef<any>} ref
+ * @returns {RuntimeNodeBase}
+ */
+export function getNode(ref: import("./types.js").ParamRef<any>): RuntimeNodeBase;
+//# sourceMappingURL=graphRuntime.d.ts.map

package/dist/src/paramRuntime/graphRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphRuntime.d.ts","sourceRoot":"","sources":["../../../src/paramRuntime/graphRuntime.js"],"names":[],"mappings":"AAoIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA6BI;;;;;;;OAOG;IACH,sBAJG;QAA2D,iBAAiB,GAApE,OAAO,wBAAwB,EAAE,OAAO;KAGlD,EAGA;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eARa,CAAC,WACH,MAAM,QACN,MAAM,QACN,MAAM,GAAG,WAAW,gBACpB,CAAC,YACD;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAClB,OAAO,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAwDpD;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAPa,CAAC,WACH,MAAM,QACN,MAAM,QACN,OAAO,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MACpC,MAAM,CAAC,GACL,OAAO,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,CAuD5C;IAED;;;;;;;;;;;;OAYG;IACH,gBALW,MAAM,QACN,OAAO,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MACpC,MAAM,IAAI,GACR,MAAM,IAAI,CAwCtB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,iBAJa,CAAC,MACH,MAAM,CAAC,GACL,CAAC,CAYb;IAED;;;;;;;;OAQG;IACH,iBA8CC;IAED;;;;;;;;;;OAUG;IACH,yBAJW;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAE1C,OAAO,CAAC,IAAI,CAAC,CAgDzB;;CA2EJ;0BA3mBY,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI;8BAEpC;IACR,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;IAC3B,SAAS,EAAE,WAAW,CAAA;CACvB;yBAIS,CAAC,IACD,eAAe,GAAG;IAC1B,KAAK,EAAE,CAAC,CAAC;IACT,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAA;CACb;yBAIS,CAAC,IACD,eAAe,GAAG;IAC1B,KAAK,EAAE,CAAC,CAAC;IACT,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC,CAAA;CACZ;yBAIS;IACR,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,EAAE,EAAE,MAAM,IAAI,CAAA;CACf;AAgEJ;;;GAGG;AACH,6BAHW,OAAO,YAAY,EAAE,QAAQ,CAAC,GAAG,CAAC,GAChC,eAAe,CAa3B"}