@genome-spy/core 0.68.0 → 0.69.1

package/dist/src/paramRuntime/lifecycleRegistry.js

@@ -0,0 +1,54 @@
+/**
+ * Tracks owner-bound cleanup callbacks for runtime resources.
+ *
+ * Why this exists:
+ * reactive graph nodes and expression subscriptions can outlive their creating
+ * call site unless they are disposed explicitly. The lifecycle registry gives
+ * `ParamRuntime`/`GraphRuntime` a single owner-based teardown mechanism so
+ * disposing a scope/view reliably detaches listeners and releases resources.
+ */
+export default class LifecycleRegistry {
+    #nextOwnerId = 1;
+
+    /** @type {Map<string, Set<() => void>>} */
+    #ownerDisposers = new Map();
+
+    /**
+     * @param {"view" | "mark" | "transform" | "source" | "scope"} kind
+     * @param {string} key
+     */
+    createOwner(kind, key) {
+        const ownerId = kind + ":" + key + ":" + this.#nextOwnerId++;
+        this.#ownerDisposers.set(ownerId, new Set());
+        return ownerId;
+    }
+
+    /**
+     * @param {string} ownerId
+     * @param {() => void} disposer
+     */
+    addDisposer(ownerId, disposer) {
+        const disposers = this.#ownerDisposers.get(ownerId);
+        if (!disposers) {
+            throw new Error("Unknown owner: " + ownerId);
+        }
+
+        disposers.add(disposer);
+    }
+
+    /**
+     * @param {string} ownerId
+     */
+    disposeOwner(ownerId) {
+        const disposers = this.#ownerDisposers.get(ownerId);
+        if (!disposers) {
+            return;
+        }
+
+        for (const disposer of disposers) {
+            disposer();
+        }
+        disposers.clear();
+        this.#ownerDisposers.delete(ownerId);
+    }
+}

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

