stone-lang 0.1.0

package/frontend/parsing/terminal-registry.js

@@ -0,0 +1,435 @@
+/**
+ * Terminal Registry
+ *
+ * Provides terminal handle class and constructor factories for Stone terminals.
+ * Terminals are first-class runtime objects that represent output channels
+ * (2D graphs, 3D scenes).
+ *
+ * Supports two modes:
+ * - Legacy: Direct executor.terminalsData mutation (backward compat)
+ * - Adapter: Stream via OutputAdapter (new CLI/daemon path)
+ */
+
+import { StoneArray } from '../../backends/js-vm/stoneArray.js';
+
+// ============================================================================
+// STONEARRAY CONVERSION UTILITIES
+// ============================================================================
+
+/**
+ * Check if a value is a StoneArray
+ */
+function isStoneArray(value) {
+  return value instanceof StoneArray || value?._type === 'StoneArray';
+}
+
+/**
+ * Convert a StoneArray to a plain JavaScript array.
+ * Uses the built-in toNested() method for proper conversion.
+ */
+function stoneArrayToJS(arr) {
+  if (!isStoneArray(arr)) return arr;
+
+  // Use the built-in toNested() method if available (live StoneArray)
+  if (typeof arr.toNested === 'function') {
+    return arr.toNested();
+  }
+
+  // Fallback: handle raw data directly
+  const data = ArrayBuffer.isView(arr.data) ? Array.from(arr.data) : arr.data;
+
+  if (arr.rank === 1) {
+    return Array.isArray(data) ? data : Array.from(data);
+  }
+
+  if (arr.rank === 2) {
+    const [rows, cols] = arr.shape;
+    const result = [];
+    for (let i = 0; i < rows; i++) {
+      result.push(data.slice(i * cols, (i + 1) * cols));
+    }
+    return result;
+  }
+
+  return data;
+}
+
+/**
+ * Recursively convert all StoneArrays in an object to plain JS arrays.
+ * This ensures data is stored in a format that serializes correctly to JSON
+ * and can be used directly by Plotly without further conversion.
+ */
+function deepConvertStoneArrays(obj) {
+  if (obj === null || obj === undefined) return obj;
+
+  // If it's a StoneArray, convert it
+  if (isStoneArray(obj)) {
+    return stoneArrayToJS(obj);
+  }
+
+  // If it's an array, recursively convert each element
+  if (Array.isArray(obj)) {
+    return obj.map(deepConvertStoneArrays);
+  }
+
+  // If it's an object, recursively convert each property
+  if (typeof obj === 'object') {
+    const result = {};
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        result[key] = deepConvertStoneArrays(obj[key]);
+      }
+    }
+    return result;
+  }
+
+  // Primitive values pass through unchanged
+  return obj;
+}
+
+/**
+ * TerminalHandle - Handle to a terminal instance
+ *
+ * Represents a reference to a terminal that can be used to send data
+ * via method calls: graph.add(data), graph.set(data), scene.add(obj), etc.
+ */
+export class TerminalHandle {
+  /**
+   * @param {string} type - Terminal type ('console', 'graph2d', 'graph3d')
+   * @param {Object} config - Terminal configuration
+   * @param {string} id - Unique terminal ID
+   * @param {Object} context - Either { executor } (legacy) or { outputAdapter } (new)
+   */
+  constructor(type, config, id, context) {
+    this._type = 'TerminalHandle';
+    this.terminalType = type;
+    this.terminalId = id;
+    this.config = config || {};
+    this.ports = {}; // View port data (snapshots)
+
+    // Support both legacy executor mode and new adapter mode
+    if (context.outputAdapter) {
+      this.outputAdapter = context.outputAdapter;
+      this.executor = null;
+      // In adapter mode, ports are managed locally
+      this._initPorts();
+    } else if (context.executor) {
+      // Legacy mode - direct executor mutation
+      this.executor = context.executor;
+      this.outputAdapter = null;
+    } else {
+      throw new Error('TerminalHandle requires either executor or outputAdapter');
+    }
+  }
+
+  _initPorts() {
+    switch (this.terminalType) {
+      case 'graph2d':
+        this.ports.plots = [];
+        break;
+      case 'graph3d':
+        this.ports.objects = [];
+        break;
+      case 'console':
+        this.ports.lines = [];
+        break;
+    }
+    this.ports.config = { ...this.config };
+  }
+
+  /**
+   * Add data to the terminal's main port
+   * - graph2d: adds plot(s) to plots
+   * - graph3d: adds object(s) to objects
+   * - console: adds line(s) to lines
+   *
+   * If value is an array, adds each item. Otherwise adds the single item.
+   * StoneArrays are converted to plain JS arrays for proper JSON serialization.
+   */
+  add(value) {
+    // Convert StoneArrays to plain JS arrays before storing
+    const converted = deepConvertStoneArrays(value);
+    const items = Array.isArray(converted) ? converted : [converted];
+
+    if (this.outputAdapter) {
+      // New adapter mode - stream via adapter
+      this.outputAdapter.addToTerminal(this.terminalId, items);
+      // Also update local ports for consistency
+      this._addToLocalPorts(items);
+    } else {
+      // Legacy mode - direct mutation
+      const terminalData = this.executor.terminalsData[this.terminalId];
+      switch (this.terminalType) {
+        case 'graph2d':
+          terminalData.plots.push(...items);
+          this.ports.plots = [...terminalData.plots];
+          break;
+        case 'graph3d':
+          terminalData.objects.push(...items);
+          this.ports.objects = [...terminalData.objects];
+          break;
+        case 'console':
+          terminalData.lines.push(...items);
+          this.ports.lines = [...terminalData.lines];
+          break;
+      }
+    }
+    return this; // Enable chaining
+  }
+
+  _addToLocalPorts(items) {
+    switch (this.terminalType) {
+      case 'graph2d':
+        this.ports.plots.push(...items);
+        break;
+      case 'graph3d':
+        this.ports.objects.push(...items);
+        break;
+      case 'console':
+        this.ports.lines.push(...items);
+        break;
+    }
+  }
+
+  /**
+   * Set the terminal's main port data (replaces existing)
+   * - graph2d: sets plots array
+   * - graph3d: sets objects array
+   * - console: sets lines array
+   * StoneArrays are converted to plain JS arrays for proper JSON serialization.
+   */
+  set(value) {
+    // Convert StoneArrays to plain JS arrays before storing
+    const converted = deepConvertStoneArrays(value);
+    const arr = Array.isArray(converted) ? converted : [converted];
+
+    if (this.outputAdapter) {
+      // New adapter mode - stream via adapter
+      this.outputAdapter.setTerminal(this.terminalId, arr);
+      // Also update local ports for consistency
+      this._setLocalPorts(arr);
+    } else {
+      // Legacy mode - direct mutation
+      const terminalData = this.executor.terminalsData[this.terminalId];
+      switch (this.terminalType) {
+        case 'graph2d':
+          terminalData.plots = arr;
+          this.ports.plots = [...terminalData.plots];
+          break;
+        case 'graph3d':
+          terminalData.objects = arr;
+          this.ports.objects = [...terminalData.objects];
+          break;
+        case 'console':
+          terminalData.lines = arr;
+          this.ports.lines = [...terminalData.lines];
+          break;
+      }
+    }
+    return this;
+  }
+
+  _setLocalPorts(arr) {
+    switch (this.terminalType) {
+      case 'graph2d':
+        this.ports.plots = [...arr];
+        break;
+      case 'graph3d':
+        this.ports.objects = [...arr];
+        break;
+      case 'console':
+        this.ports.lines = [...arr];
+        break;
+    }
+  }
+
+  /**
+   * Clear all data from the terminal's main port
+   */
+  clear() {
+    if (this.outputAdapter) {
+      // New adapter mode - stream via adapter
+      this.outputAdapter.clearTerminal(this.terminalId);
+      // Also update local ports
+      this._clearLocalPorts();
+    } else {
+      // Legacy mode - direct mutation
+      const terminalData = this.executor.terminalsData[this.terminalId];
+      switch (this.terminalType) {
+        case 'graph2d':
+          terminalData.plots = [];
+          this.ports.plots = [];
+          break;
+        case 'graph3d':
+          terminalData.objects = [];
+          this.ports.objects = [];
+          break;
+        case 'console':
+          terminalData.lines = [];
+          this.ports.lines = [];
+          break;
+      }
+    }
+    return this;
+  }
+
+  _clearLocalPorts() {
+    switch (this.terminalType) {
+      case 'graph2d':
+        this.ports.plots = [];
+        break;
+      case 'graph3d':
+        this.ports.objects = [];
+        break;
+      case 'console':
+        this.ports.lines = [];
+        break;
+    }
+  }
+
+  // Custom serialization - exclude executor/adapter reference
+  toJSON() {
+    return {
+      _type: this._type,
+      terminalType: this.terminalType,
+      terminalId: this.terminalId,
+      config: this.config,
+      ports: this.ports
+    };
+  }
+}
+
+/**
+ * Create terminal constructor functions.
+ *
+ * Supports two modes:
+ * - Legacy: Pass executor object with terminalsData and terminalCounter
+ * - Adapter: Pass object with outputAdapter and terminalCounter
+ *
+ * @param {Object} context - Either executor (legacy) or { outputAdapter, terminalCounter } (new)
+ * @returns {Object} - Object with console_terminal, graph2d, graph3d functions
+ */
+export function createTerminalConstructors(context) {
+  // Determine mode based on what's provided
+  // Check for both null and undefined to properly detect adapter mode
+  const isAdapterMode = context.outputAdapter != null;
+
+  // Get or create terminal counter
+  let counterRef;
+  if (isAdapterMode) {
+    // Adapter mode - counter passed in context or create new one
+    counterRef = { value: context.terminalCounter || 0 };
+  } else {
+    // Legacy mode - counter is on executor
+    counterRef = { get value() { return context.terminalCounter; }, set value(v) { context.terminalCounter = v; } };
+  }
+
+  const getNextId = (prefix) => {
+    const id = `${prefix}_${counterRef.value}`;
+    counterRef.value++;
+    return id;
+  };
+
+  return {
+    console_terminal: (config = {}) => {
+      const terminalId = getNextId('console');
+      const fullConfig = {
+        title: config.title || 'Console',
+        max_lines: config.max_lines || 200,
+        ...config
+      };
+
+      if (isAdapterMode) {
+        // New adapter mode - create via adapter
+        context.outputAdapter.createTerminal(terminalId, 'console', fullConfig);
+        return new TerminalHandle('console', fullConfig, terminalId, { outputAdapter: context.outputAdapter });
+      } else {
+        // Legacy mode - direct mutation
+        const handle = new TerminalHandle('console', fullConfig, terminalId, { executor: context });
+        context.terminalsData[terminalId] = {
+          type: 'console',
+          config: fullConfig,
+          lines: []
+        };
+        handle.ports = {
+          lines: [],
+          config: { ...fullConfig }
+        };
+        return handle;
+      }
+    },
+
+    graph2d: (config = {}) => {
+      const terminalId = getNextId('graph2d');
+      // Convert StoneArrays in config (e.g., axes.t.values) to plain JS arrays
+      const fullConfig = deepConvertStoneArrays({
+        title: config.title || 'Graph',
+        x_label: config.x_label || 'x',
+        y_label: config.y_label || 'y',
+        ...config
+      });
+
+      if (isAdapterMode) {
+        // New adapter mode - create via adapter
+        context.outputAdapter.createTerminal(terminalId, 'graph2d', fullConfig);
+        return new TerminalHandle('graph2d', fullConfig, terminalId, { outputAdapter: context.outputAdapter });
+      } else {
+        // Legacy mode - direct mutation
+        const handle = new TerminalHandle('graph2d', fullConfig, terminalId, { executor: context });
+        context.terminalsData[terminalId] = {
+          type: 'graph2d',
+          config: fullConfig,
+          plots: []
+        };
+        handle.ports = {
+          plots: [],
+          config: { ...fullConfig }
+        };
+        return handle;
+      }
+    },
+
+    graph3d: (config = {}) => {
+      const terminalId = getNextId('graph3d');
+      // Convert StoneArrays in config (e.g., axes.t.values) to plain JS arrays
+      const fullConfig = deepConvertStoneArrays({
+        title: config.title || 'Scene',
+        ...config
+      });
+
+      if (isAdapterMode) {
+        // New adapter mode - create via adapter
+        context.outputAdapter.createTerminal(terminalId, 'graph3d', fullConfig);
+        return new TerminalHandle('graph3d', fullConfig, terminalId, { outputAdapter: context.outputAdapter });
+      } else {
+        // Legacy mode - direct mutation
+        const handle = new TerminalHandle('graph3d', fullConfig, terminalId, { executor: context });
+        context.terminalsData[terminalId] = {
+          type: 'graph3d',
+          config: fullConfig,
+          objects: []
+        };
+        handle.ports = {
+          objects: [],
+          config: { ...fullConfig }
+        };
+        return handle;
+      }
+    }
+  };
+}
+
+/**
+ * Check if a value is a TerminalHandle
+ * @param {any} value - Value to check
+ * @returns {boolean}
+ */
+export function isTerminalHandle(value) {
+  return value instanceof TerminalHandle || value?._type === 'TerminalHandle';
+}
+
+export default {
+  TerminalHandle,
+  createTerminalConstructors,
+  isTerminalHandle
+};