dynsim 0.1.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "dynsim",
+  "version": "0.1.0",
+  "description": "Interactive dynamical systems simulator with PyScript/Python integration and Plotly visualization",
+  "type": "module",
+  "main": "dist/dynsim.umd.js",
+  "module": "dist/dynsim.esm.js",
+  "unpkg": "dist/dynsim.umd.js",
+  "jsdelivr": "dist/dynsim.umd.js",
+  "exports": {
+    ".": {
+      "import": "./dist/dynsim.esm.js",
+      "require": "./dist/dynsim.umd.js",
+      "default": "./dist/dynsim.esm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "dynamical-systems",
+    "simulation",
+    "plotly",
+    "pyscript",
+    "visualization",
+    "interactive"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "plotly.js-dist": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "plotly.js-dist": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "vitest": "^4.1.0"
+  }
+}

package/src/controller.js

@@ -0,0 +1,100 @@
+/**
+ * SimulationController — wires Simulation + SimulationView.
+ *
+ * Owns the requestAnimationFrame loop. Each tick:
+ * reads input from view → calls simulation.step() → updates view.
+ */
+import { Simulation } from './simulation.js';
+import { SimulationView } from './view.js';
+
+export class SimulationController {
+  /**
+   * @param {object} options
+   * @param {HTMLElement} options.container - DOM element for the simulation view
+   * @param {object} options.config - Parsed system config (from registry)
+   * @param {function} options.stepProvider - () => stepFunction
+   */
+  constructor({ container, config, stepProvider }) {
+    this.isRunning = true;
+    this.animationId = null;
+
+    this.simulation = new Simulation(config, stepProvider);
+
+    this.view = new SimulationView({
+      container,
+      params: config.params,
+      initialX: config.initialX ?? 0,
+      height: config.height || 400,
+      plotType: config.plotType || 'timeseries',
+      plotConfig: config.plotConfig || {},
+      spikeThreshold: config.spikeThreshold ?? null,
+      callbacks: {
+        onReset: () => this.reset(),
+        onPauseToggle: () => this.togglePause()
+      }
+    });
+  }
+
+  start() {
+    if (this.animationId) {
+      cancelAnimationFrame(this.animationId);
+    }
+    this.animate();
+  }
+
+  stop() {
+    if (this.animationId) {
+      cancelAnimationFrame(this.animationId);
+      this.animationId = null;
+    }
+  }
+
+  reset() {
+    this.simulation.reset();
+    this.view.initPlot();
+  }
+
+  togglePause() {
+    this.isRunning = !this.isRunning;
+    // Clear pause time so the simulation can continue past it
+    if (this.isRunning && this.simulation.paused) {
+      this.simulation.pauseTime = null;
+    }
+    this.view.setPauseState(this.isRunning);
+  }
+
+  animate() {
+    if (this.isRunning && !this.simulation.paused) {
+      const inputValue = this.view.getInput();
+      const paramValues = this.view.getParameters();
+
+      try {
+        this.simulation.step(inputValue, paramValues);
+      } catch (e) {
+        console.error('[DynSim] Step error:', e);
+        this.stop();
+        return;
+      }
+
+      // Auto-pause when pause time is reached
+      if (this.simulation.paused) {
+        this.isRunning = false;
+        this.view.setPauseState(false);
+      }
+    }
+
+    const plotArrays = this.simulation.getPlotArrays();
+    const xRange = this.simulation.plotType === 'timeseries'
+      ? this.simulation.getTimeseriesRange()
+      : undefined;
+    const spikeTimes = this.simulation.spikes ? this.simulation.spikeTimes : undefined;
+    this.view.updatePlot(plotArrays, xRange, spikeTimes);
+
+    this.animationId = requestAnimationFrame(() => this.animate());
+  }
+
+  destroy() {
+    this.stop();
+    this.view.destroy();
+  }
+}

package/src/editor.js