@@ -0,0 +1,165 @@
+/**
+ * Core-facing parameter runtime facade.
+ *
+ * `ParamRuntime` composes three internal subsystems:
+ * 1. `ParamStore` for scoped name resolution (`scope` + `name` -> ref).
+ * 2. `GraphRuntime` for reactive propagation and batching.
+ * 3. `LifecycleRegistry` for owner-bound teardown.
+ *
+ * Most Core call sites should use this class (or `ViewParamRuntime`) instead
+ * of interacting with `GraphRuntime` directly.
+ *
+ * Scope semantics used by this runtime:
+ * 1. A scope is a runtime-only identity (`ScopeId`) with a parent pointer.
+ * 2. Parameters are registered into exactly one scope.
+ * 3. Name resolution is lexical/nearest-first: local scope, then parent chain.
+ * 4. Shadowing is allowed across scopes (same param name in parent/child).
+ * 5. Duplicate names are rejected within a single scope.
+ * 6. `disposeScope` clears local bindings and owner resources while preserving
+ *    scope-chain structure for descendants that still resolve through parents.
+ *
+ * @typedef {string} ScopeId
+ */
+export default class ParamRuntime {
+    /**
+     * Creates a new parameter scope.
+     *
+     * If `parentScope` is provided, name resolution in this scope falls back to
+     * the parent chain.
+     *
+     * @param {ScopeId} [parentScope]
+     * @returns {ScopeId}
+     */
+    createScope(parentScope?: ScopeId): ScopeId;
+    /**
+     * Disposes all runtime resources owned by the scope and clears the scope's
+     * local parameter bindings.
+     *
+     * Descendant scopes remain valid and continue resolving through their own
+     * parent chains.
+     *
+     * @param {ScopeId} scope
+     */
+    disposeScope(scope: ScopeId): void;
+    /**
+     * Registers a disposer that is bound to the scope lifecycle.
+     *
+     * The disposer is called when `disposeScope(scope)` is executed.
+     *
+     * @param {ScopeId} scope
+     * @param {() => void} disposer
+     */
+    addScopeDisposer(scope: ScopeId, disposer: () => void): void;
+    /**
+     * Registers a writable base parameter in `scope`.
+     *
+     * @template T
+     * @param {ScopeId} scope
+     * @param {string} name
+     * @param {T} initial
+     * @param {{ notify?: boolean }} [options]
+     * @returns {import("./types.js").WritableParamRef<T>}
+     */
+    registerBase<T>(scope: ScopeId, name: string, initial: T, options?: {
+        notify?: boolean;
+    }): import("./types.js").WritableParamRef<T>;
+    /**
+     * Registers a writable selection parameter in `scope`.
+     *
+     * Selection params are writable like base params but carry `kind:
+     * "selection"` for downstream handling.
+     *
+     * @template T
+     * @param {ScopeId} scope
+     * @param {string} name
+     * @param {T} initial
+     * @param {{ notify?: boolean }} [options]
+     * @returns {import("./types.js").WritableParamRef<T>}
+     */
+    registerSelection<T>(scope: ScopeId, name: string, initial: T, options?: {
+        notify?: boolean;
+    }): import("./types.js").WritableParamRef<T>;
+    /**
+     * Registers a derived read-only parameter in `scope`.
+     *
+     * The expression is bound to current scope resolution and re-evaluated by
+     * the graph runtime when dependencies change.
+     *
+     * @template T
+     * @param {ScopeId} scope
+     * @param {string} name
+     * @param {string} expr
+     * @returns {import("./types.js").ParamRef<T>}
+     */
+    registerDerived<T>(scope: ScopeId, name: string, expr: string): import("./types.js").ParamRef<T>;
+    /**
+     * Creates an expression function bound to scope-based parameter resolution.
+     *
+     * The returned expression supports subscriptions (`subscribe`)
+     * and can be used by callers that need expression-level reactivity without
+     * registering a named derived parameter.
+     *
+     * @param {ScopeId} scope
+     * @param {string} expr
+     * @returns {import("./types.js").ExprRefFunction}
+     */
+    createExpression(scope: ScopeId, expr: string): import("./types.js").ExprRefFunction;
+    /**
+     * Resolves a parameter by name from `scope`, searching parent scopes as needed.
+     * Returns the nearest matching binding, if any.
+     *
+     * @template T
+     * @param {ScopeId} scope
+     * @param {string} name
+     * @returns {import("./types.js").ParamRef<T> | undefined}
+     */
+    resolve<T>(scope: ScopeId, name: string): import("./types.js").ParamRef<T> | undefined;
+    /**
+     * Runs a transactional update against the underlying graph runtime.
+     *
+     * Multiple writes inside `fn` are batched and propagated after the
+     * outermost transaction exits.
+     *
+     * @template T
+     * @param {() => T} fn
+     * @returns {T}
+     */
+    runInTransaction<T>(fn: () => T): T;
+    /**
+     * Forces immediate synchronous propagation of currently queued graph work.
+     */
+    flushNow(): void;
+    /**
+     * Resolves when propagation/effects have settled in the graph runtime.
+     *
+     * @param {{ signal?: AbortSignal, timeoutMs?: number }} [options]
+     * @returns {Promise<void>}
+     */
+    whenPropagated(options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<void>;
+    #private;
+}
+/**
+ * Core-facing parameter runtime facade.
+ *
+ * `ParamRuntime` composes three internal subsystems:
+ * 1. `ParamStore` for scoped name resolution (`scope` + `name` -> ref).
+ * 2. `GraphRuntime` for reactive propagation and batching.
+ * 3. `LifecycleRegistry` for owner-bound teardown.
+ *
+ * Most Core call sites should use this class (or `ViewParamRuntime`) instead
+ * of interacting with `GraphRuntime` directly.
+ *
+ * Scope semantics used by this runtime:
+ * 1. A scope is a runtime-only identity (`ScopeId`) with a parent pointer.
+ * 2. Parameters are registered into exactly one scope.
+ * 3. Name resolution is lexical/nearest-first: local scope, then parent chain.
+ * 4. Shadowing is allowed across scopes (same param name in parent/child).
+ * 5. Duplicate names are rejected within a single scope.
+ * 6. `disposeScope` clears local bindings and owner resources while preserving
+ *    scope-chain structure for descendants that still resolve through parents.
+ */
+export type ScopeId = string;
+//# sourceMappingURL=paramRuntime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paramRuntime.d.ts","sourceRoot":"","sources":["../../../src/paramRuntime/paramRuntime.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IASI;;;;;;;;OAQG;IACH,0BAHW,OAAO,GACL,OAAO,CAYnB;IAED;;;;;;;;OAQG;IACH,oBAFW,OAAO,QAMjB;IAED;;;;;;;OAOG;IACH,wBAHW,OAAO,YACP,MAAM,IAAI,QAKpB;IAED;;;;;;;;;OASG;IACH,aAPa,CAAC,SACH,OAAO,QACP,MAAM,WACN,CAAC,YACD;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAClB,OAAO,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAYpD;IAED;;;;;;;;;;;;OAYG;IACH,kBAPa,CAAC,SACH,OAAO,QACP,MAAM,WACN,CAAC,YACD;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAClB,OAAO,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAYpD;IAED;;;;;;;;;;;OAWG;IACH,gBANa,CAAC,SACH,OAAO,QACP,MAAM,QACN,MAAM,GACJ,OAAO,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,CAgB5C;IAED;;;;;;;;;;OAUG;IACH,wBAJW,OAAO,QACP,MAAM,GACJ,OAAO,YAAY,EAAE,eAAe,CAOhD;IAED;;;;;;;;OAQG;IACH,QALa,CAAC,SACH,OAAO,QACP,MAAM,GACJ,OAAO,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAIxD;IAED;;;;;;;;;OASG;IACH,iBAJa,CAAC,MACH,MAAM,CAAC,GACL,CAAC,CAIb;IAED;;OAEG;IACH,iBAEC;IAED;;;;;OAKG;IACH,yBAHW;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAIzB;;CACJ;;;;;;;;;;;;;;;;;;;;;sBApMY,MAAM"}

package/dist/src/paramRuntime/paramRuntime.js

@@ -0,0 +1,222 @@
+import GraphRuntime from "./graphRuntime.js";
+import LifecycleRegistry from "./lifecycleRegistry.js";
+import ParamStore from "./paramStore.js";
+import { bindExpression } from "./expressionRef.js";
+
+/**
+ * Core-facing parameter runtime facade.
+ *
+ * `ParamRuntime` composes three internal subsystems:
+ * 1. `ParamStore` for scoped name resolution (`scope` + `name` -> ref).
+ * 2. `GraphRuntime` for reactive propagation and batching.
+ * 3. `LifecycleRegistry` for owner-bound teardown.
+ *
+ * Most Core call sites should use this class (or `ViewParamRuntime`) instead
+ * of interacting with `GraphRuntime` directly.
+ *
+ * Scope semantics used by this runtime:
+ * 1. A scope is a runtime-only identity (`ScopeId`) with a parent pointer.
+ * 2. Parameters are registered into exactly one scope.
+ * 3. Name resolution is lexical/nearest-first: local scope, then parent chain.
+ * 4. Shadowing is allowed across scopes (same param name in parent/child).
+ * 5. Duplicate names are rejected within a single scope.
+ * 6. `disposeScope` clears local bindings and owner resources while preserving
+ *    scope-chain structure for descendants that still resolve through parents.
+ *
+ * @typedef {string} ScopeId
+ */
+export default class ParamRuntime {
+    #lifecycleRegistry = new LifecycleRegistry();
+
+    #graphRuntime = new GraphRuntime({
+        lifecycleRegistry: this.#lifecycleRegistry,
+    });
+
+    #paramStore = new ParamStore();
+
+    /**
+     * Creates a new parameter scope.
+     *
+     * If `parentScope` is provided, name resolution in this scope falls back to
+     * the parent chain.
+     *
+     * @param {ScopeId} [parentScope]
+     * @returns {ScopeId}
+     */
+    createScope(parentScope) {
+        const ownerId = this.#lifecycleRegistry.createOwner(
+            "scope",
+            parentScope ?? "root"
+        );
+        if (parentScope) {
+            return this.#paramStore.createChildScope(ownerId, parentScope);
+        } else {
+            return this.#paramStore.createRootScope(ownerId);
+        }
+    }
+
+    /**
+     * Disposes all runtime resources owned by the scope and clears the scope's
+     * local parameter bindings.
+     *
+     * Descendant scopes remain valid and continue resolving through their own
+     * parent chains.
+     *
+     * @param {ScopeId} scope
+     */
+    disposeScope(scope) {
+        const ownerId = this.#paramStore.getOwnerId(scope);
+        this.#lifecycleRegistry.disposeOwner(ownerId);
+        this.#paramStore.clearScope(scope);
+    }
+
+    /**
+     * Registers a disposer that is bound to the scope lifecycle.
+     *
+     * The disposer is called when `disposeScope(scope)` is executed.
+     *
+     * @param {ScopeId} scope
+     * @param {() => void} disposer
+     */
+    addScopeDisposer(scope, disposer) {
+        const ownerId = this.#paramStore.getOwnerId(scope);
+        this.#lifecycleRegistry.addDisposer(ownerId, disposer);
+    }
+
+    /**
+     * Registers a writable base parameter in `scope`.
+     *
+     * @template T
+     * @param {ScopeId} scope
+     * @param {string} name
+     * @param {T} initial
+     * @param {{ notify?: boolean }} [options]
+     * @returns {import("./types.js").WritableParamRef<T>}
+     */
+    registerBase(scope, name, initial, options) {
+        const ownerId = this.#paramStore.getOwnerId(scope);
+        const ref = this.#graphRuntime.createWritable(
+            ownerId,
+            name,
+            "base",
+            initial,
+            options
+        );
+        return this.#paramStore.register(scope, name, ref);
+    }
+
+    /**
+     * Registers a writable selection parameter in `scope`.
+     *
+     * Selection params are writable like base params but carry `kind:
+     * "selection"` for downstream handling.
+     *
+     * @template T
+     * @param {ScopeId} scope
+     * @param {string} name
+     * @param {T} initial
+     * @param {{ notify?: boolean }} [options]
+     * @returns {import("./types.js").WritableParamRef<T>}
+     */
+    registerSelection(scope, name, initial, options) {
+        const ownerId = this.#paramStore.getOwnerId(scope);
+        const ref = this.#graphRuntime.createWritable(
+            ownerId,
+            name,
+            "selection",
+            initial,
+            options
+        );
+        return this.#paramStore.register(scope, name, ref);
+    }
+
+    /**
+     * Registers a derived read-only parameter in `scope`.
+     *
+     * The expression is bound to current scope resolution and re-evaluated by
+     * the graph runtime when dependencies change.
+     *
+     * @template T
+     * @param {ScopeId} scope
+     * @param {string} name
+     * @param {string} expr
+     * @returns {import("./types.js").ParamRef<T>}
+     */
+    registerDerived(scope, name, expr) {
+        const { expression, dependencies } = bindExpression(
+            expr,
+            (globalName) => this.resolve(scope, globalName)
+        );
+
+        const ownerId = this.#paramStore.getOwnerId(scope);
+        const ref = this.#graphRuntime.computed(
+            ownerId,
+            name,
+            dependencies,
+            () => expression(null)
+        );
+        return this.#paramStore.register(scope, name, ref);
+    }
+
+    /**
+     * Creates an expression function bound to scope-based parameter resolution.
+     *
+     * The returned expression supports subscriptions (`subscribe`)
+     * and can be used by callers that need expression-level reactivity without
+     * registering a named derived parameter.
+     *
+     * @param {ScopeId} scope
+     * @param {string} expr
+     * @returns {import("./types.js").ExprRefFunction}
+     */
+    createExpression(scope, expr) {
+        const { expression } = bindExpression(expr, (globalName) =>
+            this.resolve(scope, globalName)
+        );
+        return expression;
+    }
+
+    /**
+     * Resolves a parameter by name from `scope`, searching parent scopes as needed.
+     * Returns the nearest matching binding, if any.
+     *
+     * @template T
+     * @param {ScopeId} scope
+     * @param {string} name
+     * @returns {import("./types.js").ParamRef<T> | undefined}
+     */
+    resolve(scope, name) {
+        return this.#paramStore.resolve(scope, name);
+    }
+
+    /**
+     * Runs a transactional update against the underlying graph runtime.
+     *
+     * Multiple writes inside `fn` are batched and propagated after the
+     * outermost transaction exits.
+     *
+     * @template T
+     * @param {() => T} fn
+     * @returns {T}
+     */
+    runInTransaction(fn) {
+        return this.#graphRuntime.runInTransaction(fn);
+    }
+
+    /**
+     * Forces immediate synchronous propagation of currently queued graph work.
+     */
+    flushNow() {
+        this.#graphRuntime.flushNow();
+    }
+
+    /**
+     * Resolves when propagation/effects have settled in the graph runtime.
+     *
+     * @param {{ signal?: AbortSignal, timeoutMs?: number }} [options]
+     * @returns {Promise<void>}
+     */
+    whenPropagated(options) {
+        return this.#graphRuntime.whenPropagated(options);
+    }
+}

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

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

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

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

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

