novac 2.0.1 → 2.2.0

package/bin/nvc

@@ -0,0 +1,522 @@
+#!/usr/bin/env node
+// nvc — novac global binary: native addon kit generator
+//
+// Usage:
+//   nvc natives --name myaddon --sources win32:src/addon_win.cpp linux-x64:src/addon_lnx.cpp darwin:src/addon_mac.cpp
+//
+// Output:
+//   nkitmyaddon/
+//     bins/                        ← compiled .node binaries per platform/arch
+//     src/                         ← copied source files
+//     CMakeLists.txt               ← auto-generated (no binding.gyp — node-gyp is never used)
+//     kitdef.js                    ← runtime loader (sniffs platform+arch)
+//     unsupported.cpp              ← auto-generated stub for missing targets
+//     build.js                     ← the build orchestrator (cmake-js → cmake → manual gcc/clang)
+
+'use strict';
+
+const fs       = require('fs');
+const path     = require('path');
+const os       = require('os');
+const { execSync, spawnSync } = require('child_process');
+
+// ─── CONSTANTS ────────────────────────────────────────────────────────────────
+
+const SUPPORTED_PLATFORMS = ['win32', 'linux', 'darwin', 'android', 'freebsd', 'openbsd'];
+const SUPPORTED_ARCHS     = ['x64', 'x86', 'arm64', 'arm', 'ia32', 'riscv64', 'mips'];
+
+// Node-API version to target (stable across Node 12+)
+const NAPI_VERSION = 6;
+
+// ─── HELPERS ─────────────────────────────────────────────────────────────────
+
+function run(cmd, cwd, silent = false) {
+  const result = spawnSync(cmd, { shell: true, cwd, stdio: silent ? 'pipe' : 'inherit' });
+  return result.status === 0;
+}
+
+function has(cmd) {
+  const r = spawnSync(cmd, ['--version'], { shell: true, stdio: 'pipe' });
+  return r.status === 0;
+}
+
+function mkdir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function write(p, content) {
+  fs.writeFileSync(p, content, 'utf8');
+}
+
+function copy(src, dest) {
+  fs.copyFileSync(src, dest);
+}
+
+// Parse "platform-arch:path" or "platform:path" source specs
+// e.g. "linux-x64:src/addon.cpp"  "win32:src/win.cpp"  "darwin-arm64:src/mac.cpp"
+function parseSourceSpec(spec) {
+  const colon = spec.indexOf(':');
+  if (colon === -1) throw new Error(`Invalid source spec (missing ':'): ${spec}`);
+  const tag  = spec.slice(0, colon).trim();
+  const file = spec.slice(colon + 1).trim();
+  const dash = tag.indexOf('-');
+  let platform, arch;
+  if (dash === -1) {
+    platform = tag;
+    arch     = '*'; // any arch for this platform
+  } else {
+    platform = tag.slice(0, dash);
+    arch     = tag.slice(dash + 1);
+  }
+  return { platform, arch, file };
+}
+
+// Canonical binary name: addon-linux-x64.node
+function binName(kitName, platform, arch) {
+  return `${kitName}-${platform}-${arch}.node`;
+}
+
+// ─── CODE GENERATORS ─────────────────────────────────────────────────────────
+
+function genCMakeLists(kitName, srcFile, napiVersion) {
+  // Resolve paths at generation time — avoids CMake execute_process quoting bugs on all platforms
+  const { execSync: _exec } = require('child_process');
+  let nodeInclude = '';
+  let napiInclude = '';
+  let nodeBinDir  = '';
+
+  try {
+    const _p = require('path');
+    nodeInclude = _p.join(_p.dirname(process.execPath), '..', 'include', 'node');
+  } catch(_) {}
+  // napi include: always use the local node_modules path — node-addon-api isn't
+  // installed globally, it gets installed by npm install inside the kit folder.
+  // CMakeLists.txt is generated before that happens, so we hardcode the relative path.
+  napiInclude = '${CMAKE_SOURCE_DIR}/node_modules/node-addon-api';
+  try {
+    nodeBinDir = require('path').dirname(process.execPath);
+  } catch(_) {}
+
+  return `cmake_minimum_required(VERSION 3.15)
+project(${kitName})
+
+set(CMAKE_CXX_STANDARD 17)
+
+# Paths baked in at kit-generation time by nvc (no runtime execute_process needed)
+set(NODE_INCLUDE_DIR "${nodeInclude}")
+set(NAPI_INCLUDE     "${napiInclude}")
+set(NODE_BIN_DIR     "${nodeBinDir}")
+
+add_library(\${PROJECT_NAME} SHARED ${srcFile})
+set_target_properties(\${PROJECT_NAME} PROPERTIES PREFIX "" SUFFIX ".node")
+
+target_include_directories(\${PROJECT_NAME} PRIVATE
+  \${NODE_INCLUDE_DIR}
+  \${NAPI_INCLUDE}
+)
+
+target_compile_definitions(\${PROJECT_NAME} PRIVATE
+  NAPI_VERSION=${napiVersion}
+  NAPI_DISABLE_CPP_EXCEPTIONS
+)
+
+if(WIN32)
+  target_link_libraries(\${PROJECT_NAME} "\${NODE_BIN_DIR}/node.lib")
+elseif(APPLE)
+  set_target_properties(\${PROJECT_NAME} PROPERTIES
+    LINK_FLAGS "-undefined dynamic_lookup"
+  )
+endif()
+`;
+}
+
+
+function genUnsupportedStub(kitName) {
+  return `// Auto-generated unsupported-arch stub for ${kitName}
+#include <node_api.h>
+#include <stdio.h>
+
+napi_value Init(napi_env env, napi_value exports) {
+  const char* arch =
+#if defined(__x86_64__) || defined(_M_X64)
+    "x64";
+#elif defined(__i386__) || defined(_M_IX86)
+    "x86";
+#elif defined(__aarch64__) || defined(_M_ARM64)
+    "arm64";
+#elif defined(__arm__) || defined(_M_ARM)
+    "arm";
+#elif defined(__riscv) && __riscv_xlen == 64
+    "riscv64";
+#else
+    "unknown";
+#endif
+
+  const char* plat =
+#if defined(_WIN32)
+    "win32";
+#elif defined(__APPLE__)
+    "darwin";
+#elif defined(__ANDROID__)
+    "android";
+#elif defined(__linux__)
+    "linux";
+#elif defined(__FreeBSD__)
+    "freebsd";
+#else
+    "unknown";
+#endif
+
+  fprintf(stderr, "\\n[${kitName}] This native addon does not support your platform: %s-%s\\n", plat, arch);
+  fprintf(stderr, "  Please check https://your-project/nkit${kitName} for supported targets.\\n\\n");
+
+  napi_throw_error(env, "UNSUPPORTED_PLATFORM",
+    "This native addon does not support your current platform/architecture.");
+  return exports;
+}
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
+`;
+}
+
+function genKitdef(kitName, sources) {
+  const entries = sources.map(s => {
+    const archClause = s.arch === '*'
+      ? `platform === '${s.platform}'`
+      : `platform === '${s.platform}' && arch === '${s.arch}'`;
+    return `  if (${archClause}) return require('./bins/${binName(kitName, s.platform, s.arch === '*' ? 'universal' : s.arch)}');`;
+  });
+
+  return `// kitdef.js — auto-generated by kitnatives for ${kitName}
+// Do not edit manually; re-run kitnatives to regenerate.
+
+'use strict';
+
+const path     = require('path');
+const platform = process.platform;
+const arch     = process.arch;
+
+function loadAddon() {
+${entries.join('\n')}
+
+  // Fallback: unsupported platform/arch
+  try {
+    return require('./bins/${kitName}-unsupported.node');
+  } catch (_) {
+    throw new Error(
+      \`[${kitName}] Unsupported platform: \${platform}-\${arch}. \` +
+      \`No native binary available for this target.\`
+    );
+  }
+}
+
+const addon = loadAddon();
+
+module.exports = {
+  kitdef: addon
+};
+`;
+}
+
+function genBuildScript(kitName, sources, outDir) {
+  const builds = sources.map((s, i) => {
+    const bname  = binName(kitName, s.platform, s.arch === '*' ? 'universal' : s.arch);
+    const srcRel = path.basename(s.file);
+    return `
+// ── Build ${i + 1}: ${s.platform}-${s.arch} ──────────────────────────────────
+{
+  const srcFile = path.join(__dirname, 'src', '${srcRel}');
+  const outBin  = path.join(__dirname, 'bins', '${bname}');
+  const cmake   = path.join(__dirname, 'cmake_build_${i}');
+
+  console.log('[kitnatives] Building ${s.platform}-${s.arch}...');
+
+  if (fs.existsSync(outBin)) {
+    console.log('  → Already built, skipping.');
+  } else {
+    let built = false;
+
+    // Strategy 1: cmake-js (explicitly told to use CMake, never gyp)
+    if (!built && hasTool('cmake-js')) {
+      console.log('  → Trying cmake-js...');
+      fs.mkdirSync(cmake, { recursive: true });
+      // Pass --cmake-options to avoid any gyp fallback; point at our CMakeLists.txt
+      const r = run(
+        \`cmake-js compile --runtime node --cmake-options="-DCMAKE_BUILD_TYPE=Release" --directory "\${__dirname}" --out "\${cmake}"\`,
+        __dirname
+      );
+      if (r) {
+        const nodeFile = findNodeFile(cmake);
+        if (nodeFile) { fs.copyFileSync(nodeFile, outBin); built = true; }
+      }
+    }
+
+    // Strategy 2: cmake manually
+    if (!built && hasTool('cmake')) {
+      console.log('  → Trying cmake...');
+      fs.mkdirSync(cmake, { recursive: true });
+      const r1 = run(\`cmake .. -DSRC_FILE="${srcRel}" -DKIT_NAME="${kitName}"\`, cmake);
+      const r2 = r1 && run('cmake --build . --config Release', cmake);
+      if (r2) {
+        const nodeFile = findNodeFile(cmake);
+        if (nodeFile) { fs.copyFileSync(nodeFile, outBin); built = true; }
+      }
+    }
+
+    // Strategy 3: raw gcc/clang
+    if (!built) {
+      console.log('  → Trying manual gcc/clang compile...');
+      const compiler = hasTool('clang++') ? 'clang++' : hasTool('g++') ? 'g++' : null;
+      if (compiler) {
+        // Resolve include paths at build time
+        let nodeHead = '', napiHead = '';
+        try { const _p = require('path'); nodeHead = _p.join(_p.dirname(process.execPath), '..', 'include', 'node'); } catch(_) {}
+        napiHead = require('path').join(__dirname, 'node_modules', 'node-addon-api');
+        const isAndroid = process.platform === 'android' || process.env.TERMUX_VERSION;
+        const sharedFlag = isAndroid ? '-shared' : process.platform === 'darwin' ? '-dynamiclib' : '-shared';
+        const extraFlags = process.platform === 'darwin' ? '-undefined dynamic_lookup' : '';
+        const flags = [
+          sharedFlag, '-fPIC', extraFlags,
+          nodeHead   ? \`-I"\${nodeHead}"\` : '',
+          napiHead   ? \`-I"\${napiHead}"\` : '',
+          \`-DNAPI_VERSION=${NAPI_VERSION}\`,
+          '-DNAPI_DISABLE_CPP_EXCEPTIONS',
+          '-std=c++17',
+          \`"\${srcFile}"\`,
+          \`-o "\${outBin}"\`
+        ].filter(Boolean).join(' ');
+        const r = run(\`\${compiler} \${flags}\`, __dirname);
+        if (r) built = true;
+      }
+    }
+
+    if (!built) {
+      console.warn(\`  ✗ Could not build ${s.platform}-${s.arch}. Skipping.\`);
+    } else {
+      console.log(\`  ✓ Built → bins/${bname}\`);
+    }
+  }
+}`;
+  });
+
+  return `#!/usr/bin/env node
+// build.js — auto-generated by kitnatives for ${kitName}
+// Run this to compile all native targets.
+
+'use strict';
+
+const fs        = require('fs');
+const path      = require('path');
+const { execSync, spawnSync } = require('child_process');
+
+function run(cmd, cwd) {
+  const r = spawnSync(cmd, { shell: true, cwd: cwd || __dirname, stdio: 'inherit' });
+  return r.status === 0;
+}
+
+function hasTool(name) {
+  const r = spawnSync(name, ['--version'], { shell: true, stdio: 'pipe' });
+  return r.status === 0;
+}
+
+function findNodeFile(dir) {
+  if (!fs.existsSync(dir)) return null;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) { const r = findNodeFile(full); if (r) return r; }
+    else if (e.name.endsWith('.node')) return full;
+  }
+  return null;
+}
+
+fs.mkdirSync(path.join(__dirname, 'bins'), { recursive: true });
+
+${builds.join('\n')}
+
+// Build unsupported stub
+{
+  const stubSrc = path.join(__dirname, 'src', 'unsupported.cpp');
+  const stubOut = path.join(__dirname, 'bins', '${kitName}-unsupported.node');
+  if (!fs.existsSync(stubOut)) {
+    console.log('[kitnatives] Building unsupported-arch stub...');
+    const compiler = hasTool('clang++') ? 'clang++' : hasTool('g++') ? 'g++' : null;
+    if (compiler) {
+      const _p = require('path');
+      const nodeHead = _p.join(_p.dirname(process.execPath), '..', 'include', 'node');
+      const flags = [
+        '-shared', '-fPIC', '-undefined dynamic_lookup',
+        \`-I"\${nodeHead}"\`,
+        \`-DNAPI_VERSION=${NAPI_VERSION}\`,
+        '-std=c++17',
+        \`"\${stubSrc}"\`,
+        \`-o "\${stubOut}"\`
+      ].join(' ');
+      if (run(\`\${compiler} \${flags}\`, __dirname)) {
+        console.log('  ✓ Built unsupported stub');
+      }
+    } else {
+      console.warn('  ✗ No compiler found for stub. Missing-arch errors will throw JS exceptions.');
+    }
+  }
+}
+
+console.log('\\n[kitnatives] Build complete.');
+`;
+}
+
+// ─── MAIN GENERATOR ──────────────────────────────────────────────────────────
+
+function generate(opts) {
+  const { name, sources, outBase } = opts;
+
+  if (!name)              throw new Error('--name is required');
+  if (!sources?.length)   throw new Error('--sources is required (at least one platform:file)');
+
+  const kitName = name;
+  const outDir  = path.resolve(outBase ?? '.', `nkit${kitName}`);
+
+  const srcDir  = path.join(outDir, 'src');
+  const binDir  = path.join(outDir, 'bins');
+
+  mkdir(outDir);
+  mkdir(srcDir);
+  mkdir(binDir);
+
+  const parsedSources = sources.map(parseSourceSpec);
+
+  // Copy source files into src/
+  for (const s of parsedSources) {
+    const dest = path.join(srcDir, path.basename(s.file));
+    if (fs.existsSync(s.file)) {
+      copy(s.file, dest);
+    } else {
+      // Create a placeholder if the file doesn't exist yet
+      write(dest, `// Placeholder for ${s.file} (file not found during generation)\n`);
+      console.warn(`[kitnatives] Warning: source file not found: ${s.file} — placeholder written`);
+    }
+  }
+
+  // Write unsupported stub
+  write(path.join(srcDir, 'unsupported.cpp'), genUnsupportedStub(kitName));
+
+  // Write CMakeLists.txt (no binding.gyp — node-gyp is never used)
+  const primarySrc = path.basename(parsedSources[0].file);
+  write(path.join(outDir, 'CMakeLists.txt'), genCMakeLists(kitName, `src/${primarySrc}`, NAPI_VERSION));
+
+  // Write kitdef.js
+  write(path.join(outDir, 'kitdef.js'), genKitdef(kitName, parsedSources));
+
+  // Write build.js
+  write(path.join(outDir, 'build.js'), genBuildScript(kitName, parsedSources, outDir));
+  try { fs.chmodSync(path.join(outDir, 'build.js'), 0o755); } catch (_) {}
+
+  // Write package.json
+  write(path.join(outDir, 'package.json'), JSON.stringify({
+    name:    `nkit${kitName}`,
+    version: '1.0.0',
+    main:    'kitdef.js',
+    scripts: {
+      build: 'node build.js'
+    },
+    dependencies: {
+      'node-addon-api': '^7.0.0'
+    },
+    description: `Native addon kit for ${kitName} (generated by kitnatives)`
+  }, null, 2));
+
+  // Write README
+  write(path.join(outDir, 'README.md'), `# nkit${kitName}
+
+Native addon kit generated by **kitnatives**.
+
+## Building
+
+\`\`\`sh
+npm install        # installs node-addon-api headers
+node build.js      # compiles all targets
+\`\`\`
+
+The build script tries three strategies in order:
+1. **cmake-js** — if available globally
+2. **cmake** — manual configure + build
+3. **gcc/clang** — raw compiler invocation with manual flags
+
+If none succeed for a target, a warning is printed and that target is skipped.
+A fallback \`unsupported.node\` stub is always compiled; it prints a descriptive
+error message and throws if loaded on an unsupported platform.
+
+## Supported targets
+
+| Platform | Arch | Source |
+|----------|------|--------|
+${parsedSources.map(s => `| ${s.platform} | ${s.arch} | \`src/${path.basename(s.file)}\` |`).join('\n')}
+
+## Usage
+
+\`\`\`js
+const { kitdef } = require('./kitdef.js');
+// kitdef === your addon's exports for this platform
+\`\`\`
+`);
+
+  console.log(`\n[nvc] Generated nkit${kitName} at: ${outDir}`);
+  console.log(`  src/           ← your C/C++ sources`);
+  console.log(`  bins/          ← compiled .node binaries (after build.js)`);
+  console.log(`  CMakeLists.txt ← cmake build (no node-gyp, no binding.gyp)`);
+  console.log(`  kitdef.js      ← runtime loader`);
+  console.log(`  build.js       ← build orchestrator`);
+  console.log(`\nNext: cd nkit${kitName} && npm install && node build.js\n`);
+
+  return outDir;
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+function parseCLI(argv) {
+  const args = argv.slice(2);
+  const opts = { sources: [] };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--name')    { opts.name    = args[++i]; }
+    else if (args[i] === '--out')     { opts.outBase = args[++i]; }
+    else if (args[i] === '--sources') {
+      while (args[i + 1] && !args[i + 1].startsWith('--')) {
+        opts.sources.push(args[++i]);
+      }
+    }
+  }
+  return opts;
+}
+
+if (require.main === module) {
+  const opts = parseCLI(process.argv);
+  try {
+    generate(opts);
+  } catch (e) {
+    console.error('[nvc] Error:', e.message);
+    console.error('\nUsage:');
+    console.error('  nvc natives --name <kitname> --sources <platform[-arch]>:<file> ...\n');
+    console.error('Examples:');
+    console.error('  nvc natives --name myaddon --sources linux-x64:src/addon.cpp darwin-arm64:src/addon_mac.cpp win32:src/addon_win.cpp');
+    console.error('  nvc natives --name myaddon --sources linux:src/addon.cpp   # any arch on linux');
+    process.exit(1);
+  }
+}
+
+// ─── EXPORTS ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+    generate,
+    parseSourceSpec,
+    binName,
+    genCMakeLists,
+    genUnsupportedStub,
+    genKitdef,
+    genBuildScript,
+    SUPPORTED_PLATFORMS,
+    SUPPORTED_ARCHS,
+    NAPI_VERSION,
+  }
+};

