From e561a43463a9bb0bf1305eaea72f13a01247486e Mon Sep 17 00:00:00 2001
From: milanofthe <milanofthe@users.noreply.github.com>
Date: Tue, 5 May 2026 20:03:01 +0200
Subject: [PATCH] Fix toolbox block resolution and surface installed versions

---
 src/lib/components/ConfirmationModal.svelte   |  1 +
 .../dialogs/ToolboxManagerDialog.svelte       | 17 ++++++-
 src/lib/components/nodes/BaseNode.svelte      | 49 ++++++++++++++-----
 src/lib/nodes/defineNode.ts                   |  6 +++
 src/lib/pyodide/pathsimRunner.ts              |  5 +-
 src/lib/schema/fileOps.ts                     | 14 +++++-
 src/lib/toolbox/bootstrap.ts                  |  6 +++
 src/lib/toolbox/dependencies.ts               |  3 +-
 src/lib/toolbox/installer.ts                  | 26 +++++++---
 src/lib/toolbox/pathsimVersion.ts             | 28 +++++++++++
 src/lib/toolbox/python.ts                     | 28 +++++++++++
 src/lib/toolbox/register.ts                   | 33 ++++++++-----
 src/lib/toolbox/types.ts                      |  4 ++
 src/lib/types/nodes.ts                        |  7 +++
 src/lib/types/schema.ts                       |  7 +++
 src/lib/utils/codePreviewHeader.ts            | 11 +++--
 src/routes/+page.svelte                       |  9 ++--
 17 files changed, 211 insertions(+), 43 deletions(-)
 create mode 100644 src/lib/toolbox/pathsimVersion.ts

diff --git a/src/lib/components/ConfirmationModal.svelte b/src/lib/components/ConfirmationModal.svelte
index 25372564..56f1c0a7 100644
--- a/src/lib/components/ConfirmationModal.svelte
+++ b/src/lib/components/ConfirmationModal.svelte
@@ -95,6 +95,7 @@
 		font-size: var(--font-sm);
 		color: var(--text-muted);
 		line-height: 1.5;
+		white-space: pre-wrap;
 	}
 
 	.dialog-actions {
diff --git a/src/lib/components/dialogs/ToolboxManagerDialog.svelte b/src/lib/components/dialogs/ToolboxManagerDialog.svelte
index 115e6c22..2363cad2 100644
--- a/src/lib/components/dialogs/ToolboxManagerDialog.svelte
+++ b/src/lib/components/dialogs/ToolboxManagerDialog.svelte
@@ -56,6 +56,7 @@
 	// Build artifact across the add-toolbox flow
 	let resolvedSource = $state<ToolboxSource | null>(null);
 	let resolvedImportPath = $state('');
+	let resolvedInstalledVersion = $state<string | null>(null);
 	let resolvedDisplayName = $state('');
 	let resolvedEventsImportPath = $state<string | undefined>(undefined);
 	let toolboxId = $state('');
@@ -97,6 +98,7 @@
 		eventsImportPathInput = '';
 		resolvedSource = null;
 		resolvedImportPath = '';
+		resolvedInstalledVersion = null;
 		resolvedDisplayName = '';
 		resolvedEventsImportPath = undefined;
 		toolboxId = '';
@@ -200,6 +202,7 @@
 			installMessage = describeInstall(resolvedSource);
 			const result = await performInstall(resolvedSource, resolvedImportPath || undefined);
 			resolvedImportPath = result.importPath;
+			resolvedInstalledVersion = result.installedVersion;
 
 			installStatus = 'discovering';
 			installMessage = `Inspecting ${resolvedImportPath}…`;
@@ -301,6 +304,7 @@
 			source: resolvedSource,
 			importPath: resolvedImportPath,
 			eventsImportPath: resolvedEventsImportPath,
+			installedVersion: resolvedInstalledVersion,
 			blocks: blockSelections,
 			events: eventSelections
 		};
