novac 2.1.1 → 2.2.0

package/novac/kits/kitnovacweb/nvml/executor.js

@@ -0,0 +1,739 @@
+'use strict';
+
+/**
+ * NVML Executor v2
+ *
+ * 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 ────────────────────────────────────────────────────
+
+class NvmlElement {
+  constructor(tag, id) {
+    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.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++); }
+
+  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);
+  }
+
+  _mutateElement(id, fn) {
+    const el = this._findElement(id);
+    if (el) fn(el);
+  }
+}
+
+// ── Executor ──────────────────────────────────────────────────────────
+
+class Executor {
+  constructor(novaRunner) {
+    this.novaRunner = novaRunner;
+    this.doc        = null;
+  }
+
+  execute(ast, existingDoc) {
+    this.doc = existingDoc || new NvmlDocument();
+    for (const node of ast.body) this._execNode(node, null);
+    return this.doc;
+  }
+
+  _execNode(node, parentElement) {
+    switch (node.kind) {
+      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 ──────────────────────────────────────────────────────
+
+  _execConfig(node) {
+    for (const [key, valNode] of Object.entries(node.pairs)) {
+      this.doc.config[key] = this._resolveValue(valNode);
+    }
+  }
+
+  // ── @state ───────────────────────────────────────────────────────
+
+  _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; }
+      }
+      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`);
+      }
+    }
+    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);
+      return;
+    }
+    // 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._buildElement(child, null);
+      if (el) section.push(el);
+    }
+    this.doc.config[node.name] = section;
+  }
+
+  // ── element ───────────────────────────────────────────────────────
+
+  _execElement(node, parentElement) {
+    const el = this._buildElement(node, parentElement);
+    if (!el) return;
+    if (parentElement) parentElement.children.push(el);
+    else this.doc.visual.push(el);
+  }
+
+  _buildElement(node, parentElement) {
+    if (!node) return null;
+
+    if (node.kind === 'text_node') {
+      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
+    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);
+    }
+
+    const el = new NvmlElement(tag, this.doc._nextId());
+
+    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 || {})) {
+      if (valNode && valNode.__subBody !== undefined) {
+        if (key === 'ss') {
+          el.ss = valNode.__subBody.map(c => this._nodeToCSS(c)).filter(Boolean).join('\n');
+        } else if (key === 'code') {
+          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;
+      }
+    }
+
+    // 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);
+      }
+    }
+
+    // script handling
+    if (tag === 'script') this._handleScript(el);
+
+    return el;
+  }
+
+  // ── 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, el) {
+    const prop = node.prop;
+    if (node.subBody !== null && node.subBody !== undefined) {
+      if (prop === 'ss') {
+        el.ss = (el.ss || '') + node.subBody.map(c => this._nodeToCSS(c)).join('\n');
+      } else if (prop === 'code') {
+        el.code = node.subBody.map(c => c.kind === 'text_node' ? c.value : '').join('\n');
+      } else {
+        el.extraProps[prop] = node.subBody;
+      }
+    } else {
+      const resolved = node.value !== null ? this._resolveValue(node.value) : true;
+      if      (prop === 'ss')   el.ss   = resolved;
+      else if (prop === 'code') el.code = resolved;
+      else    el.extraProps[prop] = resolved;
+    }
+  }
+
+  _execParentProp(node, parentElement) {
+    if (!parentElement) return;
+    this._applyParentProp(node, parentElement);
+  }
+
+  _execTextNode(node, parentElement) {
+    if (parentElement) parentElement.textValue = (parentElement.textValue || '') + node.value;
+  }
+
+  // ── script handling ───────────────────────────────────────────────
+
+  _handleScript(el) {
+    const lang    = el.props.language || el.props.lang || 'js';
+    const scope   = el.props.scope || 'client';
+    const code    = el.code || el.textValue || '';
+    const trigger = el.props.trigger || null;
+
+    el._scriptLang  = lang;
+    el._scriptScope = scope;
+    el._scriptCode  = code;
+    el._ranOnServer = false;
+
+    // ── Nova server-side (scope=server, no trigger) ──────────────
+    if ((lang === 'novac' || lang === 'nv') && scope === 'server' && !trigger && code.trim()) {
+      if (this.novaRunner) {
+        el._ranOnServer = true;
+        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.\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 serializer ────────────────────────────────────────────────
+
+  _nodeToCSS(node) {
+    if (!node) return '';
+    if (node.kind === 'text_node') return node.value;
+    if (node.kind === 'css_decl') return `${node.key}: ${this._resolveValue(node.value)};`;
+    if (node.kind === 'element') {
+      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};`;
+      }
+      const sel   = node.tag;
+      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 '';
+  }
+
+  // ── 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 === 'signal_ref') return `__sig:${valNode.name || valNode.value}`;
+    return undefined;
+  }
+}
+
+// ── 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 };