@@ -0,0 +1,131 @@
+/**
+ * CodeEditor — in-page Python code editor with live replacement.
+ *
+ * Provides a textarea for editing the Python step function definition.
+ * On "Apply", re-executes the code via PyScript/Pyodide and updates
+ * the step function in the registry. The simulation continues
+ * seamlessly with the new dynamics on the next tick.
+ */
+import * as registry from './registry.js';
+
+export class CodeEditor {
+  /**
+   * @param {object} options
+   * @param {HTMLElement} options.container - DOM element to render the editor into
+   * @param {string} options.containerId - The simulation container ID (registry key)
+   * @param {string} options.initialCode - Initial Python source code
+   * @param {function} options.executePython - (code, containerId, config) => void
+   *   Function that executes Python code in the PyScript/Pyodide runtime.
+   *   The code should call registerPythonSystem which updates the registry.
+   */
+  constructor({ container, containerId, initialCode, executePython }) {
+    this.container = container;
+    this.containerId = containerId;
+    this.initialCode = initialCode || '';
+    this.executePython = executePython;
+    this.textarea = null;
+    this.statusEl = null;
+
+    this.render();
+  }
+
+  render() {
+    this.container.innerHTML = `
+      <div class="dynsim-editor" style="font-family: Arial, sans-serif; font-size: 0.9em; margin-bottom: 12px;">
+        <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 6px;">
+          <label style="font-weight: 600; font-size: 0.85em;">Python System Definition</label>
+          <div style="display: flex; gap: 8px; align-items: center;">
+            <span class="dynsim-editor-status" style="font-size: 0.8em; color: #666;"></span>
+            <button class="dynsim-editor-apply" style="
+              background: #0056b3; color: white; border: none; border-radius: 4px;
+              padding: 4px 12px; cursor: pointer; font-size: 0.85em;
+            ">Apply</button>
+            <button class="dynsim-editor-reset" style="
+              background: #6c757d; color: white; border: none; border-radius: 4px;
+              padding: 4px 12px; cursor: pointer; font-size: 0.85em;
+            ">Reset Code</button>
+          </div>
+        </div>
+        <textarea class="dynsim-editor-textarea" style="
+          width: 100%; min-height: 200px; font-family: monospace; font-size: 0.9em;
+          padding: 8px; border: 1px solid #ddd; border-radius: 6px;
+          box-sizing: border-box; resize: vertical; tab-size: 4;
+        " spellcheck="false">${this._escapeHtml(this.initialCode)}</textarea>
+      </div>
+    `;
+
+    this.textarea = this.container.querySelector('.dynsim-editor-textarea');
+    this.statusEl = this.container.querySelector('.dynsim-editor-status');
+
+    this.container.querySelector('.dynsim-editor-apply')
+      .addEventListener('click', () => this.apply());
+
+    this.container.querySelector('.dynsim-editor-reset')
+      .addEventListener('click', () => this.resetCode());
+
+    // Tab key inserts spaces instead of changing focus
+    this.textarea.addEventListener('keydown', (e) => {
+      if (e.key === 'Tab') {
+        e.preventDefault();
+        const start = this.textarea.selectionStart;
+        const end = this.textarea.selectionEnd;
+        this.textarea.value =
+          this.textarea.value.substring(0, start) +
+          '    ' +
+          this.textarea.value.substring(end);
+        this.textarea.selectionStart = this.textarea.selectionEnd = start + 4;
+      }
+    });
+  }
+
+  /**
+   * Re-execute the current code and update the registry.
+   */
+  apply() {
+    const code = this.textarea.value;
+    const config = registry.getConfig(this.containerId);
+
+    try {
+      this.executePython(code, this.containerId, config);
+      this._setStatus('Applied', 'green');
+    } catch (e) {
+      console.error('[DynSim Editor] Error applying code:', e);
+      this._setStatus('Error: ' + e.message, 'red');
+    }
+  }
+
+  /**
+   * Reset the textarea to the initial code.
+   */
+  resetCode() {
+    this.textarea.value = this.initialCode;
+    this._setStatus('Reset to original', '#666');
+  }
+
+  /**
+   * Get the current code from the editor.
+   * @returns {string}
+   */
+  getCode() {
+    return this.textarea.value;
+  }
+
+  _setStatus(text, color) {
+    this.statusEl.textContent = text;
+    this.statusEl.style.color = color;
+    // Clear status after 3 seconds
+    setTimeout(() => {
+      if (this.statusEl.textContent === text) {
+        this.statusEl.textContent = '';
+      }
+    }, 3000);
+  }
+
+  _escapeHtml(str) {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+}

package/src/index.js

@@ -0,0 +1,126 @@
+/**
+ * dynsim — Interactive dynamical systems simulator.
+ *
+ * ES module entry point. Exports all public API.
+ */
+export { Simulation } from './simulation.js';
+export { SimulationView } from './view.js';
+export { SimulationController } from './controller.js';
+export { CodeEditor } from './editor.js';
+export * as registry from './registry.js';
+export { pyToJs, injectPythonBridge } from './pybridge.js';
+
+import { SimulationController } from './controller.js';
+import * as registry from './registry.js';
+
+/**
+ * Auto-initialize: expose globals for PyScript interop and
+ * bootstrap PyScript containers. Called automatically by the UMD build.
+ * Call manually when using as an ES module if you need the legacy behavior.
+ */
+export async function autoInit() {
+  // Expose globals for PyScript interop
+  window.pythonSystems = {};
+  window.dynSimConfigs = {};
+
+  // JS-side registration — called by the Python bridge wrapper.
+  // The Python bridge (injected by injectPythonBridge) redefines
+  // window.registerPythonSystem to wrap step functions with to_py()
+  // conversion, then calls this function.
+  window._dynsimJsRegister = function (containerId, stepFunction, config) {
+    console.log('[DynSim] Registering Python system:', containerId);
+    registry.register(containerId, stepFunction, config);
+
+    if (document.readyState === 'complete' && typeof Plotly !== 'undefined') {
+      initializeContainer(containerId);
+    }
+  };
+
+  // Fallback: if the Python bridge hasn't loaded, provide a direct JS registration
+  if (!window.registerPythonSystem) {
+    window.registerPythonSystem = window._dynsimJsRegister;
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', async () => {
+      await setupPyScriptContainers();
+      initializeAllContainers();
+    });
+  } else {
+    await setupPyScriptContainers();
+    initializeAllContainers();
+  }
+}
+
+// --- Internal helpers for autoInit ---
+
+const controllers = {};
+
+function initializeContainer(containerId) {
+  const container = document.getElementById(containerId);
+  if (!container || container.querySelector('.dynsim-container')) return;
+
+  const config = registry.getConfig(containerId);
+  if (!config) return;
+
+  controllers[containerId] = new SimulationController({
+    container,
+    config,
+    stepProvider: () => registry.getStep(containerId)
+  });
+  controllers[containerId].start();
+}
+
+function initializeAllContainers() {
+  let attempts = 0;
+  const MAX_ATTEMPTS = 20;
+
+  function tryInit() {
+    attempts++;
+    if (typeof Plotly === 'undefined') {
+      if (attempts < MAX_ATTEMPTS) setTimeout(tryInit, 50);
+      return;
+    }
+
+    const ids = registry.getContainerIds();
+    if (ids.length === 0 && attempts < MAX_ATTEMPTS) {
+      setTimeout(tryInit, 50);
+      return;
+    }
+
+    ids.forEach(initializeContainer);
+  }
+
+  tryInit();
+}
+
+async function setupPyScriptContainers() {
+  // Wait for data file
+  let attempts = 0;
+  while (!window.dynSimSystemsData && attempts < 20) {
+    await new Promise(resolve => setTimeout(resolve, 500));
+    attempts++;
+  }
+  if (!window.dynSimSystemsData) return;
+
+  // Wait for PyScript bootstrap
+  attempts = 0;
+  while (!window.executeDynSimCode && attempts < 40) {
+    await new Promise(resolve => setTimeout(resolve, 500));
+    attempts++;
+  }
+  if (!window.executeDynSimCode) return;
+
+  const containers = document.querySelectorAll('.dynsim-python-container');
+  for (const container of containers) {
+    const systemData = window.dynSimSystemsData[container.id];
+    if (!systemData) continue;
+
+    try {
+      window.dynSimConfigs[container.id] = systemData.config;
+      window.executeDynSimCode(systemData.pythonCode, container.id, systemData.config);
+    } catch (e) {
+      console.error('[DynSim] Error processing container:', container.id, e);
+    }
+  }
+}

