novac 2.0.1 → 2.2.0

package/kits/kitnovacweb/nvml/executor.js

@@ -1,92 +1,186 @@
 'use strict';
 
 /**
- * NVML Executor
+ * NVML Executor v2
  *
- * Walks the parsed AST and builds a live Document object.
- * Handles:
- *   - @config     → document.config map
- *   - @visual     → document.visual element tree
- *   - @ss         → document.globalStyles string
- *   - {script}    → server-side Nova execution  OR  client JS collection
- *   - {element.*} → element tree nodes
- *   - [..]::prop  → property on nearest parent element
+ * Walks the AST and builds a live NvmlDocument.
+ * New in v2:
+ *   - @state      → reactive signal store
+ *   - @computed   → derived signals (Nova code evaluated server-side)
+ *   - @effect     → side-effect declarations (run client-side on signal change)
+ *   - @component  → named reusable component definitions
+ *   - @route      → client-side route definitions
+ *   - @slot       → slot content definitions
+ *   - @use        → declare component imports for a page
+ *   - bindings    → one-way (->) and two-way (<->) signal bindings on elements
+ *   - transitions → CSS transition hints (~) on elements
+ *   - each_block  → @each signal as item [ ... ] — reactive list rendering
+ *   - conditional → ? signal {element} — conditional rendering
+ *   - slot_outlet → @slot name inside a component — slot insertion point
  */
 
 class ExecError extends Error {
   constructor(msg) { super(`[NVML Executor] ${msg}`); this.name = 'ExecError'; }
 }
 
-// ── Document model ────────────────────────────────────────
+// ── Document model ────────────────────────────────────────────────────
 
 class NvmlElement {
   constructor(tag, id) {
-    this.tag        = tag;          // 'h1', 'div', 'button', 'script', …
-    this.id         = id;           // unique auto-id for DOM targeting
-    this.textValue  = null;         // {h1}='text' shorthand
-    this.props      = {};           // prop='value' pairs
-    this.ss         = null;         // inline style string  ([..]::ss)
-    this.code       = null;         // script code  ([..]::code)
-    this.children   = [];           // child NvmlElement[]
-    this.extraProps = {};           // any other [..]::X values
+    this.tag         = tag;
+    this.id          = id;
+    this.textValue   = null;
+    this.props       = {};
+    this.ss          = null;       // scoped CSS string
+    this.code        = null;       // script code
+    this.children    = [];
+    this.extraProps  = {};
+    this.bindings    = [];         // [{ prop, signal, twoWay }]
+    this.transitions = [];         // [{ prop, name }]
+    this.cond        = null;       // signal name — only render if truthy
+    this.eachSignal  = null;       // for each_block wrapper
+    this.eachItemVar = null;
+    this.isSlotOutlet = false;
+    this.slotName    = null;
+  }
+}
+
+class NvmlComponent {
+  constructor(name, body) {
+    this.name = name;
+    this.body = body;   // raw AST body — instantiated on use
+  }
+}
+
+/**
+ * NvmlLangDef — a user-defined language block registered via @lang
+ *
+ *   @lang {name} [
+ *     runtime_language="nv"   // "nv" | "js" | "nodejs"
+ *     config=""               // JSON string or path to config.json
+ *     src="PATH"              // path to implementation file
+ *     code=(...)              // inline implementation code
+ *   ]
+ *
+ * Scope rules:
+ *   runtime_language="nv"     → server-side Nova (same as scope='server' lang='nv')
+ *   runtime_language="nodejs" → server-side Node.js (new built-in)
+ *   runtime_language="js"     → client-side JavaScript (embedded in page)
+ */
+class NvmlLangDef {
+  constructor(name, opts = {}) {
+    this.name            = name;
+    this.runtimeLanguage = opts.runtime_language || opts.runtimeLanguage || 'js';
+    this.config          = opts.config  || '';
+    this.src             = opts.src     || null;
+    this.code            = opts.code    || '';
+    this.scope           = this._deriveScope();
+  }
+
+  _deriveScope() {
+    switch (this.runtimeLanguage) {
+      case 'nv':
+      case 'nova':
+      case 'novac':   return 'server-nova';
+      case 'nodejs':
+      case 'node':    return 'server-node';
+      case 'js':
+      default:        return 'client';
+    }
   }
 }
 
 class NvmlDocument {
   constructor() {
-    this.config      = {};          // @config key→value
-    this.visual      = [];          // top-level NvmlElement[]
-    this.globalStyles = '';         // @ss content
-    this._idCounter  = 0;
+    this.config       = {};    // @config key→value
+    this.visual       = [];    // top-level NvmlElement[]
+    this.globalStyles = '';    // @ss content
+    this.state        = {};    // @state signal name→initial value
+    this.computed     = [];    // [{ name, code }]
+    this.effects      = [];    // [{ deps, code }]
+    this.components   = {};    // name→NvmlComponent
+    this.routes       = [];    // [{ path, body }]
+    this.slots        = {};    // name→NvmlElement[]
+    this.usedComponents= [];   // component names declared via @use
+    this.langs        = {};    // name→NvmlLangDef  (user-defined language extensions)
+    this._idCounter   = 0;
   }
 
   _nextId() { return '_nvml_' + (this._idCounter++); }
 
-  // Called by executor to set a config value at runtime
-  setConfig(key, value) { this.config[key] = value; }
+  setConfig(key, value)         { this.config[key] = value; }
+  set(id, content)              { this._mutateElement(id, el => { el.textValue = content; }); }
+  get(id)                       { return this._findElement(id)?.textValue ?? null; }
+  setProp(id, key, value)       { this._mutateElement(id, el => { el.props[key] = value; }); }
+  getProp(id, key)              { return this._findElement(id)?.props[key] ?? null; }
+  addClass(id, cls)             { this._mutateElement(id, el => { el.props.class = ((el.props.class || '') + ' ' + cls).trim(); }); }
+  setClass(id, cls)             { this._mutateElement(id, el => { el.props.class = cls; }); }
+  addStyle(css)                 { this.globalStyles += '\n' + css; }
+  addElementStyle(id, css)      { this._mutateElement(id, el => { el.ss = (el.ss || '') + '\n' + css; }); }
+  hide(id)                      { this._mutateElement(id, el => { el.props.style = ((el.props.style || '') + '; display:none').replace(/^;/, ''); }); }
+  show(id, display = 'block')   { this._mutateElement(id, el => { el.props.style = ((el.props.style || '') + `; display:${display}`).replace(/^;/, ''); }); }
+  setTitle(t)                   { this.config.title = t; }
+  setMeta(k, v)                 { this.config[k] = v; }
+  alert(msg)                    { /* no-op at render time */ }
+  setHTML(id, html)             { this._mutateElement(id, el => { el._rawHTML = html; }); }
+
+  _findElement(id) {
+    const search = (els) => {
+      for (const el of els) {
+        if (el.props?.id === id || el.id === id) return el;
+        if (el.children) { const r = search(el.children); if (r) return r; }
+      }
+      return null;
+    };
+    return search(this.visual);
+  }
 
-  // Expose title shorthand
-  get title() { return this.config.title || ''; }
+  _mutateElement(id, fn) {
+    const el = this._findElement(id);
+    if (el) fn(el);
+  }
 }
 
