novac 2.1.1 → 2.2.0

package/novac/kits/kitnovacweb/kitdef.js

@@ -0,0 +1,692 @@
+'use strict';
+
+/**
+ * kitnovacweb — Nova web kit
+ *
+ * Provides:
+ *   document.setIndex(nvmlFile)           — set the default / route
+ *   document.setPage(route, nvmlFile)     — map a route to an nvml file
+ *   document.setNotFound(nvmlFile)        — custom 404 page
+ *   document.serve(port)                  — start the server (default 3000)
+ *   document.stop()                       — stop the server
+ *   document.middleware(fn)               — add middleware fn(req, res, next)
+ *   document.static(urlPath, dirPath)     — serve static files
+ *   document.setHeader(key, value)        — set a default response header
+ *
+ * Usage in Nova:
+ *   import "kitnovacweb"
+ *   document.setIndex("index.nvml")
+ *   document.serve(8080)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const http = require('http');
+const url  = require('url');
+const nvml = require('./nvml/index');
+
+// ── Nova runner (requires executor.js from core novac) ───────
+// We try to load the novac executor from standard install locations.
+function makeNovaRunner() {
+  const searchPaths = [
+    // kits/kitnovacweb/ → novac_new/src/ (standard shipped layout)
+    path.join(__dirname, '..', '..', 'src', 'index.js'),
+    // nova_modules/kitnovacweb/ inside a user project → project root / src/
+    path.join(process.cwd(), 'src', 'index.js'),
+    // standard global install
+    path.join(require('os').homedir(), '.novac', 'node_modules', 'novac', 'src', 'index.js'),
+    // local node_modules
+    path.resolve(process.cwd(), 'node_modules', 'novac', 'src', 'index.js'),
+    // sibling directory (developer layout)
+    path.join(__dirname, '..', 'src', 'index.js'),
+    // bin sibling (when kit is symlinked / standalone)
+    path.join(__dirname, '..', '..', 'bin', '..', 'src', 'index.js'),
+  ];
+
+  let novacIndex = null;
+  for (const p of searchPaths) {
+    if (fs.existsSync(p)) { novacIndex = p; break; }
+  }
+
+  if (!novacIndex) {
+    process.stderr.write(
+      '[kitnovacweb] Warning: novac runtime not found — server-side Nova scripts will not run.\n' +
+      '  Searched:\n' + searchPaths.map(p => '    ' + p).join('\n') + '\n'
+    );
+    // Return stubs so the rest of the code doesn't need null-checks
+    return {
+      runner:  (code, doc, reqCtx) => {},
+      emitter: null,
+    };
+  }
+
+  let novaRun = null;
+  try {
+    const novacModule = require(novacIndex);
+    // src/index.js exports { run, tokenize, parse, format, Executor }
+    novaRun = novacModule.run || novacModule.default?.run || null;
+  } catch (e) {
+    process.stderr.write(`[kitnovacweb] Warning: failed to load novac runtime: ${e.message}\n`);
+    return {
+      runner:  (code, doc, reqCtx) => {},
+      emitter: null,
+    };
+  }
+
+  if (!novaRun) {
+    process.stderr.write('[kitnovacweb] Warning: novac runtime loaded but `run` not exported.\n');
+    return {
+      runner:  (code, doc, reqCtx) => {},
+      emitter: null,
+    };
+  }
+
+  /**
+   * runner(code, doc, reqContext)
+   *   - code       : Nova source string
+   *   - doc        : live NvmlDocument (mutated in place)
+   *   - reqContext : { method, url, path, query, headers, params, body }
+   *
+   * Inside the Nova script the following are available:
+   *   document  — proxy with setConfig / setTitle / set / get / addStyle …
+   *   request   — the HTTP request context object
+   */
+  const runner = (code, doc, reqCtx) => {
+    const { makeBfObject } = require('./nvml/executor');
+    const scope = {
+      document: makeDocumentProxy(doc),
+      request:  reqCtx || {},
+      bf:       makeBfObject(),
+    };
+    novaRun(code, scope);
+  };
+
+  /**
+   * exec(code, scope) — run Nova with a fully custom scope object.
+   * Used by /_nvml/run to pass a mutation-capturing proxy directly.
+   */
+  const exec = (code, scope) => {
+    const { makeBfObject } = require('./nvml/executor');
+    if (!scope.bf) scope.bf = makeBfObject();
+    novaRun(code, scope);
+  };
+
+  return { runner, exec, emitter: null };  // emitter intentionally null: server-side only
+}
+
+// ── document proxy (for use inside Nova server scripts) ──────
+// All mutations happen directly on the NvmlDocument so they are
+// reflected in the rendered HTML output.
+
+function makeDocumentProxy(doc) {
+  return {
+    // ── config / meta ──────────────────────────────────────
+    setConfig: (k, v) => { doc.config[k] = v; },
+    getConfig: (k)    => doc.config[k],
+    setTitle:  (t)    => { doc.config.title = t; },
+    setMeta:   (k, v) => { doc.config[k] = v; },
+
+    // ── element text content ───────────────────────────────
+    /** Set the text content of the element with the given id */
+    set: (id, content) => {
+      const el = findElementById(doc.visual, id);
+      if (el) el.textValue = String(content);
+    },
+    /** Get the current text content of an element */
+    get: (id) => {
+      const el = findElementById(doc.visual, id);
+      return el ? (el.textValue || null) : null;
+    },
+
+    // ── element attributes / props ─────────────────────────
+    /** Set a prop/attribute on the element with the given id */
+    setProp: (id, key, value) => {
+      const el = findElementById(doc.visual, id);
+      if (el) el.props[String(key)] = String(value);
+    },
+    /** Get a prop/attribute from the element with the given id */
+    getProp: (id, key) => {
+      const el = findElementById(doc.visual, id);
+      return el ? (el.props[String(key)] || null) : null;
+    },
+
+    // ── element class manipulation ─────────────────────────
+    /** Append a CSS class to the element's class list */
+    addClass: (id, cls) => {
+      const el = findElementById(doc.visual, id);
+      if (!el) return;
+      const existing = el.props.class || '';
+      el.props.class = (existing ? existing + ' ' : '') + cls;
+    },
+    /** Replace the entire class attribute of an element */
+    setClass: (id, cls) => {
+      const el = findElementById(doc.visual, id);
+      if (el) el.props.class = String(cls);
+    },
+
+    // ── inline styles ─────────────────────────────────────
+    /** Append CSS declarations to the element's inline ::ss block */
+    addElementStyle: (id, css) => {
+      const el = findElementById(doc.visual, id);
+      if (el) el.ss = (el.ss ? el.ss + '\n' : '') + css;
+    },
+    /** Append CSS to the document's global <style> block */
+    addStyle: (css) => { doc.globalStyles += '\n' + css; },
+
+    // ── visibility helpers ────────────────────────────────
+    /** Hide an element (sets display:none via inline style) */
+    hide: (id) => {
+      const el = findElementById(doc.visual, id);
+      if (el) el.ss = (el.ss ? el.ss + '\n' : '') + 'display: none;';
+    },
+    /** Show an element (sets display:block via inline style) */
+    show: (id, display) => {
+      const el = findElementById(doc.visual, id);
+      if (el) el.ss = (el.ss ? el.ss + '\n' : '') + `display: ${display || 'block'};`;
+    },
+    // alert: no-op when running on the server directly against a real doc
+    // (only meaningful via the mutation proxy in /_nvml/run)
+    alert: (_msg) => {},
+
+    // ── raw document reference (for advanced use) ─────────
+    config: doc.config,
+    _doc:   doc,
+  };
+}
+
+function findElementById(elements, id) {
+  for (const el of elements) {
+    if (el.props && el.props.id === id) return el;
+    if (el.children) {
+      const found = findElementById(el.children, id);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+// ── MIME types for static file serving ──────────────────────
+
+const MIME = {
+  '.html': 'text/html',
+  '.htm':  'text/html',
+  '.css':  'text/css',
+  '.js':   'text/javascript',
+  '.mjs':  'text/javascript',
+  '.json': 'application/json',
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif':  'image/gif',
+  '.svg':  'image/svg+xml',
+  '.ico':  'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2':'font/woff2',
+  '.ttf':  'font/ttf',
+  '.otf':  'font/otf',
+  '.mp4':  'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3':  'audio/mpeg',
+  '.wav':  'audio/wav',
+  '.txt':  'text/plain',
+  '.xml':  'application/xml',
+  '.pdf':  'application/pdf',
+  '.zip':  'application/zip',
+};
+
+function mimeFor(filePath) {
+  return MIME[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
+}
+
+// ── KitDocument — the main object exposed as `document` ─────
+
+class KitDocument {
+  constructor() {
+    this._routes      = new Map();   // urlPath → nvmlFilePath
+    this._notFound    = null;        // nvml file for 404
+    this._port        = 3000;
+    this._server      = null;
+    this._middlewares = [];
+    this._staticMounts= [];          // [{ urlPath, dirPath }]
+    this._headers     = {
+      'X-Powered-By': 'NovacWeb/1.0',
+    };
+    this._nova        = null;        // { runner, emitter } lazily loaded
+  }
+
+  // ── public API ──────────────────────────────────────────
+
+  setIndex(nvmlFile) {
+    this.setPage('/', nvmlFile);
+    return this;
+  }
+
+  setPage(route, nvmlFile) {
+    if (!route.startsWith('/')) route = '/' + route;
+    this._routes.set(route, path.resolve(process.cwd(), nvmlFile));
+    return this;
+  }
+
+  setNotFound(nvmlFile) {
+    this._notFound = path.resolve(process.cwd(), nvmlFile);
+    return this;
+  }
+
+  serve(port) {
+    if (port !== undefined) this._port = Number(port);
+    this._ensureNova();
+    this._startServer();
+    return this;
+  }
+
+  stop() {
+    if (this._server) {
+      this._server.close();
+      this._server = null;
+    }
+    return this;
+  }
+
+  middleware(fn) {
+    this._middlewares.push(fn);
+    return this;
+  }
+
+  static(urlPath, dirPath) {
+    if (!urlPath.startsWith('/')) urlPath = '/' + urlPath;
+    const absDir = path.resolve(process.cwd(), dirPath || urlPath.slice(1));
+    this._staticMounts.push({ urlPath, dirPath: absDir });
+    return this;
+  }
+
+  setHeader(key, value) {
+    this._headers[key] = value;
+    return this;
+  }
+
+  // ── internals ───────────────────────────────────────────
+
+  _ensureNova() {
+    if (!this._nova) {
+      this._nova = makeNovaRunner(); // always returns { runner, emitter }
+    }
+  }
+
+  _startServer() {
+    if (this._server) {
+      process.stdout.write(`[kitnovacweb] Server already running on port ${this._port}\n`);
+      return;
+    }
+
+    this._server = http.createServer((req, res) => {
+      this._handleRequest(req, res);
+    });
+
+    this._server.listen(this._port, () => {
+      process.stdout.write(`[kitnovacweb] Server running at http://localhost:${this._port}\n`);
+      process.stdout.write(`[kitnovacweb] Routes:\n`);
+      for (const [route, file] of this._routes) {
+        process.stdout.write(`  ${route}  →  ${file}\n`);
+      }
+    });
+
+    this._server.on('error', (err) => {
+      process.stderr.write(`[kitnovacweb] Server error: ${err.message}\n`);
+    });
+  }
+
+  _handleRequest(req, res) {
+    // run middleware chain
+    let idx = 0;
+    const next = () => {
+      if (idx < this._middlewares.length) {
+        const mw = this._middlewares[idx++];
+        try { mw(req, res, next); } catch (e) {
+          this._sendError(res, 500, e.message);
+        }
+      } else {
+        this._dispatch(req, res);
+      }
+    };
+    next();
+  }
+
+  _dispatch(req, res) {
+    const parsed  = url.parse(req.url || '/');
+    const urlPath = parsed.pathname || '/';
+
+    // ── /_nvml/run — Nova server script execution endpoint ──
+    if (urlPath === '/_nvml/run' && req.method === 'POST') {
+      return this._handleNvRun(req, res);
+    }
+
+    // ── /_nvml/run-node — Node.js server script execution endpoint ──
+    if (urlPath === '/_nvml/run-node' && req.method === 'POST') {
+      return this._handleNodeRun(req, res);
+    }
+
+    // ── static file serving ────────────────────────────────
+    for (const mount of this._staticMounts) {
+      if (urlPath.startsWith(mount.urlPath)) {
+        const rel      = urlPath.slice(mount.urlPath.length) || '/';
+        const filePath = path.join(mount.dirPath, rel);
+        if (this._serveStaticFile(res, filePath)) return;
+      }
+    }
+
+    // ── route matching ─────────────────────────────────────
+    // Exact match first
+    if (this._routes.has(urlPath)) {
+      return this._serveNvml(req, res, this._routes.get(urlPath), parsed);
+    }
+
+    // Pattern match: routes with :param segments
+    for (const [pattern, file] of this._routes) {
+      const params = this._matchRoute(pattern, urlPath);
+      if (params !== null) {
+        req._params = params;
+        return this._serveNvml(req, res, file, parsed);
+      }
+    }
+
+    // ── 404 ────────────────────────────────────────────────
+    if (this._notFound && fs.existsSync(this._notFound)) {
+      return this._serveNvml(req, res, this._notFound, parsed, 404);
+    }
+
+    this._sendError(res, 404, `Not Found: ${urlPath}`);
+  }
+
+  _matchRoute(pattern, urlPath) {
+    const pSegs = pattern.split('/');
+    const uSegs = urlPath.split('/');
+    if (pSegs.length !== uSegs.length) return null;
+    const params = {};
+    for (let i = 0; i < pSegs.length; i++) {
+      if (pSegs[i].startsWith(':')) {
+        params[pSegs[i].slice(1)] = uSegs[i];
+      } else if (pSegs[i] !== uSegs[i]) {
+        return null;
+      }
+    }
+    return params;
+  }
+
+  _serveNvml(req, res, nvmlFilePath, parsedUrl, statusCode = 200) {
+    if (!fs.existsSync(nvmlFilePath)) {
+      return this._sendError(res, 500, `NVML file not found: ${nvmlFilePath}`);
+    }
+
+    let source;
+    try {
+      source = fs.readFileSync(nvmlFilePath, 'utf8');
+    } catch (e) {
+      return this._sendError(res, 500, `Cannot read NVML file: ${e.message}`);
+    }
+
+    // Build a request context object accessible in server-side Nova scripts
+    const reqContext = {
+      method:  req.method,
+      url:     req.url,
+      path:    parsedUrl.pathname,
+      query:   Object.fromEntries(new URLSearchParams(parsedUrl.query || '')),
+      headers: req.headers,
+      params:  req._params || {},
+      body:    req._body   || null,
+    };
+
+    // If it's a POST/PUT/PATCH, collect body first
+    if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
+      let rawBody = '';
+      req.on('data', chunk => { rawBody += chunk; });
+      req.on('end', () => {
+        try {
+          reqContext.body = JSON.parse(rawBody);
+        } catch {
+          reqContext.body = rawBody;
+        }
+        this._compileAndSend(source, nvmlFilePath, reqContext, res, statusCode);
+      });
+      return;
+    }
+
+    this._compileAndSend(source, nvmlFilePath, reqContext, res, statusCode);
+  }
+
+  _compileAndSend(source, nvmlFilePath, reqContext, res, statusCode) {
+    // Change cwd to the NVML file's directory so relative paths in Nova scripts work
+    const nvmlDir = path.dirname(nvmlFilePath);
+
+    let html;
+    try {
+      // Wrap the runner so reqContext is forwarded to the Nova scope as `request`.
+      // The emitter is intentionally NOT passed — server-side nv scripts must not
+      // be compiled to JS and embedded in the page; they only mutate the doc.
+      const novaRunner = this._nova.runner
+        ? (code, doc) => this._nova.runner(code, doc, reqContext)
+        : null;
+
+      html = nvml.compile(source, {
+        novaRunner,
+        novaEmitter: null, // server-side only; no client-side Nova JS emitting
+      });
+    } catch (e) {
+      process.stderr.write(`[kitnovacweb] NVML compile error (${nvmlFilePath}): ${e.message}\n`);
+      if (process.env.NODE_ENV !== 'production') {
+        return this._sendError(res, 500,
+          `NVML Compile Error in ${path.basename(nvmlFilePath)}:\n${e.message}`);
+      }
+      return this._sendError(res, 500, 'Internal Server Error');
+    }
+
+    const headers = {
+      'Content-Type':   'text/html; charset=UTF-8',
+      'Content-Length': Buffer.byteLength(html),
+      ...this._headers,
+    };
+
+    res.writeHead(statusCode, headers);
+    res.end(html);
+  }
+
+  // ── /_nvml/run — run Nova server script, return mutations ──
+
+  _handleNvRun(req, res) {
+    let rawBody = '';
+    req.on('data', chunk => { rawBody += chunk; });
+    req.on('end', () => {
+      let code, live;
+      try {
+        const body = JSON.parse(rawBody);
+        code = String(body.code || '');
+        live = body.live || {};
+      } catch (e) {
+        return this._sendJSON(res, 400, { error: 'Invalid JSON body' });
+      }
+
+      if (!code.trim()) {
+        return this._sendJSON(res, 200, { mutations: [] });
+      }
+
+      if (!this._nova || !this._nova.exec) {
+        return this._sendJSON(res, 503, { error: 'Nova runtime not available' });
+      }
+
+      // Mutation-capturing proxy — collects all document mutations as JSON
+      // instead of applying them to an NvmlDocument. The client applies them.
+      const mutations = [];
+      const docProxy = {
+        // config / meta
+        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 }),
+        // element 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) }),
+        // element attributes
+        setProp:   (id, key, val) => mutations.push({ type: 'setProp', id: String(id), key: String(key), value: String(val) }),
+        // class helpers
+        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) }),
+        // styles
+        addStyle:  (css)     => mutations.push({ type: 'addStyle', value: String(css) }),
+        addElementStyle: (id, css) => mutations.push({ type: 'addStyle', id: String(id), value: String(css) }),
+        // visibility
+        hide:      (id)             => mutations.push({ type: 'hide', id: String(id) }),
+        show:      (id, display)    => mutations.push({ type: 'show', id: String(id), value: display || 'block' }),
+        // browser actions (applied client-side from mutation list)
+        alert:     (msg)            => mutations.push({ type: 'alert', value: String(msg) }),
+        // reads from the live snapshot the client sent
+        get:       (id)  => (live.elements && live.elements[id]) ? live.elements[id].text : null,
+        getConfig: (k)   => live[k] ?? null,
+        config:    live,
+      };
+
+      try {
+        this._nova.exec(code, { document: docProxy, request: live });
+        return this._sendJSON(res, 200, { mutations });
+      } catch (e) {
+        process.stderr.write(`[kitnovacweb] /_nvml/run error: ${e.message}\n`);
+        return this._sendJSON(res, 500, { error: e.message, mutations });
+      }
+    });
+  }
+
+  // ── /_nvml/run-node — run Node.js server script, return mutations ──
+
+  _handleNodeRun(req, res) {
+    let rawBody = '';
+    req.on('data', chunk => { rawBody += chunk; });
+    req.on('end', () => {
+      let code, live;
+      try {
+        const body = JSON.parse(rawBody);
+        code = String(body.code || '');
+        live = body.live || {};
+      } catch (e) {
+        return this._sendJSON(res, 400, { error: 'Invalid JSON body' });
+      }
+
+      if (!code.trim()) {
+        return this._sendJSON(res, 200, { mutations: [] });
+      }
+
+      const vm = require('vm');
+      const { makeBfObject } = require('./nvml/executor');
+      const mutations = [];
+
+      // Same mutation-capturing document proxy as _handleNvRun
+      const docProxy = {
+        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, tr)  => mutations.push({ type: 'hide',      id: String(id), transition: tr }),
+        show:      (id, d, tr)=> mutations.push({ type: 'show',     id: String(id), value: d||'block', transition: tr }),
+        remove:    (id, tr)  => mutations.push({ type: 'remove',    id: String(id), transition: tr }),
+        alert:     (msg)     => mutations.push({ type: 'alert',     value: String(msg) }),
+        toast:     (msg, dur, typ) => mutations.push({ type: 'toast', value: String(msg), duration: dur, type: typ }),
+        console:   (msg, lv) => mutations.push({ type: 'console',   value: String(msg), level: lv || 'log' }),
+        setSignal: (n, v)    => mutations.push({ type: 'setSignal', name: String(n),  value: v }),
+        navigate:  (p)       => mutations.push({ type: 'navigate',  path: String(p) }),
+        reload:    ()        => mutations.push({ type: 'reload' }),
+        redirect:  (url)     => mutations.push({ type: 'redirect',  url: String(url) }),
+        setStyle:  (id, k, v)=> mutations.push({ type: 'setStyle',  id: String(id), key: String(k), value: String(v) }),
+        setCSSVar: (n, v)    => mutations.push({ type: 'setCSSVar', name: String(n), 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) }),
+        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 }),
+        // reads from live snapshot
+        get:       (id)  => (live.elements && live.elements[id]) ? live.elements[id].text : null,
+        getSignal: (n)   => (live.state && live.state[n]) !== undefined ? live.state[n] : null,
+        getConfig: (k)   => live[k] ?? null,
+        config:    live,
+      };
+
+      try {
+        const ctx = vm.createContext({
+          document:   docProxy,
+          bf:         makeBfObject(),
+          request:    live,
+          console,
+          require,
+          process,
+          __dirname:  process.cwd(),
+          __filename: '',
+        });
+        vm.runInContext(code, ctx, { timeout: 10000 });
+        return this._sendJSON(res, 200, { mutations });
+      } catch (e) {
+        process.stderr.write(`[kitnovacweb] /_nvml/run-node error: ${e.message}\n`);
+        return this._sendJSON(res, 500, { error: e.message, mutations });
+      }
+    });
+  }
+
+
+    const body = JSON.stringify(obj);
+    res.writeHead(code, {
+      'Content-Type':                'application/json; charset=UTF-8',
+      'Content-Length':              Buffer.byteLength(body),
+      'Access-Control-Allow-Origin': '*',
+      ...this._headers,
+    });
+    res.end(body);
+  }
+
+  _serveStaticFile(res, filePath) {
+    // prevent directory traversal
+    const normalized = path.normalize(filePath);
+    if (!fs.existsSync(normalized) || !fs.statSync(normalized).isFile()) return false;
+
+    let data;
+    try { data = fs.readFileSync(normalized); } catch { return false; }
+
+    const mime = mimeFor(normalized);
+    res.writeHead(200, {
+      'Content-Type':   mime,
+      'Content-Length': data.length,
+      ...this._headers,
+    });
+    res.end(data);
+    return true;
+  }
+
+  _sendError(res, code, msg) {
+    const body = `<!DOCTYPE html>
+<html><head><meta charset="UTF-8"><title>${code}</title></head>
+<body><h1>${code}</h1><pre>${msg.replace(/</g,'&lt;')}</pre></body>
+</html>`;
+    res.writeHead(code, {
+      'Content-Type':   'text/html; charset=UTF-8',
+      'Content-Length': Buffer.byteLength(body),
+    });
+    res.end(body);
+  }
+}
+
+// ── Kit export ───────────────────────────────────────────────
+
+const kitdef = {
+  // Singleton document object (mirrors browser `document`)
+  document: new KitDocument(),
+
+  // Also expose the NVML pipeline directly for power users
+  nvml,
+
+  // Compile a raw NVML string to HTML (one-shot, no server)
+  compile: (source, opts) => nvml.compile(source, opts),
+
+  // Parse NVML source to AST
+  parse: (source) => nvml.parse(source),
+};
+
+module.exports = { kitdef };

package/novac/kits/kitnovacweb/nova.kit.json

@@ -0,0 +1,8 @@
+{
+  "name": "kitnovacweb",
+  "version": "1.0.0",
+  "description": "Nova web kit — NVML markup language with SSR, client scripts, and HTTP server",
+  "main": "index.nova",
+  "author": "",
+  "license": "MIT"
+}