symbiote-ui 0.3.0-alpha.4

package/plugins/History.js

@@ -0,0 +1,408 @@
+/**
+ * History — undo/redo action stack for NodeEditor
+ *
+ * Records editor actions (addNode, removeNode, move, connect, disconnect)
+ * and provides undo()/redo() with Ctrl+Z / Ctrl+Shift+Z keyboard bindings.
+ * Plugin pattern: attach to editor via history.listen(editor).
+ *
+ * @module symbiote-node/plugins/History
+ */
+
+/**
+ * @typedef {object} HistoryAction
+ * @property {'addNode'|'removeNode'|'moveNode'|'addConnection'|'removeConnection'|'addFrame'|'removeFrame'} type
+ * @property {object} data - Serialized action data for undo/redo
+ */
+
+const MAX_STACK = 200;
+
+export class History {
+  /** @type {HistoryAction[]} */
+  #undoStack = [];
+
+  /** @type {HistoryAction[]} */
+  #redoStack = [];
+
+  /** @type {import('../core/Editor.js').NodeEditor|null} */
+  #editor = null;
+
+  /** @type {function|null} */
+  #getCanvas = null;
+
+  /** @type {boolean} - prevent recording actions triggered by undo/redo itself */
+  #isApplying = false;
+
+  /** @type {function[]} - unsubscribe functions */
+  #unsubs = [];
+
+  /** @type {object} - injected class constructors */
+  #classes = {};
+
+  /**
+   * Attach history tracking to an editor
+   * @param {import('../core/Editor.js').NodeEditor} editor
+   * @param {object} [options]
+   * @param {function} [options.getCanvas] - returns canvas element for position tracking
+   * @param {object} [options.classes] - class constructors: { Node, Connection, Frame, Socket, Input, Output, InputControl }
+   */
+  listen(editor, options = {}) {
+    this.#editor = editor;
+    this.#getCanvas = options.getCanvas || null;
+    this.#classes = options.classes || {};
+
+
+    this.#unsubs.push(
+      editor.on('nodecreated', (node) => {
+        if (this.#isApplying) return;
+        let canvas = this.#getCanvas?.();
+        let pos = canvas ? this.#getNodePosition(canvas, node.id) : [0, 0];
+        this.#push({
+          type: 'addNode',
+          data: { node: this.#serializeNode(node), position: pos },
+        });
+      })
+    );
+
+
+    this.#unsubs.push(
+      editor.on('noderemove', (node) => {
+        if (this.#isApplying) return;
+        let canvas = this.#getCanvas?.();
+        let pos = canvas ? this.#getNodePosition(canvas, node.id) : [0, 0];
+
+        let conns = editor.getNodeConnections(node.id).map((c) => this.#serializeConnection(c));
+        this.#push({
+          type: 'removeNode',
+          data: { node: this.#serializeNode(node), position: pos, connections: conns },
+        });
+      })
+    );
+
+
+    this.#unsubs.push(
+      editor.on('nodepicked', (node) => {
+        if (this.#isApplying) return;
+        let canvas = this.#getCanvas?.();
+        if (!canvas) return;
+        let pos = this.#getNodePosition(canvas, node.id);
+        node._historyStartPos = pos;
+      })
+    );
+
+    this.#unsubs.push(
+      editor.on('nodedragged', ({ id }) => {
+        if (this.#isApplying) return;
+        let node = editor.getNode(id);
+        if (!node?._historyStartPos) return;
+        let canvas = this.#getCanvas?.();
+        let endPos = canvas ? this.#getNodePosition(canvas, id) : [0, 0];
+        let startPos = node._historyStartPos;
+
+        if (startPos[0] !== endPos[0] || startPos[1] !== endPos[1]) {
+          this.#push({
+            type: 'moveNode',
+            data: { nodeId: id, from: startPos, to: endPos },
+          });
+        }
+        delete node._historyStartPos;
+      })
+    );
+
+
+    this.#unsubs.push(
+      editor.on('connectioncreated', (conn) => {
+        if (this.#isApplying) return;
+        this.#push({
+          type: 'addConnection',
+          data: { connection: this.#serializeConnection(conn) },
+        });
+      })
+    );
+
+    this.#unsubs.push(
+      editor.on('connectionremove', (conn) => {
+        if (this.#isApplying) return;
+        this.#push({
+          type: 'removeConnection',
+          data: { connection: this.#serializeConnection(conn) },
+        });
+      })
+    );
+
+
+    this.#unsubs.push(
+      editor.on('framecreated', (frame) => {
+        if (this.#isApplying) return;
+        this.#push({
+          type: 'addFrame',
+          data: { frame: { ...frame } },
+        });
+      })
+    );
+
+    this.#unsubs.push(
+      editor.on('frameremove', (frame) => {
+        if (this.#isApplying) return;
+        this.#push({
+          type: 'removeFrame',
+          data: { frame: { ...frame } },
+        });
+      })
+    );
+  }
+
+  bindKeyboard(target) {
+    let handler = (e) => {
+      if ((e.ctrlKey || e.metaKey) && e.key === 'z') {
+        e.preventDefault();
+        if (e.shiftKey) this.redo();
+        else this.undo();
+      }
+      if ((e.ctrlKey || e.metaKey) && e.key === 'y') {
+        e.preventDefault();
+        this.redo();
+      }
+    };
+    target.addEventListener('keydown', handler);
+    this.#unsubs.push(() => target.removeEventListener('keydown', handler));
+  }
+
+  /** Undo last action */
+  undo() {
+    let action = this.#undoStack.pop();
+    if (!action) return;
+    this.#isApplying = true;
+    try {
+      this.#applyReverse(action);
+      this.#redoStack.push(action);
+    } finally {
+      this.#isApplying = false;
+    }
+  }
+
+  /** Redo last undone action */
+  redo() {
+    let action = this.#redoStack.pop();
+    if (!action) return;
+    this.#isApplying = true;
+    try {
+      this.#applyForward(action);
+      this.#undoStack.push(action);
+    } finally {
+      this.#isApplying = false;
+    }
+  }
+
+  /** @returns {number} */
+  get undoCount() {
+    return this.#undoStack.length;
+  }
+
+  /** @returns {number} */
+  get redoCount() {
+    return this.#redoStack.length;
+  }
+
+  /** Clear all history */
+  clear() {
+    this.#undoStack = [];
+    this.#redoStack = [];
+  }
+
+  /** Destroy and unsubscribe */
+  destroy() {
+    for (const unsub of this.#unsubs) {
+      if (typeof unsub === 'function') unsub();
+    }
+    this.#unsubs = [];
+    this.clear();
+    this.#editor = null;
+  }
+
+
+  #push(action) {
+    this.#undoStack.push(action);
+    if (this.#undoStack.length > MAX_STACK) this.#undoStack.shift();
+    this.#redoStack = [];
+  }
+
+  #applyReverse(action) {
+    let editor = this.#editor;
+    let canvas = this.#getCanvas?.();
+    if (!editor) return;
+
+    let reverseMap = {
+      addNode: () => editor.removeNode(action.data.node.id),
+      removeNode: () => {
+        let { node: nodeData, position, connections } = action.data;
+        let restoredNode = this.#deserializeNode(nodeData);
+        editor.addNode(restoredNode);
+        if (canvas && position) canvas.setNodePosition(restoredNode.id, position[0], position[1]);
+        for (let connData of connections) {
+          let conn = new this.#classes.Connection(
+            connData.from,
+            connData.out,
+            connData.to,
+            connData.in
+          );
+          conn.id = connData.id;
+          try {
+            editor.addConnection(conn);
+          } catch {
+
+          }
+        }
+      },
+      moveNode: () =>
+        canvas?.setNodePosition(action.data.nodeId, action.data.from[0], action.data.from[1]),
+      addConnection: () => editor.removeConnection(action.data.connection.id),
+      removeConnection: () => {
+        let connData = action.data.connection;
+        let conn = new this.#classes.Connection(
+          connData.from,
+          connData.out,
+          connData.to,
+          connData.in
+        );
+        conn.id = connData.id;
+        try {
+          editor.addConnection(conn);
+        } catch {
+
+        }
+      },
+      addFrame: () => editor.removeFrame(action.data.frame.id),
+      removeFrame: () => {
+        let frame = new this.#classes.Frame(action.data.frame.label, action.data.frame);
+        frame.id = action.data.frame.id;
+        editor.addFrame(frame);
+      },
+    };
+
+    reverseMap[action.type]?.();
+  }
+
+  #applyForward(action) {
+    let editor = this.#editor;
+    let canvas = this.#getCanvas?.();
+    if (!editor) return;
+
+    let forwardMap = {
+      addNode: () => {
+        let restoredNode = this.#deserializeNode(action.data.node);
+        editor.addNode(restoredNode);
+        if (canvas && action.data.position)
+          canvas.setNodePosition(restoredNode.id, action.data.position[0], action.data.position[1]);
+      },
+      removeNode: () => editor.removeNode(action.data.node.id),
+      moveNode: () =>
+        canvas?.setNodePosition(action.data.nodeId, action.data.to[0], action.data.to[1]),
+      addConnection: () => {
+        let connData = action.data.connection;
+        let conn = new this.#classes.Connection(
+          connData.from,
+          connData.out,
+          connData.to,
+          connData.in
+        );
+        conn.id = connData.id;
+        try {
+          editor.addConnection(conn);
+        } catch {
+
+        }
+      },
+      removeConnection: () => editor.removeConnection(action.data.connection.id),
+      addFrame: () => {
+        let frame = new this.#classes.Frame(action.data.frame.label, action.data.frame);
+        frame.id = action.data.frame.id;
+        editor.addFrame(frame);
+      },
+      removeFrame: () => editor.removeFrame(action.data.frame.id),
+    };
+
+    forwardMap[action.type]?.();
+  }
+
+  #serializeNode(node) {
+    return {
+      id: node.id,
+      label: node.label,
+      type: node.type,
+      category: node.category,
+      shape: node.shape,
+      params: { ...node.params },
+      inputs: Object.fromEntries(
+        Object.entries(node.inputs).map(([k, v]) => [
+          k,
+          {
+            socket: v.socket ? { type: v.socket.type, color: v.socket.color } : null,
+            label: v.label,
+          },
+        ])
+      ),
+      outputs: Object.fromEntries(
+        Object.entries(node.outputs).map(([k, v]) => [
+          k,
+          {
+            socket: v.socket ? { type: v.socket.type, color: v.socket.color } : null,
+            label: v.label,
+          },
+        ])
+      ),
+      controls: Object.fromEntries(
+        Object.entries(node.controls).map(([k, v]) => [
+          k,
+          {
+            label: v.label,
+            value: v.value,
+            type: v.type,
+          },
+        ])
+      ),
+    };
+  }
+
+  #serializeConnection(conn) {
+    return { id: conn.id, from: conn.from, out: conn.out, to: conn.to, in: conn.in };
+  }
+
+  #deserializeNode(data) {
+    let { Node, Socket, Input, Output, InputControl } = this.#classes;
+    let node = new Node(data.label, {
+      type: data.type,
+      category: data.category,
+      shape: data.shape,
+    });
+    node.id = data.id;
+    node.params = { ...data.params };
+
+    for (const [key, inp] of Object.entries(data.inputs)) {
+      let socket = inp.socket
+        ? new Socket(inp.socket.type, { color: inp.socket.color })
+        : new Socket('any');
+      node.addInput(key, new Input(socket, inp.label));
+    }
+    for (const [key, out] of Object.entries(data.outputs)) {
+      let socket = out.socket
+        ? new Socket(out.socket.type, { color: out.socket.color })
+        : new Socket('any');
+      node.addOutput(key, new Output(socket, out.label));
+    }
+    for (const [key, ctrl] of Object.entries(data.controls)) {
+      node.addControl(
+        key,
+        new InputControl(ctrl.type || 'text', { label: ctrl.label, initial: ctrl.value })
+      );
+    }
+
+    return node;
+  }
+
+  #getNodePosition(canvas, nodeId) {
+    let positions = canvas.getPositions();
+    return positions[nodeId] || [0, 0];
+  }
+}
+
+export { History as default };