@@ -0,0 +1,68 @@
+/**
+ * Runtime store for scoped parameter bindings.
+ *
+ * Responsibilities:
+ * 1. Maintain scope chain metadata (`scope -> parentScope`).
+ * 2. Store local bindings (`scope + name -> ParamRef`).
+ * 3. Resolve names using nearest-scope lookup through the parent chain.
+ *
+ * This class is intentionally storage-only: propagation/lifecycle is handled
+ * by higher-level runtime components.
+ */
+export default class ParamStore {
+    /**
+     * Creates a root scope with no parent scope.
+     *
+     * @param {string} ownerId
+     * @returns {string}
+     */
+    createRootScope(ownerId: string): string;
+    /**
+     * Creates a child scope whose fallback resolution target is `parentScope`.
+     *
+     * @param {string} ownerId
+     * @param {string} parentScope
+     * @returns {string}
+     */
+    createChildScope(ownerId: string, parentScope: string): string;
+    /**
+     * Returns lifecycle owner id associated with a scope.
+     *
+     * @param {string} scopeId
+     * @returns {string}
+     */
+    getOwnerId(scopeId: string): string;
+    /**
+     * Clears all parameter bindings from a scope while keeping the scope chain
+     * metadata intact for descendants that may still resolve through it.
+     *
+     * @param {string} scopeId
+     */
+    clearScope(scopeId: string): void;
+    /**
+     * Registers a local parameter binding into `scopeId`.
+     *
+     * The same parameter name can exist in parent scopes (shadowing), but
+     * duplicate names are not allowed within one scope.
+     *
+     * @template T
+     * @template {import("./types.js").ParamRef<T>} R
+     * @param {string} scopeId
+     * @param {string} name
+     * @param {R} ref
+     * @returns {R}
+     */
+    register<T, R extends import("./types.js").ParamRef<T>>(scopeId: string, name: string, ref: R): R;
+    /**
+     * Resolves a parameter by name from `scopeId`, searching current scope
+     * first and then walking parent scopes until a match is found.
+     *
+     * @template T
+     * @param {string} scopeId
+     * @param {string} name
+     * @returns {import("./types.js").ParamRef<T> | undefined}
+     */
+    resolve<T>(scopeId: string, name: string): import("./types.js").ParamRef<T> | undefined;
+    #private;
+}
+//# sourceMappingURL=paramStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paramStore.d.ts","sourceRoot":"","sources":["../../../src/paramRuntime/paramStore.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH;IAkBI;;;;;OAKG;IACH,yBAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;;OAMG;IACH,0BAJW,MAAM,eACN,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;OAKG;IACH,oBAFW,MAAM,QAShB;IAED;;;;;;;;;;;;OAYG;IACH,SAPa,CAAC,EACkC,CAAC,SAApC,OAAQ,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAE,WACpC,MAAM,QACN,MAAM,OACN,CAAC,GACC,CAAC,CAiBb;IAED;;;;;;;;OAQG;IACH,QALa,CAAC,WACH,MAAM,QACN,MAAM,GACJ,OAAO,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,CAoBxD;;CACJ"}