package/bin/nvml

@@ -212,24 +212,71 @@ function cmdServe(port, nvmlFile, route) {
   }
 
   // Build a mutation-capturing proxy for /_nvml/run
+  const _sseClients = new Set(); // Server-Sent Events connections
+
   function makeMutationProxy(mutations, live) {
     return {
-      setConfig: (k, v)    => mutations.push({ type: 'setConfig', key: String(k), value: v }),
-      setTitle:  (t)       => mutations.push({ type: 'setConfig', key: 'title',   value: t }),
-      setMeta:   (k, v)    => mutations.push({ type: 'setConfig', key: String(k), value: v }),
-      set:       (id, val) => mutations.push({ type: 'setText',  id: String(id), value: String(val) }),
-      setHTML:   (id, val) => mutations.push({ type: 'setHTML',  id: String(id), value: String(val) }),
-      setProp:   (id, k, v)=> mutations.push({ type: 'setProp',  id: String(id), key: String(k), value: String(v) }),
-      addClass:  (id, cls) => mutations.push({ type: 'addClass', id: String(id), value: String(cls) }),
-      setClass:  (id, cls) => mutations.push({ type: 'setClass', id: String(id), value: String(cls) }),
-      addStyle:  (css)     => mutations.push({ type: 'addStyle', value: String(css) }),
-      addElementStyle: (id, css) => mutations.push({ type: 'addStyle', id: String(id), value: String(css) }),
-      hide:      (id)      => mutations.push({ type: 'hide', id: String(id) }),
-      show:      (id, d)   => mutations.push({ type: 'show', id: String(id), value: d || 'block' }),
-      alert:     (msg)     => mutations.push({ type: 'alert', value: String(msg) }),
-      get:       (id)      => (live.elements && live.elements[id]) ? live.elements[id].text : null,
-      getConfig: (k)       => live[k] ?? null,
-      config:    live,
+      // config
+      setConfig:      (k, v)       => mutations.push({ type: 'setConfig',    key: String(k), value: v }),
+      setTitle:       (t)          => mutations.push({ type: 'setConfig',    key: 'title', value: t }),
+      setMeta:        (k, v)       => mutations.push({ type: 'setConfig',    key: String(k), value: v }),
+      // text / html
+      set:            (id, val)    => mutations.push({ type: 'setText',      id: String(id), value: String(val) }),
+      setHTML:        (id, val)    => mutations.push({ type: 'setHTML',      id: String(id), value: String(val) }),
+      // props / attrs
+      setProp:        (id, k, v)   => mutations.push({ type: 'setProp',      id: String(id), key: String(k), value: String(v) }),
+      setAttr:        (id, k, v)   => mutations.push({ type: 'setAttr',      id: String(id), key: String(k), value: String(v) }),
+      removeAttr:     (id, k)      => mutations.push({ type: 'removeAttr',   id: String(id), key: String(k) }),
+      // classes
+      addClass:       (id, cls)    => mutations.push({ type: 'addClass',     id: String(id), value: String(cls) }),
+      removeClass:    (id, cls)    => mutations.push({ type: 'removeClass',  id: String(id), value: String(cls) }),
+      toggleClass:    (id, cls, f) => mutations.push({ type: 'toggleClass',  id: String(id), value: String(cls), force: f }),
+      setClass:       (id, cls)    => mutations.push({ type: 'setClass',     id: String(id), value: String(cls) }),
+      // style
+      addStyle:       (css)        => mutations.push({ type: 'addStyle',     value: String(css) }),
+      addElementStyle:(id, css)    => mutations.push({ type: 'addStyle',     id: String(id), value: String(css) }),
+      setStyle:       (id, k, v)   => mutations.push({ type: 'setStyle',     id: String(id), key: String(k), value: String(v) }),
+      setCSSVar:      (name, val)  => mutations.push({ type: 'setCSSVar',    name: String(name), value: String(val) }),
+      // visibility
+      hide:           (id, t)      => mutations.push({ type: 'hide',         id: String(id), transition: t || null }),
+      show:           (id, d, t)   => mutations.push({ type: 'show',         id: String(id), value: d || 'block', transition: t || null }),
+      // DOM manipulation
+      remove:         (id, t)      => mutations.push({ type: 'remove',       id: String(id), transition: t || null }),
+      appendChild:    (id, html)   => mutations.push({ type: 'appendChild',  id: String(id), html: String(html) }),
+      insertBefore:   (id, html)   => mutations.push({ type: 'insertBefore', id: String(id), html: String(html) }),
+      insertAfter:    (id, html)   => mutations.push({ type: 'insertAfter',  id: String(id), html: String(html) }),
+      // focus / scroll
+      focus:          (id)         => mutations.push({ type: 'focus',        id: String(id) }),
+      blur:           (id)         => mutations.push({ type: 'blur',         id: String(id) }),
+      scroll:         (id, beh)    => mutations.push({ type: 'scroll',       id: String(id), behavior: beh || 'smooth' }),
+      // signals
+      setSignal:      (name, val)  => mutations.push({ type: 'setSignal',    name: String(name), value: val }),
+      // list patch
+      patchList:      (id, items, tpl, key) => mutations.push({ type: 'patchList', id: String(id), items, template: String(tpl), key: key || null }),
+      // navigation
+      navigate:       (path)       => mutations.push({ type: 'navigate',     path: String(path) }),
+      reload:         ()           => mutations.push({ type: 'reload' }),
+      redirect:       (url)        => mutations.push({ type: 'redirect',     url: String(url) }),
+      // feedback
+      alert:          (msg)        => mutations.push({ type: 'alert',        value: String(msg) }),
+      toast:          (msg, d, t)  => mutations.push({ type: 'toast',        value: String(msg), duration: d || 3000, type: t || 'info' }),
+      console:        (msg, lvl)   => mutations.push({ type: 'console',      value: String(msg), level: lvl || 'log' }),
+      // reads from live snapshot
+      get:            (id)         => (live.elements && live.elements[id]) ? live.elements[id].text : null,
+      getValue:       (id)         => (live.elements && live.elements[id]) ? live.elements[id].value : null,
+      getClass:       (id)         => (live.elements && live.elements[id]) ? live.elements[id].class : null,
+      getConfig:      (k)          => live[k] ?? null,
+      getSignal:      (n)          => (live.state && live.state[n]) ?? null,
+      config:         live,
+      // SSE push (server → all connected clients)
+      push:           (name, val)  => {
+        const msg = `event: signal\ndata: ${JSON.stringify({ name, value: val })}\n\n`;
+        _sseClients.forEach(c => { try { c.write(msg); } catch(_) {} });
+      },
+      pushMutations:  (muts)       => {
+        const msg = `event: mutations\ndata: ${JSON.stringify(muts)}\n\n`;
+        _sseClients.forEach(c => { try { c.write(msg); } catch(_) {} });
+      },
     };
   }
 
@@ -237,12 +284,26 @@ function cmdServe(port, nvmlFile, route) {
     const parsed  = url.parse(req.url || '/');
     const urlPath = parsed.pathname || '/';
 
-    // CORS — lets nvml-browser previewer connect without issues
+    // CORS
     res.setHeader('Access-Control-Allow-Origin', '*');
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
     if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
 
+    // ── /_nvml/sse — Server-Sent Events for server-push signal updates ──
+    if (urlPath === '/_nvml/sse' && req.method === 'GET') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no',
+      });
+      res.write('retry: 3000\n\n'); // tell client to reconnect after 3s if disconnected
+      _sseClients.add(res);
+      req.on('close', () => _sseClients.delete(res));
+      return;
+    }
+
     // ── /_nvml/run — triggered server-side Nova scripts ──────
     if (urlPath === '/_nvml/run' && req.method === 'POST') {
       let rawBody = '';