symbiote-ui 0.3.0-alpha.4

package/core/Portal.js

@@ -0,0 +1,106 @@
+/**
+ * Portal — Named Reroutes for wireless connections
+ *
+ * Provides virtual sender/receiver pairs that act as invisible
+ * connections. PortalManager tracks named channels and resolves
+ * portal connections during graph evaluation.
+ *
+ * Usage:
+ *   const pm = new PortalManager();
+ *   pm.addSender('channelA', node1, 'output');
+ *   pm.addReceiver('channelA', node2, 'input');
+ *   pm.getConnections(); // returns virtual connections
+ *
+ * @module symbiote-node/core/Portal
+ */
+
+/**
+ * PortalManager — manages named reroute channels
+ */
+export class PortalManager {
+  /** @type {Map<string, { senders: Array<{nodeId: string, portKey: string}>, receivers: Array<{nodeId: string, portKey: string}> }>} */
+  #channels = new Map();
+
+  /**
+   * Register a sender portal
+   * @param {string} channel - Named channel
+   * @param {string} nodeId - Source node ID
+   * @param {string} portKey - Output port key
+   */
+  addSender(channel, nodeId, portKey) {
+    if (!this.#channels.has(channel)) {
+      this.#channels.set(channel, { senders: [], receivers: [] });
+    }
+    this.#channels.get(channel).senders.push({ nodeId, portKey });
+  }
+
+  /**
+   * Register a receiver portal
+   * @param {string} channel - Named channel
+   * @param {string} nodeId - Target node ID
+   * @param {string} portKey - Input port key
+   */
+  addReceiver(channel, nodeId, portKey) {
+    if (!this.#channels.has(channel)) {
+      this.#channels.set(channel, { senders: [], receivers: [] });
+    }
+    this.#channels.get(channel).receivers.push({ nodeId, portKey });
+  }
+
+  /**
+   * Remove all portals for a node
+   * @param {string} nodeId
+   */
+  removeNode(nodeId) {
+    for (const [, ch] of this.#channels) {
+      ch.senders = ch.senders.filter((s) => s.nodeId !== nodeId);
+      ch.receivers = ch.receivers.filter((r) => r.nodeId !== nodeId);
+    }
+  }
+
+  /**
+   * Get all virtual connections from portal channels
+   * @returns {Array<{ from: string, out: string, to: string, in: string, channel: string }>}
+   */
+  getConnections() {
+    let result = [];
+    for (const [channel, ch] of this.#channels) {
+      for (const sender of ch.senders) {
+        for (const receiver of ch.receivers) {
+          result.push({
+            from: sender.nodeId,
+            out: sender.portKey,
+            to: receiver.nodeId,
+            in: receiver.portKey,
+            channel,
+          });
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Get all channel names
+   * @returns {string[]}
+   */
+  getChannels() {
+    return [...this.#channels.keys()];
+  }
+
+  /**
+   * Get channel info
+   * @param {string} channel
+   * @returns {{ senders: Array, receivers: Array }|undefined}
+   */
+  getChannel(channel) {
+    return this.#channels.get(channel);
+  }
+
+  /** Clear all portals */
+  clear() {
+    this.#channels.clear();
+  }
+}
+
+export { PortalManager as default };

package/core/Socket.js

@@ -0,0 +1,187 @@
+/**
+ * Socket — typed port connector
+ *
+ * Defines the type and visual identity of a connection endpoint.
+ * Compatible with symbiote-node SocketTypes system.
+ *
+ * @module symbiote-node/core/Socket
+ */
+
+let _uid = 0;
+
+/**
+ * Generate unique ID with prefix
+ * @param {string} prefix
+ * @returns {string}
+ */
+export function uid(prefix = 'id') {
+  return `${prefix}_${(++_uid).toString(36)}_${Date.now().toString(36)}`;
+}
+
+/**
+ * Socket type — defines connection endpoint type
+ */
+export class Socket {
+  /**
+   * @param {string} name - Socket type name (e.g. 'number', 'string', 'any')
+   * @param {object} [options]
+   * @param {string} [options.color] - CSS color for visual
+   */
+  constructor(name, options = {}) {
+    /** @type {string} */
+    this.name = name;
+
+    /** @type {string} */
+    this.color = options.color || 'var(--clr-3)';
+  }
+
+  /**
+   * Check if this socket is compatible with another
+   * @param {Socket} other
+   * @returns {boolean}
+   */
+  isCompatibleWith(other) {
+    if (this.name === 'any' || other.name === 'any') return true;
+    return this.name === other.name;
+  }
+}
+
+/**
+ * Port — represents an input or output endpoint on a node
+ */
+export class Port {
+  /**
+   * @param {Socket} socket - Socket type
+   * @param {string} [label] - Display label
+   * @param {boolean} [multipleConnections=false] - Allow multiple connections
+   */
+  constructor(socket, label, multipleConnections = false) {
+    /** @type {string} */
+    this.id = uid('port');
+
+    /** @type {Socket} */
+    this.socket = socket;
+
+    /** @type {string|undefined} */
+    this.label = label;
+
+    /** @type {boolean} */
+    this.multipleConnections = multipleConnections;
+
+    /** @type {number} */
+    this.index = 0;
+  }
+}
+
+/**
+ * Input port — accepts incoming connections
+ */
+export class Input extends Port {
+  /**
+   * @param {Socket} socket
+   * @param {string} [label]
+   * @param {boolean} [multipleConnections=false]
+   */
+  constructor(socket, label, multipleConnections = false) {
+    super(socket, label, multipleConnections);
+
+    /** @type {Control|null} */
+    this.control = null;
+
+    /** @type {boolean} */
+    this.showControl = true;
+  }
+
+  /**
+   * Add embedded control to this input
+   * @param {Control} control
+   */
+  addControl(control) {
+    if (this.control) throw new Error('control already added for this input');
+    this.control = control;
+  }
+
+  /**
+   * Remove embedded control
+   */
+  removeControl() {
+    this.control = null;
+  }
+}
+
+/**
+ * Output port — provides outgoing connections
+ */
+export class Output extends Port {
+  /**
+   * @param {Socket} socket
+   * @param {string} [label]
+   * @param {boolean} [multipleConnections=true]
+   */
+  constructor(socket, label, multipleConnections = true) {
+    super(socket, label, multipleConnections);
+  }
+}
+
+/**
+ * Control — embeddable UI widget inside a node
+ */
+export class Control {
+  constructor() {
+    /** @type {string} */
+    this.id = uid('ctrl');
+
+    /** @type {number} */
+    this.index = 0;
+
+    /** @type {function|undefined} */
+    this._onChange = undefined;
+  }
+}
+
+/**
+ * InputControl — text or number input widget
+ */
+export class InputControl extends Control {
+  /**
+   * @param {'text'|'number'|'textarea'|'select'|'boolean'} type
+   * @param {object} [options]
+   * @param {boolean} [options.readonly=false]
+   * @param {string|number|boolean} [options.initial]
+   * @param {string} [options.label] - Display label
+   * @param {string[]} [options.options] - Options for select type
+   * @param {function} [options.change] - Callback on value change
+   */
+  constructor(type, options = {}) {
+    super();
+
+    /** @type {'text'|'number'|'textarea'|'select'|'boolean'} */
+    this.type = type;
+
+    /** @type {boolean} */
+    this.readonly = options.readonly || false;
+
+    /** @type {string|number|boolean|undefined} */
+    this.value = options.initial;
+
+    /** @type {string} */
+    this.label = options.label || '';
+
+    /** @type {string[]} */
+    this.options = options.options || [];
+
+    /** @type {function|undefined} */
+    this._onChange = options.change;
+  }
+
+  /**
+   * Set control value
+   * @param {string|number|boolean} value
+   */
+  setValue(value) {
+    this.value = value;
+    if (this._onChange) this._onChange(value);
+  }
+}
+
+export { Socket as default };

package/core/SubgraphNode.js

@@ -0,0 +1,121 @@
+/**
+ * SubgraphNode — Node containing an embedded graph
+ *
+ * Extends Node with an inner NodeEditor that holds a sub-pipeline.
+ * Ports are auto-generated from exposed inner nodes.
+ * Supports drill-down navigation via SubgraphManager.
+ *
+ * @module symbiote-node/core/SubgraphNode
+ */
+
+import { Node } from './Node.js';
+import { NodeEditor } from './Editor.js';
+import { Socket, Input, Output } from './Socket.js';
+
+export class SubgraphNode extends Node {
+  /** @type {NodeEditor} */
+  innerEditor;
+
+  /** @type {Object<string, { x: number, y: number }>} */
+  innerPositions = {};
+
+  /** @type {{ panX: number, panY: number, zoom: number }} */
+  innerTransform = { panX: 0, panY: 0, zoom: 1 };
+
+  /**
+   * @param {string} label - Display name
+   * @param {object} [options={}]
+   * @param {string} [options.category='subgraph']
+   * @param {string} [options.icon='account_tree']
+   */
+  constructor(label, options = {}) {
+    super(label, {
+      type: 'subgraph',
+      category: options.category ?? 'subgraph',
+      icon: options.icon ?? 'account_tree',
+      shape: 'rect',
+      ...options,
+    });
+
+    this.innerEditor = new NodeEditor();
+    this._isSubgraph = true;
+  }
+
+  /**
+   * Sync external ports with inner graph exposed nodes.
+   * Inner nodes with `_exposed: 'input'` become subgraph inputs.
+   * Inner nodes with `_exposed: 'output'` become subgraph outputs.
+   */
+  syncPorts() {
+
+    for (const key of Object.keys(this.inputs)) {
+      if (key.startsWith('sg_')) this.removeInput(key);
+    }
+    for (const key of Object.keys(this.outputs)) {
+      if (key.startsWith('sg_')) this.removeOutput(key);
+    }
+
+    let anySocket = new Socket('any', { color: '#94a3b8' });
+
+
+    for (const innerNode of this.innerEditor.getNodes()) {
+      if (innerNode._exposed === 'input') {
+        for (const [key, output] of Object.entries(innerNode.outputs)) {
+          let portKey = `sg_${innerNode.id}_${key}`;
+          this.addInput(portKey, new Input(output.socket ?? anySocket, innerNode.label ?? key));
+        }
+      }
+      if (innerNode._exposed === 'output') {
+        for (const [key, input] of Object.entries(innerNode.inputs)) {
+          let portKey = `sg_${innerNode.id}_${key}`;
+          this.addOutput(portKey, new Output(input.socket ?? anySocket, innerNode.label ?? key));
+        }
+      }
+    }
+  }
+
+  /**
+   * Get inner editor
+   * @returns {NodeEditor}
+   */
+  getInnerEditor() {
+    return this.innerEditor;
+  }
+
+  /**
+   * Save inner node positions
+   * @param {Object<string, { x: number, y: number }>} positions
+   */
+  setInnerPositions(positions) {
+    this.innerPositions = { ...positions };
+  }
+
+  /**
+   * Save inner viewport transform
+   * @param {{ panX: number, panY: number, zoom: number }} transform
+   */
+  setInnerTransform(transform) {
+    this.innerTransform = { ...transform };
+  }
+
+  /**
+   * Serialize subgraph node including inner graph
+   * @returns {object}
+   */
+  toJSON() {
+    return {
+      id: this.id,
+      type: 'subgraph',
+      label: this.label,
+      category: this.category,
+      innerGraph: this.innerEditor.toJSON(
+        Object.fromEntries(
+          Object.entries(this.innerPositions).map(([id, pos]) => [id, [pos.x, pos.y]])
+        )
+      ),
+      innerTransform: this.innerTransform,
+    };
+  }
+}
+
+export { SubgraphNode as default };

package/core/base-path.js

@@ -0,0 +1,55 @@
+const apiPrefixes = ['/api/', '/ws/']
+
+export function getAppBasePath() {
+  const baseEl = document.querySelector('base[href]')
+  if (!baseEl) return ''
+  const baseUrl = new URL(baseEl.href, window.location.href)
+  if (baseUrl.origin !== window.location.origin) return ''
+  const path = baseUrl.pathname.replace(/\/$/, '')
+  return path === '' || path === '/' ? '' : path
+}
+
+export function withAppBasePath(value, protocol = window.location.protocol) {
+  const basePath = getAppBasePath()
+  if (!basePath || typeof value !== 'string') return value
+
+  if (apiPrefixes.some((prefix) => value.startsWith(prefix))) {
+    return `${basePath}${value}`
+  }
+
+  if (value.startsWith(`${window.location.origin}/`)) {
+    const url = new URL(value)
+    if (apiPrefixes.some((prefix) => url.pathname.startsWith(prefix))) {
+      url.pathname = `${basePath}${url.pathname}`
+      return url.toString()
+    }
+  }
+
+  if ((protocol === 'ws:' || protocol === 'wss:') && /^wss?:\/\//.test(value)) {
+    const url = new URL(value)
+    if (url.host === window.location.host && apiPrefixes.some((prefix) => url.pathname.startsWith(prefix))) {
+      url.pathname = `${basePath}${url.pathname}`
+      return url.toString()
+    }
+  }
+
+  return value
+}
+
+const nativeFetch = window.fetch.bind(window)
+window.fetch = (input, init) => {
+  if (typeof input === 'string') {
+    return nativeFetch(withAppBasePath(input), init)
+  }
+  if (input instanceof URL) {
+    return nativeFetch(new URL(withAppBasePath(input.toString())), init)
+  }
+  return nativeFetch(input, init)
+}
+
+const NativeWebSocket = window.WebSocket
+window.WebSocket = class PortalWebSocket extends NativeWebSocket {
+  constructor(url, protocols) {
+    super(withAppBasePath(String(url), new URL(String(url), window.location.href).protocol), protocols)
+  }
+}

package/core/dom-utils.js

@@ -0,0 +1,14 @@
+export function waitForElementApi(element, methodName, timeoutMs = 2000) {
+  if (!element || typeof element[methodName] === 'function') return Promise.resolve(element);
+  return new Promise((resolve) => {
+    let startedAt = Date.now();
+    function check() {
+      if (typeof element[methodName] === 'function' || Date.now() - startedAt >= timeoutMs) {
+        resolve(element);
+        return;
+      }
+      requestAnimationFrame(check);
+    }
+    check();
+  });
+}

package/core/index.js

@@ -0,0 +1,18 @@
+/**
+ * Node-safe core API for symbiote-node.
+ *
+ * This entrypoint must not import browser custom elements or Symbiote UI modules.
+ */
+
+export { NodeEditor } from './Editor.js';
+export { Node } from './Node.js';
+export { Connection } from './Connection.js';
+export { Frame } from './Frame.js';
+export { Socket, Port, Input, Output, Control, InputControl, uid } from './Socket.js';
+export { editorToText, textToGraph, textToEditor } from './GraphText.js';
+export { editorToMermaid, mermaidToGraph } from './GraphMermaid.js';
+export { PortalManager } from './Portal.js';
+export { SubgraphNode } from './SubgraphNode.js';
+export { readJsonCache, writeJsonCache, readStringCache, writeStringCache } from './local-cache.js';
+export { waitForElementApi } from './dom-utils.js';
+export { createStateSync } from './state-sync.js';

package/core/local-cache.js

@@ -0,0 +1,26 @@
+export function readJsonCache(key) {
+  if (typeof localStorage === 'undefined') return undefined
+  let raw = localStorage.getItem(key)
+  if (raw == null) return undefined
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+}
+
+export function writeJsonCache(key, value) {
+  if (typeof localStorage === 'undefined') return
+  localStorage.setItem(key, JSON.stringify(value))
+}
+
+export function readStringCache(key) {
+  if (typeof localStorage === 'undefined') return undefined
+  return localStorage.getItem(key) ?? undefined
+}
+
+export function writeStringCache(key, value) {
+  if (typeof localStorage === 'undefined') return
+  if (value == null) localStorage.removeItem(key)
+  else localStorage.setItem(key, String(value))
+}