package/src/pybridge.js

@@ -0,0 +1,67 @@
+/**
+ * PyBridge — transparent type conversion between JS and Python (Pyodide).
+ *
+ * Injects a Python-side bridge script that wraps step functions so that
+ * JS objects are automatically converted to Python dicts before the user's
+ * step function is called. Neither side needs to know about the other.
+ *
+ * Flow:
+ * 1. UMD load → injectPythonBridge() inserts <script type="py"> into DOM
+ * 2. PyScript processes it before user scripts (document order)
+ * 3. Python bridge redefines window.registerPythonSystem to wrap step functions
+ * 4. User's Python code calls registerPythonSystem as normal
+ * 5. The wrapper converts JsProxy args to Python dicts, calls real step,
+ *    and returns the result
+ */
+
+const PYTHON_BRIDGE = `
+def _dynsim_init_bridge():
+    from pyscript import window as _w
+    from pyodide.ffi import create_proxy, to_js
+    from js import Object
+
+    _js_register = _w._dynsimJsRegister
+
+    def _register(container_id, step_fn, config):
+        def wrapped_step(x, state, params):
+            # Convert JS inputs to Python dicts
+            s = state.to_py() if hasattr(state, 'to_py') else state
+            p = params.to_py() if hasattr(params, 'to_py') else params
+            result = step_fn(float(x), s, p)
+            # Convert Python outputs to plain JS objects
+            return to_js(result, dict_converter=Object.fromEntries)
+        # create_proxy prevents the wrapped function from being garbage collected
+        # after this call returns — it's called repeatedly from requestAnimationFrame
+        _js_register(container_id, create_proxy(wrapped_step), config)
+
+    _w.registerPythonSystem = _register
+
+_dynsim_init_bridge()
+del _dynsim_init_bridge
+`;
+
+/**
+ * Inject the Python bridge script into the DOM.
+ * Must be called synchronously during UMD script load (before PyScript processes scripts).
+ */
+export function injectPythonBridge() {
+  const script = document.createElement('script');
+  script.type = 'py';
+  script.textContent = PYTHON_BRIDGE;
+  // Insert as first child of <head> so it runs before user's <script type="py"> tags
+  document.head.insertBefore(script, document.head.firstChild);
+}
+
+/**
+ * Convert a Python proxy value to a plain JS value.
+ */
+export function pyToJs(value) {
+  if (value != null && typeof value.toJs === 'function') {
+    try {
+      return value.toJs({ dict_converter: Object.fromEntries });
+    } catch {
+      try { return value.toJs(); } catch {}
+    }
+  }
+  return value;
+}