-// ── Executor ──────────────────────────────────────────────
+// ── Executor ──────────────────────────────────────────────────────────
 
 class Executor {
-  /**
-   * @param {object} novaRunner  - { run(source, scope): any }
-   *                               Used to execute server-side Nova script blocks.
-   */
   constructor(novaRunner) {
     this.novaRunner = novaRunner;
     this.doc        = null;
   }
 
-  // ── public entry point ────────────────────────────────────
-
   execute(ast, existingDoc) {
     this.doc = existingDoc || new NvmlDocument();
-    for (const node of ast.body) {
-      this._execNode(node, null);
-    }
+    for (const node of ast.body) this._execNode(node, null);
     return this.doc;
   }
 
-  // ── dispatch ──────────────────────────────────────────────
-
   _execNode(node, parentElement) {
     switch (node.kind) {
-      case 'at_config':    return this._execConfig(node);
-      case 'at_block':     return this._execAtBlock(node, parentElement);
-      case 'element':      return this._execElement(node, parentElement);
-      case 'text_node':    return this._execTextNode(node, parentElement);
-      case 'parent_prop':  return this._execParentProp(node, parentElement);
-      case 'css_decl':     return; // handled inline in sub-body processing
+      case 'at_config':      return this._execConfig(node);
+      case 'at_state':       return this._execState(node);
+      case 'at_computed':    return this._execComputed(node);
+      case 'at_effect':      return this._execEffect(node);
+      case 'at_component':   return this._execComponent(node);
+      case 'at_route':       return this._execRoute(node);
+      case 'at_slot':        return this._execSlot(node);
+      case 'at_use':         return this._execUse(node);
+      case 'at_lang':        return this._execLang(node);
+      case 'at_block':       return this._execAtBlock(node, parentElement);
+      case 'element':        return this._execElement(node, parentElement);
+      case 'each_block':     return this._execEachBlock(node, parentElement);
+      case 'text_node':      return this._execTextNode(node, parentElement);
+      case 'parent_prop':    return this._execParentProp(node, parentElement);
+      case 'slot_outlet':    return this._execSlotOutlet(node, parentElement);
+      case 'component_use':  return this._execComponentUse(node, parentElement);
+      case 'signal_ref':     return; // resolved at render time
+      case 'css_decl':       return;
       default:
         throw new ExecError(`Unknown AST node kind: ${node.kind}`);
     }
   }
 
-  // ── @config ───────────────────────────────────────────────
+  // ── @config ──────────────────────────────────────────────────────
 
   _execConfig(node) {
     for (const [key, valNode] of Object.entries(node.pairs)) {
@@ -94,158 +188,309 @@ class Executor {
     }
   }
 
-  // ── @visual / @ss / custom at-blocks ─────────────────────
+  // ── @state ───────────────────────────────────────────────────────
 
-  _execAtBlock(node, parentElement) {
-    if (node.name === 'ss') {
-      // @ss [ ... ] — collect raw CSS-like content from nested text or sub-blocks
-      // We allow any nested blocks and stringify them as CSS
-      const cssLines = [];
-      for (const child of node.body) {
-        cssLines.push(this._nodeToCSS(child));
+  _execState(node) {
+    for (const [key, valNode] of Object.entries(node.pairs)) {
+      this.doc.state[key] = this._resolveValue(valNode);
+    }
+  }
+
+  // ── @computed ────────────────────────────────────────────────────
+
+  _execComputed(node) {
+    for (const entry of node.entries) {
+      const code = this._resolveValue(entry.code);
+      let value  = null;
+      // Run the Nova code server-side if possible to get an initial value
+      if (this.novaRunner && code) {
+        try { value = this.novaRunner(code, this.doc); } catch (e) { value = null; }
       }
-      if (parentElement) {
-        parentElement.ss = (parentElement.ss || '') + cssLines.join('\n');
-      } else {
-        this.doc.globalStyles += cssLines.join('\n');
+      this.doc.computed.push({ name: entry.name, code, initialValue: value });
+    }
+  }
+
+  // ── @effect ──────────────────────────────────────────────────────
+
+  _execEffect(node) {
+    for (const entry of node.entries) {
+      this.doc.effects.push({
+        deps: entry.deps,
+        code: this._resolveValue(entry.code),
+      });
+    }
+  }
+
+  // ── @component ───────────────────────────────────────────────────
+
+  _execComponent(node) {
+    this.doc.components[node.name] = new NvmlComponent(node.name, node.body);
+  }
+
+  // ── @route ───────────────────────────────────────────────────────
+
+  _execRoute(node) {
+    this.doc.routes.push({ path: this._resolveValue(node.arg || node.path), body: node.body });
+  }
+
+  // ── @slot ────────────────────────────────────────────────────────
+
+  _execSlot(node) {
+    const els = [];
+    for (const child of node.body) {
+      const el = this._buildElement(child, null);
+      if (el) els.push(el);
+    }
+    this.doc.slots[node.name] = els;
+  }
+
+  // ── @lang ─────────────────────────────────────────────────────────
+
+  _execLang(node) {
+    const opts = {};
+    for (const [key, valNode] of Object.entries(node.pairs || {})) {
+      opts[key] = this._resolveValue(valNode);
+    }
+    // code may come from inline code= or src= file
+    if (!opts.code && opts.src) {
+      try {
+        const fs   = require('fs');
+        const path = require('path');
+        opts.code  = fs.readFileSync(path.resolve(process.cwd(), opts.src), 'utf8');
+      } catch (e) {
+        process.stderr.write(`[NVML @lang ${node.name}] Cannot read src: ${e.message}\n`);
+      }
+    }
+    // load JSON config if it's a path string
+    if (opts.config && !opts.config.trim().startsWith('{')) {
+      try {
+        const fs   = require('fs');
+        const path = require('path');
+        opts.config = fs.readFileSync(path.resolve(process.cwd(), opts.config), 'utf8');
+      } catch (e) {
+        process.stderr.write(`[NVML @lang ${node.name}] Cannot read config file: ${e.message}\n`);
       }
-      return;
     }
+    this.doc.langs[node.name] = new NvmlLangDef(node.name, opts);
+  }
 
+  _execUse(node) {
+    for (const name of node.names) {
+      if (!this.doc.usedComponents.includes(name)) this.doc.usedComponents.push(name);
+    }
+  }
+
+  // ── @visual / @ss / custom ───────────────────────────────────────
+
+  _execAtBlock(node, parentElement) {
+    if (node.name === 'ss') {
+      const css = node.body.map(c => this._nodeToCSS(c)).join('\n');
+      if (parentElement) parentElement.ss = (parentElement.ss || '') + css;
+      else this.doc.globalStyles += css;
+      return;
+    }
     if (node.name === 'visual') {
-      for (const child of node.body) {
-        this._execNode(child, null);
-      }
+      for (const child of node.body) this._execNode(child, null);
       return;
     }
-
-    // Unknown @block — treat as a named section stored in doc.config
+    // each inside element body
+    if (node.name === 'each') {
+      // handled by parseEachBlock
+      return;
+    }
+    // unknown @block → store in doc.config
     const section = [];
     for (const child of node.body) {
-      const el = this._execElementToModel(child, null);
+      const el = this._buildElement(child, null);
       if (el) section.push(el);
     }
     this.doc.config[node.name] = section;
   }
 
-  // ── element ───────────────────────────────────────────────
+  // ── element ───────────────────────────────────────────────────────
 
   _execElement(node, parentElement) {
-    const el = this._execElementToModel(node, parentElement);
+    const el = this._buildElement(node, parentElement);
     if (!el) return;
-
-    if (parentElement) {
-      parentElement.children.push(el);
-    } else {
-      this.doc.visual.push(el);
-    }
+    if (parentElement) parentElement.children.push(el);
+    else this.doc.visual.push(el);
   }
 
-  _execElementToModel(node, parentElement) {
+  _buildElement(node, parentElement) {
+    if (!node) return null;
+
     if (node.kind === 'text_node') {
-      // bare string inside a parent
-      if (parentElement) {
-        parentElement.textValue = (parentElement.textValue || '') + node.value;
-      }
+      if (parentElement) parentElement.textValue = (parentElement.textValue || '') + node.value;
+      return null;
+    }
+    if (node.kind === 'signal_ref') {
+      // Inline signal reference: bind text content to signal
+      if (parentElement) parentElement._signalText = node.name || node.value;
+      return null;
+    }
+    if (node.kind === 'each_block') {
+      const wrapper = new NvmlElement('each-block', this.doc._nextId());
+      wrapper.eachSignal  = node.signal;
+      wrapper.eachItemVar = node.itemVar;
+      wrapper.eachIndexVar = node.indexVar;
+      wrapper._eachBody   = node.body;    // raw AST — rendered per-item at client
+      if (parentElement) parentElement.children.push(wrapper);
+      else this.doc.visual.push(wrapper);
+      return null;
+    }
+    if (node.kind === 'slot_outlet') {
+      const outlet = new NvmlElement('slot-outlet', this.doc._nextId());
+      outlet.isSlotOutlet = true;
+      outlet.slotName     = node.name || 'default';
+      if (parentElement) parentElement.children.push(outlet);
       return null;
     }
     if (node.kind !== 'element') return null;
 
-    // Resolve tag: 'element.button' → 'button', 'h1' → 'h1'
-    const rawTag = node.tag;
-    let tag = rawTag;
-    if (rawTag.startsWith('element.')) {
-      tag = rawTag.slice('element.'.split('.').length > 1 ? 'element.'.length : 0) || rawTag;
-    } else if (rawTag.includes('.')) {
-      // namespaced: element.NAME  — already handled above but catch remainder
-      tag = rawTag.split('.').pop();
+    // resolve tag
+    let tag = node.tag;
+    if (tag.startsWith('element.')) tag = tag.slice('element.'.length);
+    else if (tag.includes('.'))     tag = tag.split('.').pop();
+    if (tag === '..' || tag === '') return null;
+
+    // Check if this tag is a component name
+    if (this.doc.components[tag] || this.doc.usedComponents.includes(tag)) {
+      return this._instantiateComponent(tag, node, parentElement);
     }
-    // {..} is parent-ref used standalone — skip
-    if (rawTag === '..') return null;
 
     const el = new NvmlElement(tag, this.doc._nextId());
 
-    // inline text
-    if (node.textValue !== null) {
-      el.textValue = this._resolveValue(node.textValue);
+    if (node.textValue !== null && node.textValue !== undefined) {
+      const tv = node.textValue;
+      if (tv && tv.kind === 'signal_ref') el._signalText = tv.name || tv.value;
+      else el.textValue = this._resolveValue(tv);
     }
 
+    // conditional render
+    if (node.cond) el.cond = node.cond;
+
+    // bindings
+    el.bindings    = (node.bindings   || []).map(b => ({ prop: b.prop, signal: b.signal, twoWay: b.twoWay }));
+    el.transitions = (node.transitions|| []).map(t => ({ prop: t.prop, name: t.name }));
+
     // props
-    for (const [key, valNode] of Object.entries(node.props)) {
+    for (const [key, valNode] of Object.entries(node.props || {})) {
       if (valNode && valNode.__subBody !== undefined) {
-        // [..]::key [ subBody ] — stored as special sub-body
         if (key === 'ss') {
-          const cssLines = valNode.__subBody.map(c => this._nodeToCSS(c)).filter(Boolean);
-          el.ss = cssLines.join('\n');
+          el.ss = valNode.__subBody.map(c => this._nodeToCSS(c)).filter(Boolean).join('\n');
         } else if (key === 'code') {
-          // sub-body code block: collect text_node and css_decl values
-          el.code = valNode.__subBody
-            .map(c => c.kind === 'text_node' ? c.value : '')
-            .join('\n');
+          el.code = valNode.__subBody.map(c => c.kind === 'text_node' ? c.value : '').join('\n');
         } else {
           el.extraProps[key] = valNode.__subBody;
         }
+      } else if (valNode && valNode.kind === 'signal_ref') {
+        // prop -> signal binding via value shorthand
+        el.bindings.push({ prop: key, signal: valNode.name || valNode.value, twoWay: false });
       } else {
         const resolved = this._resolveValue(valNode);
-        if (key === 'ss')   { el.ss   = resolved; }
-        else if (key === 'code') { el.code = resolved; }
-        else { el.props[key] = resolved; }
+        if (key === 'ss')   el.ss   = resolved;
+        else if (key === 'code') el.code = resolved;
+        else el.props[key]  = resolved;
       }
     }
 
-    // body: child elements and @blocks
-    for (const child of node.body) {
+    // body children
+    for (const child of (node.body || [])) {
       if (child.kind === 'text_node') {
         el.textValue = (el.textValue || '') + child.value;
       } else if (child.kind === 'parent_prop') {
         this._applyParentProp(child, el);
+      } else if (child.kind === 'signal_ref') {
+        el._signalText = child.name || child.value;
       } else {
         this._execNode(child, el);
       }
     }
 
-    // if element is a script, handle server vs client
-    if (tag === 'script') {
-      this._handleScript(el);
-    }
+    // script handling
+    if (tag === 'script') this._handleScript(el);
 
     return el;
   }
 
-  // ── [..] property applied to nearest parent ───────────────
+  // ── component instantiation ───────────────────────────────────────
+
+  _instantiateComponent(name, node, parentElement) {
+    const comp = this.doc.components[name];
+    if (!comp) {
+      // External component (registered via @use but defined elsewhere) — emit a placeholder
+      const placeholder = new NvmlElement('div', this.doc._nextId());
+      placeholder.props['data-component'] = name;
+      placeholder.props['data-props']     = JSON.stringify(
+        Object.fromEntries(Object.entries(node.props || {}).map(([k,v]) => [k, this._resolveValue(v)]))
+      );
+      // pass bindings as data attrs
+      for (const b of (node.bindings || [])) {
+        placeholder.props[`data-bind-${b.prop}`] = b.signal + (b.twoWay ? ':2way' : '');
+      }
+      if (parentElement) parentElement.children.push(placeholder);
+      return null;
+    }
+    // Inline component: instantiate its body with prop overrides
+    const compRoot = new NvmlElement('div', this.doc._nextId());
+    compRoot.props['data-component'] = name;
+    for (const child of comp.body) this._execNode(child, compRoot);
+    if (parentElement) parentElement.children.push(compRoot);
+    return null;
+  }
+
+  // ── @each block ───────────────────────────────────────────────────
+
+  _execEachBlock(node, parentElement) {
+    const wrapper = new NvmlElement('each-block', this.doc._nextId());
+    wrapper.eachSignal   = node.signal;
+    wrapper.eachItemVar  = node.itemVar;
+    wrapper.eachIndexVar = node.indexVar;
+    wrapper._eachBody    = node.body;
+    if (parentElement) parentElement.children.push(wrapper);
+    else this.doc.visual.push(wrapper);
+  }
+
+  // ── slot outlet ───────────────────────────────────────────────────
+
+  _execSlotOutlet(node, parentElement) {
+    const outlet = new NvmlElement('slot-outlet', this.doc._nextId());
+    outlet.isSlotOutlet = true;
+    outlet.slotName     = node.name || 'default';
+    if (parentElement) parentElement.children.push(outlet);
+    else this.doc.visual.push(outlet);
+  }
+
+  // ── [..] prop ────────────────────────────────────────────────────
 
-  _applyParentProp(node, parentElement) {
+  _applyParentProp(node, el) {
     const prop = node.prop;
     if (node.subBody !== null && node.subBody !== undefined) {
       if (prop === 'ss') {
-        const cssLines = node.subBody.map(c => this._nodeToCSS(c));
-        parentElement.ss = (parentElement.ss || '') + cssLines.join('\n');
+        el.ss = (el.ss || '') + node.subBody.map(c => this._nodeToCSS(c)).join('\n');
       } else if (prop === 'code') {
-        const codeLines = node.subBody.map(c => this._nodeToRaw(c));
-        parentElement.code = codeLines.join('\n');
+        el.code = node.subBody.map(c => c.kind === 'text_node' ? c.value : '').join('\n');
       } else {
-        parentElement.extraProps[prop] = node.subBody;
+        el.extraProps[prop] = node.subBody;
       }
     } else {
       const resolved = node.value !== null ? this._resolveValue(node.value) : true;
-      if (prop === 'ss')   parentElement.ss   = resolved;
-      else if (prop === 'code') parentElement.code = resolved;
-      else parentElement.extraProps[prop] = resolved;
+      if      (prop === 'ss')   el.ss   = resolved;
+      else if (prop === 'code') el.code = resolved;
+      else    el.extraProps[prop] = resolved;
     }
   }
 
   _execParentProp(node, parentElement) {
-    if (!parentElement) return; // top-level [..] — ignore
+    if (!parentElement) return;
     this._applyParentProp(node, parentElement);
   }
 
   _execTextNode(node, parentElement) {
-    if (parentElement) {
-      parentElement.textValue = (parentElement.textValue || '') + node.value;
-    }
+    if (parentElement) parentElement.textValue = (parentElement.textValue || '') + node.value;
   }
 
-  // ── script handling ───────────────────────────────────────
+  // ── script handling ───────────────────────────────────────────────
 
   _handleScript(el) {
     const lang    = el.props.language || el.props.lang || 'js';
@@ -253,85 +498,242 @@ class Executor {
     const code    = el.code || el.textValue || '';
     const trigger = el.props.trigger || null;
 
-    el._scriptLang    = lang;
-    el._scriptScope   = scope;
-    el._scriptCode    = code;
-    el._ranOnServer   = false;
+    el._scriptLang  = lang;
+    el._scriptScope = scope;
+    el._scriptCode  = code;
+    el._ranOnServer = false;
 
-    // Server-side scripts with no trigger must run NOW, during execution,
-    // so their document mutations are baked into the HTML before it is sent.
-    // Triggered scripts (click, change, …) have no code to run at render
-    // time — they fire later via the /_nvml/run endpoint.
+    // ── Nova server-side (scope=server, no trigger) ──────────────
     if ((lang === 'novac' || lang === 'nv') && scope === 'server' && !trigger && code.trim()) {
       if (this.novaRunner) {
-        // Mark as ran-on-server immediately: any partial mutations applied before
-        // an error are already baked into the document, so we must not re-run
-        // the same code client-side (that would double-apply the mutations).
         el._ranOnServer = true;
-        try {
-          this.novaRunner(code, this.doc);
-        } catch (e) {
-          process.stderr.write(`[NVML Executor] Server script error: ${e.message}\n`);
-        }
+        try { this.novaRunner(code, this.doc); }
+        catch (e) { process.stderr.write(`[NVML Executor] Server script error: ${e.message}\n`); }
       } else {
-        process.stderr.write(
-          '[NVML Executor] Warning: server-side Nova script found but no novaRunner provided — script skipped.\n'
-        );
+        process.stderr.write('[NVML Executor] Warning: server-side Nova script found but no novaRunner provided.\n');
       }
+      return;
+    }
+
+    // ── Node.js server-side (lang=nodejs, no trigger) ─────────────
+    if ((lang === 'nodejs' || lang === 'node') && !trigger && code.trim()) {
+      el._ranOnServer = true;
+      try { this._runNodejsScript(code, el); }
+      catch (e) { process.stderr.write(`[NVML Executor] nodejs script error: ${e.message}\n`); }
+      return;
     }
+
+    // ── User-defined language (registered via @lang) ──────────────
+    const langDef = this.doc.langs[lang];
+    if (langDef && !trigger && code.trim()) {
+      if (langDef.scope === 'server-nova' && this.novaRunner) {
+        el._ranOnServer = true;
+        // Wrap: call the lang's implementation code first, then user code
+        const wrapped = langDef.code
+          ? langDef.code + '\n' + code
+          : code;
+        try { this.novaRunner(wrapped, this.doc); }
+        catch (e) { process.stderr.write(`[NVML Executor] @lang ${lang} (nv) error: ${e.message}\n`); }
+      } else if (langDef.scope === 'server-node') {
+        el._ranOnServer = true;
+        try { this._runNodejsScript((langDef.code ? langDef.code + '\n' : '') + code, el); }
+        catch (e) { process.stderr.write(`[NVML Executor] @lang ${lang} (nodejs) error: ${e.message}\n`); }
+      }
+      // client-scoped custom langs: renderer handles embedding
+      return;
+    }
+  }
+
+  // ── Node.js script runner ────────────────────────────────────────
+  // Runs code in Node's VM with document proxy + bf object in scope.
+  _runNodejsScript(code, el) {
+    const vm   = require('vm');
+    const doc  = this.doc;
+
+    // Build the document proxy (same surface as Nova runner)
+    const documentProxy = this._makeNodejsDocumentProxy(doc);
+
+    const ctx = vm.createContext({
+      document:   documentProxy,
+      bf:         makeBfObject(),
+      console,
+      require,
+      process,
+      __filename: '',
+      __dirname:  process.cwd(),
+    });
+
+    vm.runInContext(code, ctx, { timeout: 5000 });
+  }
+
+  _makeNodejsDocumentProxy(doc) {
+    const findEl = (id) => {
+      const search = (els) => {
+        for (const el of els) {
+          if (el.props?.id === id || el.id === id) return el;
+          if (el.children) { const r = search(el.children); if (r) return r; }
+        }
+        return null;
+      };
+      return search(doc.visual);
+    };
+    return {
+      setConfig:  (k, v)    => { doc.config[k] = v; },
+      setTitle:   (t)       => { doc.config.title = t; },
+      setMeta:    (k, v)    => { doc.config[k] = v; },
+      getConfig:  (k)       => doc.config[k],
+      set:        (id, val) => { const el = findEl(id); if (el) el.textValue = String(val); },
+      get:        (id)      => { const el = findEl(id); return el ? (el.textValue || null) : null; },
+      setHTML:    (id, html)=> { const el = findEl(id); if (el) el._rawHTML = html; },
+      setProp:    (id, k, v)=> { const el = findEl(id); if (el) el.props[k] = String(v); },
+      getProp:    (id, k)   => { const el = findEl(id); return el ? (el.props[k] || null) : null; },
+      addClass:   (id, cls) => { const el = findEl(id); if (!el) return; el.props.class = ((el.props.class||'')+' '+cls).trim(); },
+      setClass:   (id, cls) => { const el = findEl(id); if (el) el.props.class = cls; },
+      addStyle:   (css)     => { doc.globalStyles += '\n' + css; },
+      addElementStyle:(id, css) => { const el = findEl(id); if (el) el.ss = (el.ss||'')+'\n'+css; },
+      hide:       (id)      => { const el = findEl(id); if (el) el.props.style = ((el.props.style||'')+';display:none').replace(/^;/,''); },
+      show:       (id, d)   => { const el = findEl(id); if (el) el.props.style = ((el.props.style||'')+`;display:${d||'block'}`).replace(/^;/,''); },
+      setSignal:  (n, v)    => { doc.state[n] = v; },
+      getSignal:  (n)       => doc.state[n],
+      alert:      (_)       => {},
+      config:     doc.config,
+      _doc:       doc,
+    };
   }
 
-  // ── CSS node serializer (crude but functional) ────────────
+  // ── CSS serializer ────────────────────────────────────────────────
 
   _nodeToCSS(node) {
     if (!node) return '';
     if (node.kind === 'text_node') return node.value;
-    if (node.kind === 'css_decl') {
-      const val = this._resolveValue(node.value);
-      return `${node.key}: ${val};`;
-    }
+    if (node.kind === 'css_decl') return `${node.key}: ${this._resolveValue(node.value)};`;
     if (node.kind === 'element') {
-      const nodeProps    = node.props    || {};
-      const nodeBody     = node.body     || [];
-      const nodeChildren = node.children || [];
-      const textVal      = node.textValue;
-
-      // {color}='#aaa'  ← CSS property shorthand: textValue is the CSS value
-      if ((textVal !== null && textVal !== undefined) &&
-          Object.keys(nodeProps).length === 0 &&
-          nodeChildren.length === 0 &&
-          nodeBody.length === 0) {
-        const propName = node.tag;
-        const propVal  = typeof textVal === 'object'
-          ? this._resolveValue(textVal)
-          : textVal;
-        return `  ${propName}: ${propVal};`;
+      const tv = node.textValue;
+      if ((tv !== null && tv !== undefined) &&
+          Object.keys(node.props || {}).length === 0 &&
+          (node.body || []).length === 0) {
+        const propVal = typeof tv === 'object' ? this._resolveValue(tv) : tv;
+        return `  ${node.tag}: ${propVal};`;
       }
-      // treat {selector} [ decl='val', ] as a full CSS rule
       const sel   = node.tag;
-      const decls = Object.entries(nodeProps)
-        .map(([k, v]) => `  ${k}: ${this._resolveValue(v)};`)
-        .join('\n');
-      const nested = nodeBody.map(c => this._nodeToCSS(c)).filter(Boolean).join('\n');
+      const decls = Object.entries(node.props || {}).map(([k,v]) => `  ${k}: ${this._resolveValue(v)};`).join('\n');
+      const nested= (node.body || []).map(c => this._nodeToCSS(c)).filter(Boolean).join('\n');
       return `${sel} {\n${decls}${nested ? '\n' + nested : ''}\n}`;
     }
     return '';
   }
 
-  _nodeToRaw(node) {
-    if (!node) return '';
-    if (node.kind === 'text_node') return node.value;
-    return '';
-  }
-
-  // ── value resolver ────────────────────────────────────────
+  // ── value resolver ────────────────────────────────────────────────
 
   _resolveValue(valNode) {
     if (!valNode) return undefined;
-    if (valNode.kind === 'value') return valNode.value;
-    if (valNode.kind === 'pipe_list') return valNode.items;
+    if (valNode.kind === 'value')      return valNode.value;
+    if (valNode.kind === 'pipe_list')  return valNode.items;
+    if (valNode.kind === 'signal_ref') return `__sig:${valNode.name || valNode.value}`;
     return undefined;
   }
 }
 
-module.exports = { Executor, NvmlDocument, NvmlElement, ExecError };
+// ── Brainfuck object ──────────────────────────────────────────────────
+//
+// Available as `bf` in every language scope (server and client).
+//
+// Server-side (Nova / nodejs scripts): a live JS object.
+// Client-side: serialised to the page as window.__nvml_bf and also
+// injected into the custom-language JS wrapper.
+//
+// Properties / methods:
+//   bf.tape          — Uint8Array(30000) — the cell tape
+//   bf.pointer       — current data pointer (integer)
+//   bf.output        — string accumulated by '.' instructions
+//   bf.input         — string used as the input buffer for ',' instructions
+//   bf.run(code)     — run a BF program; returns the output string
+//   bf.reset()       — clear tape, pointer, I/O buffers
+//   bf.cell(n?)      — get (or with value: set) the value of cell n (default: current cell)
+
+function makeBfObject(opts = {}) {
+  const TAPE_SIZE = opts.tapeSize || 30000;
+  let tape    = new Uint8Array(TAPE_SIZE);
+  let ptr     = 0;
+  let output  = '';
+  let input   = opts.input || '';
+  let inPtr   = 0;
+
+  const obj = {
+    get tape()    { return tape; },
+    get pointer() { return ptr; },
+    get output()  { return output; },
+    get input()   { return input; },
+    set input(v)  { input = String(v); inPtr = 0; },
+
+    cell(n, v) {
+      const idx = (n === undefined) ? ptr : Number(n);
+      if (v !== undefined) tape[idx] = Number(v) & 0xFF;
+      return tape[idx];
+    },
+
+    reset() {
+      tape   = new Uint8Array(TAPE_SIZE);
+      ptr    = 0;
+      output = '';
+      input  = '';
+      inPtr  = 0;
+      return obj;
+    },
+
+    /**
+     * run(code, inputStr?) → output string
+     * Executes BF source. Stops on EOF (',') if input buffer is exhausted.
+     * Cell values wrap at 255/0 (unsigned byte).
+     */
+    run(code, inputStr) {
+      if (inputStr !== undefined) { input = String(inputStr); inPtr = 0; }
+      const src = String(code).split('').filter(c => '><+-.,[]'.includes(c));
+      let ip = 0;
+      const MAX_OPS = opts.maxOps || 10_000_000;
+      let ops = 0;
+
+      // pre-build bracket map for O(1) jump
+      const brackets = {};
+      const stack    = [];
+      for (let i = 0; i < src.length; i++) {
+        if (src[i] === '[') { stack.push(i); }
+        else if (src[i] === ']') {
+          const open = stack.pop();
+          if (open === undefined) throw new Error(`[bf] Unmatched ']' at ${i}`);
+          brackets[open] = i;
+          brackets[i]    = open;
+        }
+      }
+      if (stack.length) throw new Error(`[bf] Unmatched '[' at ${stack[0]}`);
+
+      while (ip < src.length) {
+        if (++ops > MAX_OPS) throw new Error('[bf] Maximum operations exceeded');
+        const cmd = src[ip];
+        switch (cmd) {
+          case '>': ptr = (ptr + 1) % TAPE_SIZE; break;
+          case '<': ptr = (ptr - 1 + TAPE_SIZE) % TAPE_SIZE; break;
+          case '+': tape[ptr] = (tape[ptr] + 1) & 0xFF; break;
+          case '-': tape[ptr] = (tape[ptr] - 1 + 256) & 0xFF; break;
+          case '.': output += String.fromCharCode(tape[ptr]); break;
+          case ',': {
+            if (inPtr < input.length) {
+              tape[ptr] = input.charCodeAt(inPtr++) & 0xFF;
+            } else {
+              tape[ptr] = 0; // EOF → 0
+            }
+            break;
+          }
+          case '[': if (tape[ptr] === 0) ip = brackets[ip]; break;
+          case ']': if (tape[ptr] !== 0) ip = brackets[ip]; break;
+        }
+        ip++;
+      }
+      return output;
+    },
+  };
+
+  return obj;
+}
+
+module.exports = { Executor, NvmlDocument, NvmlElement, NvmlComponent, NvmlLangDef, ExecError, makeBfObject };