@@ -387,7 +391,10 @@
 								{#each installed as t (t.id)}
 									<div class="installed-row">
 										<div class="installed-meta">
-											<div class="installed-name">{t.displayName}</div>
+											<div class="installed-name">
+												{t.displayName}
+												{#if t.installedVersion}<span class="installed-version">v{t.installedVersion}</span>{/if}
+											</div>
 											<div class="installed-source">
 												{#if t.source.type === 'pypi'}
 													pip · {t.source.pkg}{t.source.version ? `==${t.source.version}` : ''}
@@ -782,6 +789,14 @@
 		color: var(--text-muted);
 	}
 
+	.installed-version {
+		margin-left: 6px;
+		font-family: var(--font-mono);
+		font-size: var(--font-sm);
+		font-weight: 400;
+		color: var(--text-disabled);
+	}
+
 	.installed-source {
 		font-size: var(--font-sm);
 		color: var(--text-muted);
diff --git a/src/lib/components/nodes/BaseNode.svelte b/src/lib/components/nodes/BaseNode.svelte
index 036b8e07..b541d0ca 100644
--- a/src/lib/components/nodes/BaseNode.svelte
+++ b/src/lib/components/nodes/BaseNode.svelte
@@ -1,7 +1,7 @@
 <script lang="ts">
 	import { onDestroy } from 'svelte';
 	import { Handle, Position, useUpdateNodeInternals } from '@xyflow/svelte';
-	import { nodeRegistry, type NodeInstance } from '$lib/nodes';
+	import { nodeRegistry, registryVersion, type NodeInstance } from '$lib/nodes';
 	import { getShapeCssClass, isSubsystem } from '$lib/nodes/shapes/index';
 	import { NODE_TYPES } from '$lib/constants/nodeTypes';
 	import { openNodeDialog } from '$lib/stores/nodeDialog';
@@ -33,8 +33,16 @@
 	// Get SvelteFlow hook to trigger re-measurement when node size changes
 	const updateNodeInternals = useUpdateNodeInternals();
 
-	// Get type definition
-	const typeDef = $derived(nodeRegistry.get(data.type));
+	// Get type definition. The registry isn't a reactive store on its own,
+	// so we tick on registryVersion bumps (toolbox install/uninstall) and
+	// re-read here. Without this, blocks loaded before their toolbox finished
+	// bootstrapping would stay stuck rendering as (missing).
+	let registryTick = $state(0);
+	const unsubRegistry = registryVersion.subscribe((v) => (registryTick = v));
+	const typeDef = $derived.by(() => {
+		registryTick; // dependency: re-read whenever the registry version bumps
+		return nodeRegistry.get(data.type);
+	});
 	const category = $derived(typeDef?.category || 'Algebraic');
 
 	// Get valid pinned params (filter out any that no longer exist in the type definition)
@@ -109,6 +117,7 @@
 	});
 
 	onDestroy(() => {
+		unsubRegistry();
 		unsubscribePinned();
 		unsubscribePlotData();
 		unsubscribePortLabels();
@@ -333,7 +342,13 @@
 	const shapeClass = $derived(() => typeDef ? getShapeCssClass(typeDef) : 'shape-default');
 
 	// Custom node color (defaults to pathsim-blue)
-	const nodeColor = $derived(data.color || 'var(--accent)');
+	// Missing blocks (type not registered) override any custom color so the
+	// whole block — name, handles, hover state — picks up the error red.
+	const nodeColor = $derived(
+		!typeDef && data.type !== NODE_TYPES.SUBSYSTEM && data.type !== NODE_TYPES.INTERFACE
+			? 'var(--error)'
+			: data.color || 'var(--accent)'
+	);
 
 	// Handle pinned param change
 	function handlePinnedParamChange(paramName: string, value: string) {
@@ -697,6 +712,9 @@
 		font-size: 8px;
 		color: var(--text-muted);
 		margin-top: 2px;
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
 	}
 
 	.node-content.has-icon {
@@ -727,19 +745,28 @@
 	}
 
 	.node-type.missing {
-		color: var(--warning);
+		color: var(--error);
+		font-weight: 500;
 	}
 
 	/* Visual marker for nodes whose block type isn't registered (e.g. file
-	   loaded with a toolbox dependency the user hasn't installed). */
+	 * loaded with a toolbox dependency the user hasn't installed). Same
+	 * shape as a normal block, just dressed in error red so it's obvious
+	 * something is wrong. */
 	.node.missing-type {
-		--node-color: var(--warning);
-		opacity: 0.85;
+		--node-color: var(--error);
+		border-color: var(--error);
+		background: var(--error-bg);
 	}
 
-	.node.missing-type .node-content,
-	.node.missing-type :global(.node-shape) {
-		border-style: dashed;
+	/* Port handles: paint the outer pentagon red so the missing block
+	 * carries its error state out to its connections. The inner cutout
+	 * picks up the red-tinted body so it visually merges with the block. */
+	:global(.node.missing-type .svelte-flow__handle::before) {
+		background: var(--error);
+	}
+	:global(.node.missing-type .svelte-flow__handle::after) {
+		background: color-mix(in srgb, var(--error-bg) 60%, var(--surface-raised));
 	}
 
 	/* Pinned parameters - rectangular, clipped by node-clip's overflow:hidden */
diff --git a/src/lib/nodes/defineNode.ts b/src/lib/nodes/defineNode.ts
index 3604f8c3..b3d57e10 100644
--- a/src/lib/nodes/defineNode.ts
+++ b/src/lib/nodes/defineNode.ts
@@ -11,6 +11,10 @@ interface DefineNodeOptions {
 	category: NodeCategory;
 	description?: string;
 	blockClass: string; // PathSim class name
+	/** Python module to import `blockClass` from. Optional — built-ins
+	 *  resolve via the static map in `blocks.ts`. Toolbox-registered
+	 *  blocks pass their toolbox `importPath` here. */
+	importPath?: string;
 
 	// Port configuration
 	inputs?: string[]; // Named input ports
@@ -47,6 +51,7 @@ export function defineNode(options: DefineNodeOptions): NodeTypeDefinition {
 		category,
 		description = `${name} block`,
 		blockClass,
+		importPath,
 		inputs = ['in 0'],
 		outputs = ['out 0'],
 		minInputs = 1,
@@ -75,6 +80,7 @@ export function defineNode(options: DefineNodeOptions): NodeTypeDefinition {
 		category,
 		description,
 		blockClass,
+		importPath,
 		shape,
 
 		ports: {
diff --git a/src/lib/pyodide/pathsimRunner.ts b/src/lib/pyodide/pathsimRunner.ts
index d9dbea17..5bd54b0a 100644
--- a/src/lib/pyodide/pathsimRunner.ts
+++ b/src/lib/pyodide/pathsimRunner.ts
@@ -163,7 +163,10 @@ function collectBlockImportGroups(nodes: NodeInstance[]): Map<string, Set<string
 		const typeDef = nodeRegistry.get(node.type);
 		if (!typeDef) continue;
 
-		const importPath = blockImportPaths[typeDef.blockClass] || 'pathsim.blocks';
+		// Toolbox-registered blocks carry their own importPath; built-ins
+		// fall back to the static map. Last fallback is core pathsim.blocks.
+		const importPath =
+			typeDef.importPath ?? blockImportPaths[typeDef.blockClass] ?? 'pathsim.blocks';
 		if (!groups.has(importPath)) groups.set(importPath, new Set());
 		groups.get(importPath)!.add(typeDef.blockClass);
 	}
diff --git a/src/lib/schema/fileOps.ts b/src/lib/schema/fileOps.ts
index 4e483cad..61558a34 100644
--- a/src/lib/schema/fileOps.ts
+++ b/src/lib/schema/fileOps.ts
@@ -29,6 +29,7 @@ import {
 	upsertToolbox,
 	getCatalogEntry
 } from '$lib/toolbox';
+import { getCachedPathsimVersion } from '$lib/toolbox/pathsimVersion';
 import type { ToolboxRequirement } from '$lib/types/schema';
 import { requestAssemblyAnimation } from '$lib/animation/assemblyAnimation';
 import { downloadJson } from '$lib/utils/download';
@@ -97,13 +98,15 @@ export function createGraphFile(name?: string): GraphFile {
 	) as SimulationSettings;
 
 	const requiredToolboxes = collectRequiredToolboxes(nodes);
+	const pathsimVersion = getCachedPathsimVersion();
 
 	return {
 		version: GRAPH_FILE_VERSION,
 		metadata: {
 			created: new Date().toISOString(),
 			modified: new Date().toISOString(),
-			name: name || 'Untitled'
+			name: name || 'Untitled',
+			...(pathsimVersion ? { pathsimVersion } : {})
 		},
 		graph: {
 			nodes: cleanedNodes,
@@ -172,7 +175,13 @@ async function installRequiredToolboxes(reqs: ToolboxRequirement[]): Promise<voi
 	const missing = findMissingRequirements(reqs);
 	if (missing.length === 0) return;
 
-	const list = missing.map((r) => `· ${r.displayName}`).join('\n');
+	// List missing toolboxes with the version recorded in the file as info —
+	// purely transparency so the user knows which version the model was
+	// authored against. Install resolves to whatever's latest; if a user
+	// needs to pin, they can do it manually in the toolbox manager.
+	const list = missing
+		.map((r) => `· ${r.displayName}${r.installedVersion ? ` (saved with v${r.installedVersion})` : ''}`)
+		.join('\n');
 	const ok = await confirmationStore.show({
 		title: 'Install required toolboxes?',
 		message: `This file uses ${missing.length} toolbox${missing.length === 1 ? '' : 'es'} that ${missing.length === 1 ? 'is' : 'are'} not installed:\n\n${list}\n\nInstall now?`,
@@ -204,6 +213,7 @@ async function installRequiredToolboxes(reqs: ToolboxRequirement[]): Promise<voi
 				source: req.source,
 				importPath: updated.importPath,
 				eventsImportPath: updated.eventsImportPath,
+				installedVersion: installResult.installedVersion,
 				blocks: discovered.blocks.map((b) => ({ className: b.className, enabled: true })),
 				events: discovered.events.map((e) => ({ className: e.className, enabled: true }))
 			};
diff --git a/src/lib/toolbox/bootstrap.ts b/src/lib/toolbox/bootstrap.ts
index 22ebbff6..93445c30 100644
--- a/src/lib/toolbox/bootstrap.ts
+++ b/src/lib/toolbox/bootstrap.ts
@@ -15,6 +15,7 @@ import { get } from 'svelte/store';
 import { toolboxes, upsertToolbox, seedPreloadedToolboxes } from './store';
 import { performInstall, discoverToolbox, registerToolbox } from './register';
 import { getCatalogEntry } from './catalog';
+import { primePathsimVersion } from './pathsimVersion';
 import type { ToolboxConfig } from './types';
 
 let bootstrapped = false;
@@ -23,6 +24,10 @@ export async function bootstrapToolboxes(): Promise<void> {
 	if (bootstrapped) return;
 	bootstrapped = true;
 
+	// Cache pathsim's version once so createGraphFile (which is sync) can
+	// stamp it into saved files without needing an async hop.
+	await primePathsimVersion();
+
 	seedPreloadedToolboxes();
 
 	const list = get(toolboxes);
@@ -43,6 +48,7 @@ export async function bootstrapToolboxes(): Promise<void> {
 			const reconciled: ToolboxConfig = {
 				...config,
 				importPath: installResult.importPath,
+				installedVersion: installResult.installedVersion,
 				blocks: discovered.blocks.map(
 					(b) =>
 						config.blocks.find((s) => s.className === b.className) ?? {
diff --git a/src/lib/toolbox/dependencies.ts b/src/lib/toolbox/dependencies.ts
index b83169da..c366fad5 100644
--- a/src/lib/toolbox/dependencies.ts
+++ b/src/lib/toolbox/dependencies.ts
@@ -31,7 +31,8 @@ function toRequirement(t: ToolboxConfig): ToolboxRequirement {
 		displayName: t.displayName,
 		source: t.source,
 		importPath: t.importPath,
-		eventsImportPath: t.eventsImportPath
+		eventsImportPath: t.eventsImportPath,
+		installedVersion: t.installedVersion ?? null
 	};
 }
 
diff --git a/src/lib/toolbox/installer.ts b/src/lib/toolbox/installer.ts
index 14c1da19..f24627f0 100644
--- a/src/lib/toolbox/installer.ts
+++ b/src/lib/toolbox/installer.ts
@@ -36,23 +36,21 @@ export interface IntrospectedEvent {
 	params: IntrospectedParam[];
 }
 
-let helpersLoaded = false;
-
 /**
  * Make sure Pyodide is initialized (so `json` and `_to_json` are available
  * for `evaluate(...)`) and that our toolbox helpers are defined.
+ *
+ * No JS-side cache: pathview wipes Python globals on simulation reset, so
+ * a cached "loaded" flag goes stale and the next call hits a NameError.
+ * The sentinel check is a single evaluate — cheap enough to run every time.
  */
 async function ensureHelpers(): Promise<void> {
-	if (helpersLoaded) return;
-	// initPyodide is idempotent and also runs REPL_SETUP_CODE which imports
-	// `json` and defines `_to_json` — both needed by evaluate().
 	await initPyodide();
 	const present = await evaluate<boolean>(TOOLBOX_HELPERS_SENTINEL);
 	if (!present) {
 		await exec(TOOLBOX_PYTHON_HELPERS);
+		await ensureDocutils();
 	}
-	await ensureDocutils();
-	helpersLoaded = true;
 }
 
 /**
@@ -146,6 +144,20 @@ export async function introspectEvents(importPath: string): Promise<Introspected
 	return result.events;
 }
 
+/**
+ * Best-effort version lookup for an installed module. Reads
+ * `module.__version__` first, falls back to `importlib.metadata`. Returns
+ * null when neither is available (typical for inline modules).
+ */
+export async function getModuleVersion(importPath: string): Promise<string | null> {
+	await ensureHelpers();
+	try {
+		return await evaluate<string | null>(`_pv_module_version(${pyStr(importPath)})`);
+	} catch {
+		return null;
+	}
+}
+
 /**
  * Drop a module from sys.modules. micropip has no real uninstall, so the
  * package files stay cached in the Pyodide FS until reload, but importing
diff --git a/src/lib/toolbox/pathsimVersion.ts b/src/lib/toolbox/pathsimVersion.ts
new file mode 100644
index 00000000..a93aff27
--- /dev/null
+++ b/src/lib/toolbox/pathsimVersion.ts
@@ -0,0 +1,28 @@
+/**
+ * Cached pathsim version. Read once via `getModuleVersion('pathsim')` after
+ * bootstrap, then exposed synchronously so `createGraphFile` (which can't
+ * be async because it's called from autoSave) can stamp the version into
+ * saved files.
+ */
+
+import { getModuleVersion } from './installer';
+
+let cached: string | null = null;
+let primed = false;
+
+/** Read pathsim's version from Python and cache it. Call once after the
+ *  Python runtime is up (bootstrap or first save). Idempotent. */
+export async function primePathsimVersion(): Promise<void> {
+	if (primed) return;
+	try {
+		cached = await getModuleVersion('pathsim');
+	} catch {
+		cached = null;
+	}
+	primed = true;
+}
+
+/** Synchronous accessor. Returns null until `primePathsimVersion` has run. */
+export function getCachedPathsimVersion(): string | null {
+	return cached;
+}
diff --git a/src/lib/toolbox/python.ts b/src/lib/toolbox/python.ts
index 97a176a1..2ebcac21 100644
--- a/src/lib/toolbox/python.ts
+++ b/src/lib/toolbox/python.ts
@@ -127,6 +127,34 @@ def pathview_uninstall(import_path):
     return {"ok": True, "dropped": _pv_drop_module(import_path)}
 
 
+def _pv_module_version(import_path):
+    """Best-effort version lookup for an imported module.
+    Tries module.__version__ first, falls back to importlib.metadata,
+    returns None if nothing works."""
+    try:
+        mod = _pv_importlib.import_module(import_path)
+    except Exception:
+        return None
+    v = getattr(mod, "__version__", None)
+    if isinstance(v, str) and v:
+        return v
+    try:
+        import importlib.metadata as _pv_md
+    except Exception:
+        return None
+    # Walk up the dotted path so submodule imports still resolve to their
+    # owning distribution (e.g. pathsim_chem.blocks → pathsim-chem).
+    parts = import_path.split(".")
+    for i in range(len(parts), 0, -1):
+        candidate = parts[0] if i == 1 else ".".join(parts[:i])
+        for name in (candidate, candidate.replace("_", "-"), candidate.replace("-", "_")):
+            try:
+                return _pv_md.version(name)
+            except Exception:
+                continue
+    return None
+
+
 _pv_helpers_loaded = True
 `;
 
diff --git a/src/lib/toolbox/register.ts b/src/lib/toolbox/register.ts
index 56eb5175..1c8f8e90 100644
--- a/src/lib/toolbox/register.ts
+++ b/src/lib/toolbox/register.ts
@@ -20,6 +20,7 @@ import {
 	loadInlineModule,
 	introspectBlocks,
 	introspectEvents,
+	getModuleVersion,
 	uninstallModule,
 	type IntrospectedBlock,
 	type IntrospectedEvent
@@ -82,7 +83,12 @@ function asShape(value: string | undefined): NodeShape | undefined {
 }
 
 /** Build a node definition from one introspected block + the user's selection. */
-function buildBlockDefinition(block: IntrospectedBlock, selection: BlockSelection, fallbackCategory: string) {
+function buildBlockDefinition(
+	block: IntrospectedBlock,
+	selection: BlockSelection,
+	fallbackCategory: string,
+	importPath: string
+) {
 	const { ports: inputs, max: maxInputs } = resolvePorts(block.inputs);
 	const { ports: outputs, max: maxOutputs } = resolvePorts(block.outputs);
 
@@ -99,6 +105,7 @@ function buildBlockDefinition(block: IntrospectedBlock, selection: BlockSelectio
 		name: selection.override?.name ?? block.className,
 		category: selection.override?.category ?? fallbackCategory,
 		blockClass: block.className,
+		importPath,
 		description: block.description,
 		inputs,
 		outputs,
@@ -144,27 +151,27 @@ function buildEventDefinition(event: IntrospectedEvent, selection: EventSelectio
 export async function performInstall(
 	source: ToolboxConfig['source'],
 	requestedImportPath?: string
-): Promise<{ importPath: string }> {
+): Promise<{ importPath: string; installedVersion: string | null }> {
+	let importPath: string;
 	if (source.type === 'pypi') {
 		const spec = source.version ? `${source.pkg}==${source.version}` : source.pkg;
 		// Default to the package name with `_` if caller didn't specify.
-		const importPath = requestedImportPath ?? source.pkg.replace(/-/g, '_');
+		importPath = requestedImportPath ?? source.pkg.replace(/-/g, '_');
 		await installPackage(spec, importPath);
-		return { importPath };
-	}
-	if (source.type === 'url') {
+	} else if (source.type === 'url') {
 		if (!requestedImportPath) {
 			throw new Error('importPath is required when installing from URL');
 		}
 		await installPackage(source.url, requestedImportPath);
-		return { importPath: requestedImportPath };
-	}
-	if (source.type === 'inline') {
+		importPath = requestedImportPath;
+	} else if (source.type === 'inline') {
 		const baseName = source.filename.replace(/\.py$/, '').replace(/[^A-Za-z0-9_]/g, '_');
-		const moduleName = await loadInlineModule(baseName, source.code);
-		return { importPath: moduleName };
+		importPath = await loadInlineModule(baseName, source.code);
+	} else {
+		throw new Error(`Unknown toolbox source type: ${(source as { type: string }).type}`);
 	}
-	throw new Error(`Unknown toolbox source type: ${(source as { type: string }).type}`);
+	const installedVersion = await getModuleVersion(importPath);
+	return { importPath, installedVersion };
 }
 
 /**
@@ -226,7 +233,7 @@ export function registerToolbox(
 			options.categoryByClass?.[sel.className] ??
 			options.defaultCategory ??
 			config.displayName;
-		const def = buildBlockDefinition(block, sel, fallbackCategory);
+		const def = buildBlockDefinition(block, sel, fallbackCategory, config.importPath);
 		nodeRegistry.register(def, config.id);
 	}
 
diff --git a/src/lib/toolbox/types.ts b/src/lib/toolbox/types.ts
index b1b6ab38..1013a019 100644
--- a/src/lib/toolbox/types.ts
+++ b/src/lib/toolbox/types.ts
@@ -65,6 +65,10 @@ export interface ToolboxConfig {
 	blocks: BlockSelection[];
 	/** Per-event selections + overrides. */
 	events: EventSelection[];
+	/** Version actually installed (read from `module.__version__` or
+	 *  `importlib.metadata`). Populated post-install / post-bootstrap.
+	 *  Distinct from `source.version`, which pins the install spec when set. */
+	installedVersion?: string | null;
 }
 
 /** Versioned envelope persisted to localStorage. */
diff --git a/src/lib/types/nodes.ts b/src/lib/types/nodes.ts
index 49969a86..5a1b8594 100644
--- a/src/lib/types/nodes.ts
+++ b/src/lib/types/nodes.ts
@@ -73,6 +73,13 @@ export interface NodeTypeDefinition {
 	// PathSim block class name for export
 	blockClass: string;
 
+	// Python module to import the block class from. Built-in pathsim blocks
+	// can leave this undefined and codegen falls back to the static
+	// `blockImportPaths` map; runtime-toolbox blocks set this to their
+	// toolbox config's importPath so the generated code says
+	// `from pathsim_chem import GLC` instead of `from pathsim.blocks import GLC`.
+	importPath?: string;
+
 	// Full RST docstring from PathSim (for documentation display)
 	docstring?: string;
 
diff --git a/src/lib/types/schema.ts b/src/lib/types/schema.ts
index 9fd01306..92b6cf0b 100644
--- a/src/lib/types/schema.ts
+++ b/src/lib/types/schema.ts
@@ -13,6 +13,9 @@ export interface FileMetadata {
 	modified: string;
 	name: string;
 	description?: string;
+	/** Pathsim version installed when the file was saved. Used at load
+	 *  time to warn the user if their pathsim differs significantly. */
+	pathsimVersion?: string | null;
 }
 
 /**
@@ -29,6 +32,10 @@ export interface ToolboxRequirement {
 	source: ToolboxSource;
 	importPath: string;
 	eventsImportPath?: string;
+	/** Version actually installed on the machine that saved this file
+	 *  (read from `module.__version__` / `importlib.metadata`). The loader
+	 *  offers to pin to this version for reproducibility. */
+	installedVersion?: string | null;
 }
 
 /** Shared graph content structure (used by GraphFile and ModelContent) */
diff --git a/src/lib/utils/codePreviewHeader.ts b/src/lib/utils/codePreviewHeader.ts
index 5c0065fe..a3b9444a 100644
--- a/src/lib/utils/codePreviewHeader.ts
+++ b/src/lib/utils/codePreviewHeader.ts
@@ -135,10 +135,14 @@ export function generateBlockCodeHeader(node: NodeInstance, codeContext: string)
 		const blockClasses = new Set<string>();
 		collectSubsystemBlockClasses(node, blockClasses);
 		if (blockClasses.size > 0) {
-			// Group block classes by import path
+			// Group block classes by import path. Toolbox-registered blocks
+			// carry their own importPath in the typeDef; built-ins fall back
+			// to the static map.
 			const importGroups = new Map<string, string[]>();
 			for (const cls of [...blockClasses].sort()) {
-				const importPath = blockImportPaths[cls] || 'pathsim.blocks';
+				const def = nodeRegistry.get(cls);
+				const importPath =
+					def?.importPath ?? blockImportPaths[cls] ?? 'pathsim.blocks';
 				const group = importGroups.get(importPath) || [];
 				group.push(cls);
 				importGroups.set(importPath, group);
@@ -148,7 +152,8 @@ export function generateBlockCodeHeader(node: NodeInstance, codeContext: string)
 			}
 		}
 	} else {
-		const importPath = blockImportPaths[typeDef.blockClass] || 'pathsim.blocks';
+		const importPath =
+			typeDef.importPath ?? blockImportPaths[typeDef.blockClass] ?? 'pathsim.blocks';
 		lines.push(`from ${importPath} import ${typeDef.blockClass}`);
 	}
 
diff --git a/src/routes/+page.svelte b/src/routes/+page.svelte
index e73399fa..4e2c4928 100644
--- a/src/routes/+page.svelte
+++ b/src/routes/+page.svelte
@@ -507,13 +507,17 @@
 		// Bring up the Python backend the moment the page loads so the
 		// runtime is ready by the time the user clicks Run. Order matters:
 		// detect the active backend first, then initialise it, then run
-		// the toolbox bootstrap on top.
+		// the toolbox bootstrap on top. The URL-param model load runs at
+		// the end so toolbox blocks are registered in nodeRegistry by the
+		// time BaseNode tries to resolve them — otherwise blocks from
+		// installed-but-not-yet-bootstrapped toolboxes render as (missing).
 		(async () => {
 			try {
 				await autoDetectBackend();
 				await initBackendFromUrl();
 				await initPyodide();
 				await bootstrapToolboxes();
+				await loadFromUrlParam();
 			} catch (e) {
 				console.error('[startup]', e);
 			}
@@ -634,9 +638,6 @@
 		window.addEventListener('run-simulation', handleRunSimulation);
 		window.addEventListener('continue-simulation', handleContinueSimulation);
 
-		// Check for URL parameters to load model
-		loadFromUrlParam();
-
 		return () => {
 			// Cleanup store subscriptions
 			unsubPinnedPreviews();