package/src/registry.js

@@ -0,0 +1,102 @@
+/**
+ * Registry for step functions, keyed by container ID.
+ *
+ * Supports live replacement: update a step function at any time
+ * and the next simulation tick will pick it up via the stepProvider pattern.
+ */
+
+const systems = {};
+
+/**
+ * Ensure a value is a plain JS object (not a PyProxy or other foreign wrapper).
+ * Uses Pyodide's toJs() if available, otherwise falls back to JSON round-trip.
+ */
+function toPlainObject(value) {
+  if (value == null) return value;
+  // Pyodide PyProxy — use toJs with dict_converter for proper dict→object conversion
+  if (typeof value.toJs === 'function') {
+    try {
+      return value.toJs({ dict_converter: Object.fromEntries });
+    } catch {
+      try { return value.toJs(); } catch {}
+    }
+  }
+  // Fallback: JSON round-trip (works for plain JS objects)
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Register (or replace) a step function and config for a container.
+ * @param {string} containerId
+ * @param {function} stepFunction - step(x, state, params) => [x_new, state_new]
+ * @param {object} rawConfig - Config object (plain JS or Python dict proxy — converted implicitly)
+ */
+export function register(containerId, stepFunction, rawConfig) {
+  // Convert potential PyProxy to plain JS object
+  const cfg = toPlainObject(rawConfig);
+  systems[containerId] = {
+    step: stepFunction,
+    config: {
+      params: typeof cfg.params === 'string' ? JSON.parse(cfg.params) : (cfg.params || []),
+      plotType: cfg.plotType || 'timeseries',
+      plotConfig: typeof cfg.plotConfig === 'string' ? JSON.parse(cfg.plotConfig) : (cfg.plotConfig || {}),
+      initialState: typeof cfg.initialState === 'string' ? JSON.parse(cfg.initialState) : (cfg.initialState || { t: 0 }),
+      initialX: cfg.initialX ?? 0,
+      height: cfg.height || 400,
+      dt: cfg.dt || 0.01,
+      pauseTime: cfg.pauseTime ?? null,
+      spikes: cfg.spikes || null,
+      spikeThreshold: cfg.spikeThreshold ?? null
+    }
+  };
+}
+
+/**
+ * Get the current step function for a container.
+ * @param {string} containerId
+ * @returns {function|null}
+ */
+export function getStep(containerId) {
+  return systems[containerId]?.step || null;
+}
+
+/**
+ * Get the parsed config for a container.
+ * @param {string} containerId
+ * @returns {object|null}
+ */
+export function getConfig(containerId) {
+  return systems[containerId]?.config || null;
+}
+
+/**
+ * Replace just the step function (for live code editing).
+ * @param {string} containerId
+ * @param {function} stepFunction
+ */
+export function replaceStep(containerId, stepFunction) {
+  if (systems[containerId]) {
+    systems[containerId].step = stepFunction;
+  }
+}
+
+/**
+ * Get all registered container IDs.
+ * @returns {string[]}
+ */
+export function getContainerIds() {
+  return Object.keys(systems);
+}
+
+/**
+ * Check if a container is registered.
+ * @param {string} containerId
+ * @returns {boolean}
+ */
+export function has(containerId) {
+  return containerId in systems;
+}