package/plugins/Readonly.js

@@ -0,0 +1,60 @@
+/**
+ * Readonly — toggle readonly mode for node editor
+ *
+ * When enabled, blocks node creation, deletion, connection
+ * creation/removal, and node dragging.
+ *
+ * Adapted from Rete.js readonly plugin (63 LOC).
+ * @module symbiote-node/plugins/Readonly
+ */
+
+export class Readonly {
+  /** @type {boolean} */
+  #enabled = false;
+
+  /** @type {import('../core/Editor.js').NodeEditor|null} */
+  #editor = null;
+
+  /**
+   * @param {import('../core/Editor.js').NodeEditor} editor
+   */
+  constructor(editor) {
+    this.#editor = editor;
+  }
+
+  /** Enable readonly mode */
+  enable() {
+    this.#enabled = true;
+    this.#editor.emit('readonlychanged', true);
+  }
+
+  /** Disable readonly mode */
+  disable() {
+    this.#enabled = false;
+    this.#editor.emit('readonlychanged', false);
+  }
+
+  /** Toggle readonly mode */
+  toggle() {
+    this.#enabled ? this.disable() : this.enable();
+  }
+
+  /**
+   * Whether readonly is currently enabled
+   * @returns {boolean}
+   */
+  get isEnabled() {
+    return this.#enabled;
+  }
+
+  /**
+   * Guard check — throws if readonly
+   * Use before mutation operations
+   * @returns {boolean} true if operation should be blocked
+   */
+  shouldBlock() {
+    return this.#enabled;
+  }
+}
+
+export { Readonly as default };