package/dist/src/paramRuntime/paramStore.js

@@ -0,0 +1,148 @@
+import { validateParameterName } from "./paramUtils.js";
+
+/**
+ * Runtime store for scoped parameter bindings.
+ *
+ * Responsibilities:
+ * 1. Maintain scope chain metadata (`scope -> parentScope`).
+ * 2. Store local bindings (`scope + name -> ParamRef`).
+ * 3. Resolve names using nearest-scope lookup through the parent chain.
+ *
+ * This class is intentionally storage-only: propagation/lifecycle is handled
+ * by higher-level runtime components.
+ */
+export default class ParamStore {
+    #nextScopeId = 1;
+
+    /**
+     * @typedef {{
+     *   parentScope?: string,
+     *   params: Map<string, import("./types.js").ParamRef<any>>,
+     *   ownerId: string
+     * }} ScopeRecord
+     */
+
+    /**
+     * Scope registry keyed by scope id.
+     *
+     * @type {Map<string, ScopeRecord>}
+     */
+    #scopes = new Map();
+
+    /**
+     * Creates a root scope with no parent scope.
+     *
+     * @param {string} ownerId
+     * @returns {string}
+     */
+    createRootScope(ownerId) {
+        const scopeId = "scope:" + this.#nextScopeId++;
+        this.#scopes.set(scopeId, { params: new Map(), ownerId });
+        return scopeId;
+    }
+
+    /**
+     * Creates a child scope whose fallback resolution target is `parentScope`.
+     *
+     * @param {string} ownerId
+     * @param {string} parentScope
+     * @returns {string}
+     */
+    createChildScope(ownerId, parentScope) {
+        if (!this.#scopes.has(parentScope)) {
+            throw new Error("Unknown parent scope: " + parentScope);
+        }
+
+        const scopeId = "scope:" + this.#nextScopeId++;
+        this.#scopes.set(scopeId, { parentScope, params: new Map(), ownerId });
+        return scopeId;
+    }
+
+    /**
+     * Returns lifecycle owner id associated with a scope.
+     *
+     * @param {string} scopeId
+     * @returns {string}
+     */
+    getOwnerId(scopeId) {
+        const scope = this.#scopes.get(scopeId);
+        if (!scope) {
+            throw new Error("Unknown scope: " + scopeId);
+        }
+        return scope.ownerId;
+    }
+
+    /**
+     * Clears all parameter bindings from a scope while keeping the scope chain
+     * metadata intact for descendants that may still resolve through it.
+     *
+     * @param {string} scopeId
+     */
+    clearScope(scopeId) {
+        const scope = this.#scopes.get(scopeId);
+        if (!scope) {
+            throw new Error("Unknown scope: " + scopeId);
+        }
+
+        scope.params.clear();
+    }
+
+    /**
+     * Registers a local parameter binding into `scopeId`.
+     *
+     * The same parameter name can exist in parent scopes (shadowing), but
+     * duplicate names are not allowed within one scope.
+     *
+     * @template T
+     * @template {import("./types.js").ParamRef<T>} R
+     * @param {string} scopeId
+     * @param {string} name
+     * @param {R} ref
+     * @returns {R}
+     */
+    register(scopeId, name, ref) {
+        validateParameterName(name);
+        const scope = this.#scopes.get(scopeId);
+        if (!scope) {
+            throw new Error("Unknown scope: " + scopeId);
+        }
+
+        if (scope.params.has(name)) {
+            throw new Error(
+                'Parameter "' + name + '" already exists in scope ' + scopeId
+            );
+        }
+
+        scope.params.set(name, ref);
+        return ref;
+    }
+
+    /**
+     * Resolves a parameter by name from `scopeId`, searching current scope
+     * first and then walking parent scopes until a match is found.
+     *
+     * @template T
+     * @param {string} scopeId
+     * @param {string} name
+     * @returns {import("./types.js").ParamRef<T> | undefined}
+     */
+    resolve(scopeId, name) {
+        validateParameterName(name);
+
+        let currentScopeId = scopeId;
+        while (currentScopeId) {
+            const scope = this.#scopes.get(currentScopeId);
+            if (!scope) {
+                throw new Error("Unknown scope: " + currentScopeId);
+            }
+
+            const ref = scope.params.get(name);
+            if (ref) {
+                return /** @type {import("./types.js").ParamRef<T>} */ (ref);
+            }
+            currentScopeId = scope.parentScope;
+        }
+
+        return undefined;
+    }
+}

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

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

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

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