package/rules/symbiote-3x.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "symbiote-3x",
+  "version": "1.0.0",
+  "description": "Machine-readable Symbiote.js 3.x rules for reusable package, UI, and provider contracts.",
+  "rules": [
+    {
+      "id": "SYM-001",
+      "name": "triple-file-standard",
+      "description": "Production components are split into .js, .tpl.js, and .css.js files.",
+      "severity": "error",
+      "filePattern": "**/*.js",
+      "check": "component_has_triple_files",
+      "tags": ["symbiote", "components", "architecture"]
+    },
+    {
+      "id": "SYM-002",
+      "name": "no-inline-templates",
+      "description": "Templates are defined in .tpl.js files instead of inline component bodies.",
+      "severity": "error",
+      "filePattern": "**/*.js",
+      "check": "no_inline_html_template",
+      "tags": ["symbiote", "templates"]
+    },
+    {
+      "id": "SYM-003",
+      "name": "reg-call-required",
+      "description": "Every custom element component calls .reg('kebab-case-tag').",
+      "severity": "error",
+      "filePattern": "**/*.js",
+      "check": "has_reg_call",
+      "tags": ["symbiote", "web-components"]
+    },
+    {
+      "id": "SYM-004",
+      "name": "css-token-usage",
+      "description": "Component CSS uses --sn-* custom properties for themeable values.",
+      "severity": "warning",
+      "filePattern": "**/*.css.js",
+      "check": "uses_sn_css_tokens",
+      "tags": ["symbiote", "theming", "tokens"]
+    },
+    {
+      "id": "SYM-005",
+      "name": "node-safe-core",
+      "description": "Root, core, manifest, rules, schemas, and tokens remain importable without DOM globals.",
+      "severity": "error",
+      "filePattern": ["index.js", "core/**/*.js", "manifest/**/*.js"],
+      "check": "no_dom_side_effects",
+      "tags": ["symbiote", "node-safe", "library"]
+    },
+    {
+      "id": "SYM-006",
+      "name": "single-binding-block",
+      "description": "Each template element has at most one Symbiote binding block.",
+      "severity": "error",
+      "filePattern": "**/*.tpl.js",
+      "check": "no_multiple_binding_blocks",
+      "tags": ["symbiote", "templates", "bindings"]
+    },
+    {
+      "id": "SYM-007",
+      "name": "published-library-contract",
+      "description": "Public metadata, rules, schemas, and token files are reachable from package exports and files[].",
+      "severity": "error",
+      "filePattern": "package.json",
+      "check": "published_contract_in_exports_and_files",
+      "tags": ["package", "exports", "library"]
+    },
+    {
+      "id": "SYM-008",
+      "name": "agent-boundary",
+      "description": "Agent-facing manifests describe modules and rules without importing browser components.",
+      "severity": "error",
+      "filePattern": "manifest/**/*.js",
+      "check": "manifest_is_side_effect_free",
+      "tags": ["agents", "mcp", "architecture"]
+    },
+    {
+      "id": "SYM-009",
+      "name": "public-subpath-imports",
+      "description": "Consumers import symbiote-node through package exports instead of relative package internals or deep implementation paths.",
+      "severity": "error",
+      "filePattern": "**/*.js",
+      "check": "uses_public_package_exports",
+      "tags": ["package", "exports", "library", "agents"]
+    },
+    {
+      "id": "SYM-010",
+      "name": "light-dom-host-selector",
+      "description": "Light DOM rootStyles use the registered custom element selector as the host selector; Shadow DOM styles use :host. Shared CSS that must run in both modes includes both selectors.",
+      "severity": "error",
+      "filePattern": "**/*.css.js",
+      "check": "root_styles_use_registered_host_selector",
+      "tags": ["symbiote", "styles", "light-dom", "theming"]
+    },
+    {
+      "id": "SYM-011",
+      "name": "theme-cascade-contract",
+      "description": "Themeable components consume inherited CSS custom properties and do not require per-component applyTheme calls or local token resets.",
+      "severity": "error",
+      "filePattern": ["**/*.css.js", "themes/**/*.js", "tokens/**/*.json"],
+      "check": "theme_values_cascade_from_stable_root",
+      "tags": ["symbiote", "theming", "tokens", "library"]
+    },
+    {
+      "id": "SYM-012",
+      "name": "css-data-for-visual-tokens",
+      "description": "Static visual tokens such as colors, spacing, radius, typography, and icon fonts are carried by CSS custom properties; PubSub and JS setters are reserved for application state or explicit dynamic measurements.",
+      "severity": "warning",
+      "filePattern": "**/*.js",
+      "check": "visual_tokens_use_css_custom_properties",
+      "tags": ["symbiote", "css-data", "theming", "state"]
+    },
+    {
+      "id": "SYM-013",
+      "name": "data-driven-runtime-ui",
+      "description": "Reusable UI primitives expose clean data, props, events, and manifest metadata so agents can assemble layouts and functionality at runtime without product-specific coupling.",
+      "severity": "error",
+      "filePattern": ["**/*.js", "manifest/**/*.js", "custom-elements.json"],
+      "check": "component_contract_is_data_driven",
+      "tags": ["symbiote", "agents", "runtime-ui", "library"]
+    },
+    {
+      "id": "SYM-014",
+      "name": "theme-rule-block-composition",
+      "description": "Themes are composed from named rule blocks: source accents, derived color formulas, geometry formulas, typography formulas, motion/effect formulas, semantic aliases, and component aliases.",
+      "severity": "error",
+      "filePattern": ["themes/**/*.js", "tokens/**/*.json", "manifest/**/*.js"],
+      "check": "theme_exposes_composable_rule_blocks",
+      "tags": ["symbiote", "themes", "agents", "design-rules"]
+    },
+    {
+      "id": "SYM-015",
+      "name": "geometry-cascade-formulas",
+      "description": "Spacing, radius, stroke, density, panel gaps, and component sizing derive from root geometry tokens through documented formulas instead of unrelated fixed values.",
+      "severity": "error",
+      "filePattern": ["themes/**/*.js", "tokens/**/*.json", "**/*.css.js"],
+      "check": "geometry_tokens_derive_from_root_scale",
+      "tags": ["symbiote", "themes", "geometry", "tokens"]
+    },
+    {
+      "id": "SYM-016",
+      "name": "color-cascade-formulas",
+      "description": "Surface, text, border, accent, state, and overlay tokens derive from source palettes or accent tokens through documented formulas with contrast-aware roles.",
+      "severity": "error",
+      "filePattern": ["themes/**/*.js", "tokens/**/*.json", "**/*.css.js"],
+      "check": "color_tokens_derive_from_source_palette",
+      "tags": ["symbiote", "themes", "color", "tokens", "accessibility"]
+    },
+    {
+      "id": "SYM-017",
+      "name": "interaction-effect-formulas",
+      "description": "Hover, focus, active, selected, loading, error, and transition effects derive from semantic state tokens and motion formulas, not per-component bespoke effects.",
+      "severity": "warning",
+      "filePattern": ["themes/**/*.js", "tokens/**/*.json", "**/*.css.js"],
+      "check": "interaction_effects_derive_from_state_tokens",
+      "tags": ["symbiote", "themes", "motion", "effects", "interaction"]
+    },
+    {
+      "id": "SYM-018",
+      "name": "no-legacy-ui-shell-classes",
+      "description": "Reusable and provider-owned UI must not introduce legacy .ui-* shared shell classes; use provider custom elements, host selectors, or component-namespaced classes.",
+      "severity": "error",
+      "filePattern": ["**/*.tpl.js", "**/*.css.js", "**/*.js"],
+      "check": "no_legacy_ui_shell_classes",
+      "tags": ["symbiote", "styles", "theming", "components"]
+    }
+  ]
+}