npm - novac - Versions diffs - 2.0.1 → 2.2.0 - Mend

novac 2.0.1 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (161) hide show

package/LICENSE +1 -1
package/README.md +1574 -597
package/bin/novac +468 -171
package/bin/nvc +522 -0
package/bin/nvml +78 -17
package/demo.nv +0 -0
package/demo_builtins.nv +0 -0
package/demo_http.nv +0 -0
package/examples/bf.nv +69 -0
package/examples/math.nv +21 -0
package/kits/birdAPI/kitdef.js +954 -0
package/kits/kitRNG/kitdef.js +740 -0
package/kits/kitSSH/kitdef.js +1272 -0
package/kits/kitadb/kitdef.js +606 -0
package/kits/kitai/kitdef.js +2185 -0
package/kits/kitansi/kitdef.js +1402 -0
package/kits/kitcanvas/kitdef.js +914 -0
package/kits/kitclippy/kitdef.js +925 -0
package/kits/kitformat/kitdef.js +1485 -0
package/kits/kitgps/kitdef.js +1862 -0
package/kits/kitlibproc/kitdef.js +3 -2
package/kits/kitmatrix/ex.js +19 -0
package/kits/kitmatrix/kitdef.js +960 -0
package/kits/kitmorse/kitdef.js +229 -0
package/kits/kitmpatch/kitdef.js +906 -0
package/kits/kitnet/kitdef.js +1401 -0
package/kits/kitnovacweb/README.md +1416 -143
package/kits/kitnovacweb/kitdef.js +92 -2
package/kits/kitnovacweb/nvml/executor.js +578 -176
package/kits/kitnovacweb/nvml/index.js +2 -2
package/kits/kitnovacweb/nvml/lexer.js +72 -69
package/kits/kitnovacweb/nvml/parser.js +328 -159
package/kits/kitnovacweb/nvml/renderer.js +770 -270
package/kits/kitparse/kitdef.js +1688 -0
package/kits/kitproto/kitdef.js +613 -0
package/kits/kitqr/kitdef.js +637 -0
package/kits/kitregex++/kitdef.js +1353 -0
package/kits/kitrequire/kitdef.js +1599 -0
package/kits/kitx11/kitdef.js +1 -0
package/kits/kitx11/kitx11.js +2472 -0
package/kits/kitx11/kitx11_conn.js +948 -0
package/kits/kitx11/kitx11_worker.js +121 -0
package/kits/libtea/kitdef.js +2691 -0
package/kits/libterm/ex.js +285 -0
package/kits/libterm/kitdef.js +1927 -0
package/novac/LICENSE +21 -0
package/novac/README.md +1823 -0
package/novac/bin/novac +950 -0
package/novac/bin/nvc +522 -0
package/novac/bin/nvml +542 -0
package/novac/demo.nv +245 -0
package/novac/demo_builtins.nv +209 -0
package/novac/demo_http.nv +62 -0
package/novac/examples/bf.nv +69 -0
package/novac/examples/math.nv +21 -0
package/novac/kits/kitai/kitdef.js +2185 -0
package/novac/kits/kitansi/kitdef.js +1402 -0
package/novac/kits/kitformat/kitdef.js +1485 -0
package/novac/kits/kitgps/kitdef.js +1862 -0
package/novac/kits/kitlibfs/kitdef.js +231 -0
package/{examples/example-project/nova_modules → novac/kits}/kitlibproc/kitdef.js +3 -2
package/novac/kits/kitmatrix/ex.js +19 -0
package/novac/kits/kitmatrix/kitdef.js +960 -0
package/novac/kits/kitmpatch/kitdef.js +906 -0
package/novac/kits/kitnovacweb/README.md +1572 -0
package/novac/kits/kitnovacweb/demo.nv +12 -0
package/novac/kits/kitnovacweb/demo.nvml +71 -0
package/novac/kits/kitnovacweb/index.nova +12 -0
package/novac/kits/kitnovacweb/kitdef.js +692 -0
package/novac/kits/kitnovacweb/nova.kit.json +8 -0
package/novac/kits/kitnovacweb/nvml/executor.js +739 -0
package/novac/kits/kitnovacweb/nvml/index.js +67 -0
package/novac/kits/kitnovacweb/nvml/lexer.js +263 -0
package/novac/kits/kitnovacweb/nvml/parser.js +508 -0
package/novac/kits/kitnovacweb/nvml/renderer.js +924 -0
package/novac/kits/kitparse/kitdef.js +1688 -0
package/novac/kits/kitregex++/kitdef.js +1353 -0
package/novac/kits/kitrequire/kitdef.js +1599 -0
package/novac/kits/kitx11/kitdef.js +1 -0
package/novac/kits/kitx11/kitx11.js +2472 -0
package/novac/kits/kitx11/kitx11_conn.js +948 -0
package/novac/kits/kitx11/kitx11_worker.js +121 -0
package/novac/kits/libtea/tf.js +2691 -0
package/novac/kits/libterm/ex.js +285 -0
package/novac/kits/libterm/kitdef.js +1927 -0
package/novac/node_modules/chalk/license +9 -0
package/novac/node_modules/chalk/package.json +83 -0
package/novac/node_modules/chalk/readme.md +297 -0
package/novac/node_modules/chalk/source/index.d.ts +325 -0
package/novac/node_modules/chalk/source/index.js +225 -0
package/novac/node_modules/chalk/source/utilities.js +33 -0
package/novac/node_modules/chalk/source/vendor/ansi-styles/index.d.ts +236 -0
package/novac/node_modules/chalk/source/vendor/ansi-styles/index.js +223 -0
package/novac/node_modules/chalk/source/vendor/supports-color/browser.d.ts +1 -0
package/novac/node_modules/chalk/source/vendor/supports-color/browser.js +34 -0
package/novac/node_modules/chalk/source/vendor/supports-color/index.d.ts +55 -0
package/novac/node_modules/chalk/source/vendor/supports-color/index.js +190 -0
package/novac/node_modules/commander/LICENSE +22 -0
package/novac/node_modules/commander/Readme.md +1176 -0
package/novac/node_modules/commander/esm.mjs +16 -0
package/novac/node_modules/commander/index.js +24 -0
package/novac/node_modules/commander/lib/argument.js +150 -0
package/novac/node_modules/commander/lib/command.js +2777 -0
package/novac/node_modules/commander/lib/error.js +39 -0
package/novac/node_modules/commander/lib/help.js +747 -0
package/novac/node_modules/commander/lib/option.js +380 -0
package/novac/node_modules/commander/lib/suggestSimilar.js +101 -0
package/novac/node_modules/commander/package-support.json +19 -0
package/novac/node_modules/commander/package.json +82 -0
package/novac/node_modules/commander/typings/esm.d.mts +3 -0
package/novac/node_modules/commander/typings/index.d.ts +1113 -0
package/novac/node_modules/node-addon-api/LICENSE.md +9 -0
package/novac/node_modules/node-addon-api/README.md +95 -0
package/novac/node_modules/node-addon-api/common.gypi +21 -0
package/novac/node_modules/node-addon-api/except.gypi +25 -0
package/novac/node_modules/node-addon-api/index.js +14 -0
package/novac/node_modules/node-addon-api/napi-inl.deprecated.h +186 -0
package/novac/node_modules/node-addon-api/napi-inl.h +7165 -0
package/novac/node_modules/node-addon-api/napi.h +3364 -0
package/novac/node_modules/node-addon-api/node_addon_api.gyp +42 -0
package/novac/node_modules/node-addon-api/node_api.gyp +9 -0
package/novac/node_modules/node-addon-api/noexcept.gypi +26 -0
package/novac/node_modules/node-addon-api/package-support.json +21 -0
package/novac/node_modules/node-addon-api/package.json +480 -0
package/novac/node_modules/node-addon-api/tools/README.md +73 -0
package/novac/node_modules/node-addon-api/tools/check-napi.js +99 -0
package/novac/node_modules/node-addon-api/tools/clang-format.js +71 -0
package/novac/node_modules/node-addon-api/tools/conversion.js +301 -0
package/novac/node_modules/serialize-javascript/LICENSE +27 -0
package/novac/node_modules/serialize-javascript/README.md +149 -0
package/novac/node_modules/serialize-javascript/index.js +297 -0
package/novac/node_modules/serialize-javascript/package.json +33 -0
package/novac/package.json +27 -0
package/novac/scripts/update-bin.js +24 -0
package/novac/src/core/bstd.js +1035 -0
package/novac/src/core/config.js +155 -0
package/novac/src/core/describe.js +187 -0
package/novac/src/core/emitter.js +499 -0
package/novac/src/core/error.js +86 -0
package/novac/src/core/executor.js +5606 -0
package/novac/src/core/formatter.js +686 -0
package/novac/src/core/lexer.js +1026 -0
package/novac/src/core/nova_builtins.js +717 -0
package/novac/src/core/nova_thread_worker.js +166 -0
package/novac/src/core/parser.js +2181 -0
package/novac/src/core/types.js +112 -0
package/novac/src/index.js +28 -0
package/novac/src/runtime/stdlib.js +244 -0
package/package.json +6 -3
package/scripts/update-bin.js +0 -0
package/src/core/bstd.js +838 -362
package/src/core/executor.js +2578 -170
package/src/core/lexer.js +502 -54
package/src/core/nova_builtins.js +21 -3
package/src/core/parser.js +413 -72
package/src/core/types.js +30 -2
package/src/index.js +0 -0
package/examples/example-project/README.md +0 -3
package/examples/example-project/src/main.nova +0 -3
package/src/core/environment.js +0 -0
/package/{examples/example-project/bin/example-project.nv → novac/node_modules/node-addon-api/nothing.c} +0 -0

package/kits/kitnovacweb/README.md CHANGED Viewed

@@ -1,299 +1,1572 @@
-# kitnovacweb
+# NVML — Nova Markup Language Reference v2
-Nova web kit — NVML markup language with SSR, client scripts, and HTTP server.
+NVML is the reactive templating language for novac web pages. It compiles to HTML with a built-in reactive signal system, virtual DOM diffing, component model, client-side router, slot system, CSS transitions, and Server-Sent Events. Files use the `.nvml` extension.
 ---
-## Usage
+## Table of Contents
+1. [CLI — nvml](#cli--nvml)
+2. [File Structure](#file-structure)
+3. [Comments](#comments)
+4. [Lexer Tokens](#lexer-tokens)
+5. [@config](#config)
+6. [@visual](#visual)
+7. [@ss — Global Styles](#ss--global-styles)
+8. [@state — Reactive Signals](#state--reactive-signals)
+9. [@computed — Derived Signals](#computed--derived-signals)
+10. [@effect — Side Effects](#effect--side-effects)
+11. [@component — Component Definitions](#component--component-definitions)
+12. [@use — Component Imports](#use--component-imports)
+13. [@slot — Named Slot Content](#slot--named-slot-content)
+14. [@route — Client-Side Router](#route--client-side-router)
+15. [Elements](#elements)
+16. [Properties](#properties)
+17. [Inline Text](#inline-text)
+18. [One-Way Binding (->)](#one-way-binding--)
+19. [Two-Way Binding (<->)](#two-way-binding--)
+20. [Conditional Rendering (?)](#conditional-rendering-)
+21. [@each — Reactive Lists](#each--reactive-lists)
+22. [Transitions (~)](#transitions-)
+23. [Signal References (#)](#signal-references-)
+24. [Scoped Styles — [..]::ss](#scoped-styles---ss)
+25. [Scripts — {script}](#scripts---script)
+26. [Server-Side Nova Scripts](#server-side-nova-scripts)
+27. [Server-Side Node.js Scripts](#server-side-nodejs-scripts)
+28. [Triggered Server Scripts](#triggered-server-scripts)
+29. [Client-Side Scripts](#client-side-scripts)
+30. [@lang — Custom Language Extensions](#lang--custom-language-extensions)
+31. [bf — Brainfuck Runtime](#bf--brainfuck-runtime)
+32. [document API](#document-api)
+33. [Reactive Runtime API (client-side)](#reactive-runtime-api-client-side)
+34. [Virtual DOM Diffing](#virtual-dom-diffing)
+35. [Server-Sent Events (SSE)](#server-sent-events-sse)
+36. [Mutation Types — Full Reference](#mutation-types--full-reference)
+37. [Pipe Lists](#pipe-lists)
+38. [kitnovacweb Integration](#kitnovacweb-integration)
+39. [Full Example](#full-example)
-```nova
-import "kitnovacweb"
+---
-document.setIndex("index.nvml")
-document.setPage("/about", "about.nvml")
-document.setNotFound("404.nvml")
-document.static("/public", "./public")
-document.serve(3000)
+## CLI — nvml
+```sh
+nvml <port> <file.nvml>              Serve on localhost:<port> at route /
+nvml <port> <file.nvml> <route>      Serve at a specific route path
+nvml compile <file.nvml>             Compile to HTML, print to stdout
+nvml ast     <file.nvml>             Print parsed AST as JSON
+nvml tokens  <file.nvml>             Print token stream as JSON
+nvml check   <file.nvml>             Validate syntax (exit 0 = OK)
+nvml --help                          Show help
+nvml --version                       Show version
+```
+The server **re-reads and re-compiles the file on every request** — no restart needed during development.
+CORS headers are set automatically. Internal endpoints:
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/_nvml/run` | `POST` | Execute triggered server-side Nova scripts, return mutations |
+| `/_nvml/sse` | `GET` | Server-Sent Events stream for server-push signal updates |
+---
+## File Structure
+An NVML file is a sequence of **top-level blocks**. Order does not matter except that `@visual` renders in the order it appears.
+| Block | Purpose |
+|-------|---------|
+| `@config [ ... ]` | Document metadata → `<head>` |
+| `@state [ ... ]` | Reactive signal declarations |
+| `@computed [ ... ]` | Derived signal declarations |
+| `@effect [ ... ]` | Side-effect declarations |
+| `@component Name [ ... ]` | Reusable component definition |
+| `@use Name, Name` | Declare component names used in this file |
+| `@slot name [ ... ]` | Named slot content |
+| `@route path [ ... ]` | Client-side route definition |
+| `@lang Name [ ... ]` | Define a custom scripting language extension |
+| `@visual [ ... ]` | Page body → `<body>` |
+| `@ss [ ... ]` | Global CSS → `<style>` in `<head>` |
+A minimal reactive page:
+```nvml
+@config [ title='My App', lang='en' ]
+@state [ count=0 ]
+@ss [
+  {body} [ font-family='system-ui', background='#111', color='#eee' ]
+]
+@visual [
+  {h1} [ text -> count ]
+  {button}='Increment' [ id='btn' ]
+  {script} [
+    language='nv', scope='server', trigger='click', target='btn',
+    [..]::code=(
+      document.setSignal("count", document.getSignal("count") + 1)
+    )
+  ]
+]
+```
+---
+## Comments
+```nvml
+// single-line comment
+/* multi-line block comment */
 ```
+Both are stripped before parsing and produce no output.
 ---
-## NVML Syntax
+## Lexer Tokens
+| Token | Syntax | Example |
+|-------|--------|---------|
+| `AT_IDENT` | `@name` | `@config`, `@state`, `@visual` |
+| `ELEMENT` | `{name}` | `{div}`, `{h1}`, `{element.button}` |
+| `LBRACKET` | `[` | Opens a block |
+| `RBRACKET` | `]` | Closes a block |
+| `STRING` | `'text'` `"text"` `(multiline)` | Value |
+| `COLONCOLON` | `::` | Parent-ref separator |
+| `ARROW` | `->` | One-way binding |
+| `DARROW` | `<->` | Two-way binding |
+| `QUESTION` | `?` | Conditional render |
+| `TILDE` | `~` | Transition hint |
+| `HASH` | `#name` | Signal reference |
+| `BANG_IDENT` | `!name` | Event emit shorthand |
+| `IDENT` | bare word | Property key or value |
+| `NUMBER` | `42`, `3.14` | Numeric value |
+| `PIPE` | `\|` | Pipe list delimiter |
+| `EQ` | `=` | Assignment |
+| `COMMA` | `,` | Separator (always optional trailing) |
+| `DOTDOT` | `[..]` | Parent element reference |
+| `DOT` | `.` | Separator in namespaced element names |
+| `EOF` | — | End of file |
+### Multiline Strings
+Paren-delimited strings support multiple lines and nested parentheses:
-NVML (Nova Markup Language) is the templating language for novacweb pages.
+```nvml
+[..]::code=(
+  let result = items.filter(x => x.active)
+  document.setSignal("filtered", result.length)
+)
+```
+Escape sequences inside quoted strings: `\n` `\t` `\r` `\\`
+---
-### `@config` — document metadata
+## @config
+Flat key-value block. All keys map to `<head>` elements or `<body>` attributes.
 ```nvml
 @config [
-  title='My Site',
+  title='My App',
   lang='en',
   charset='UTF-8',
-  description='Site description',
+  description='A reactive novac web app.',
+  author='Dev',
+  keywords=|nova, web, reactive|,
   viewport='width=device-width, initial-scale=1.0',
-  favicon='/public/favicon.ico',
-  theme-color='#1a1a2e',
-  stylesheet='styles.css',
-  scripts='app.js',
-  og:title='My Site',
+  favicon='/favicon.ico',
+  theme-color='#6c63ff',
+  robots='index, follow',
+  canonical='https://example.com',
+  base='/app/',
+  stylesheet=|reset.css, main.css|,
+  scripts=|vendor.js, app.js|,
+  bodyClass='dark',
+  bodyId='root',
+  bodyStyle='overflow-x: hidden',
+  head='<link rel="preconnect" href="https://fonts.googleapis.com">',
+  og:title='My App',
+  og:description='Reactive novac.',
   og:image='/og.png',
+  og:url='https://example.com',
+  og:type='website',
+  twitter:card='summary_large_image',
+  twitter:title='My App',
+  twitter:description='Reactive.',
+  twitter:image='/twitter.png',
 ]
 ```
-All keys are freeform and map to appropriate `<head>` tags. Known keys:
-`title`, `lang`, `charset`, `description`, `author`, `keywords`, `viewport`,
-`favicon`, `base`, `robots`, `canonical`, `theme-color`, `stylesheet`, `scripts`,
-`bodyClass`, `bodyId`, `bodyStyle`, `head` (raw HTML injected into head),
-Open Graph (`og:title`, `og:description`, `og:image`, `og:url`, `og:type`),
-Twitter card (`twitter:card`, `twitter:title`, `twitter:description`, `twitter:image`).
+### Config Keys Reference
+| Key | Output |
+|-----|--------|
+| `title` | `<title>` |
+| `lang` | `<html lang="...">` |
+| `charset` | `<meta charset="...">` (default: `UTF-8`) |
+| `description` | `<meta name="description">` |
+| `author` | `<meta name="author">` |
+| `keywords` | `<meta name="keywords">` (pipe list = joined with `, `) |
+| `viewport` | `<meta name="viewport">` |
+| `favicon` | `<link rel="icon">` |
+| `base` | `<base href="...">` |
+| `theme-color` | `<meta name="theme-color">` |
+| `robots` | `<meta name="robots">` |
+| `canonical` | `<link rel="canonical">` |
+| `stylesheet` | `<link rel="stylesheet">` (pipe list = one per value) |
+| `scripts` | `<script src="...">` (pipe list = one per value) |
+| `bodyClass` | `class="..."` on `<body>` |
+| `bodyId` | `id="..."` on `<body>` |
+| `bodyStyle` | `style="..."` on `<body>` |
+| `head` | Raw HTML injected directly into `<head>` |
+| `og:title` `og:description` `og:image` `og:url` `og:type` | `<meta property="og:...">` |
+| `twitter:card` `twitter:title` `twitter:description` `twitter:image` | `<meta name="twitter:...">` |
 ---
-### `@visual` — document body
+## @visual
-The main body of the page. Contains elements and script blocks.
+Contains the page body. Direct children become contents of `<body>`.
 ```nvml
 @visual [
   {div} [
     class='container',
-    {h1}='Hello World'
-    {p} [ "Some text." ]
+    {h1}='Welcome'
+    {p}='Built with NVML v2'
   ]
 ]
 ```
 ---
-### Elements
+## @ss — Global Styles
-**Any HTML tag name works:**
+Generates a `<style>` block in `<head>`. Uses a CSS-flavored sub-syntax where element names are CSS selectors.
 ```nvml
-{div} [ ... ]
-{h1} [ ... ]
-{button} [ id='btn', class='primary', "Label" ]
-{img} [ src='/logo.png', alt='Logo' ]
-{input} [ type='text', placeholder='Enter text' ]
+@ss [
+  {*} [ box-sizing='border-box', margin='0', padding='0' ]
+  {body} [
+    font-family='system-ui, sans-serif',
+    background='#111',
+    color='#eee',
+    display='flex',
+    align-items='center',
+    justify-content='center',
+    min-height='100vh',
+  ]
+  {.card} [
+    border-radius='10px',
+    padding='2.5rem',
+    background='#1e1e1e',
+    box-shadow='0 4px 24px #0008',
+  ]
+  {button:hover} [ background='#5548e0' ]
+  {.card h2}     [ font-size='1.4rem', margin-bottom='0.5rem' ]
+  {#hero}        [ min-height='60vh' ]
+]
 ```
-**Inline text shorthand:**
+`{selector} [ property='value', ... ]` renders as:
+```css
+selector {
+  property: value;
+}
+```
+Shorthand inside a selector block: `{property}='value'` → `property: value;`
+CSS variables:
+```nvml
+@ss [
+  {:root} [
+    --brand='#6c63ff',
+    --surface='#1e1e1e',
+    --nvml-dur-fade='0.3s',
+  ]
+]
+```
+---
+## @state — Reactive Signals
+Declares reactive signals. All entries are automatically tracked. Every element with a binding to a signal updates automatically when the signal value changes.
+```nvml
+@state [
+  count=0,
+  name='World',
+  isLoggedIn=false,
+  theme='dark',
+  items='[]',
+  selectedId=null,
+]
+```
+The initial values are serialized to `window.__nvml.state` and the reactive runtime script is injected into `<head>`. Signals are accessible client-side:
+```js
+window.__nvml.get('count')        // read
+window.__nvml.set('count', 42)    // write — triggers all subscribers
+window.__nvml.subscribe('count', val => { /* ... */ })
+```
+---
+## @computed — Derived Signals
+Computed signals are derived from other signals. Nova code is evaluated server-side at render time to get an initial value. Client-side re-evaluation happens via `/_nvml/run` when dependencies change.
+```nvml
+@computed [
+  doubled=( document.getSignal("count") * 2 ),
+  greeting=( f"Hello, {document.getSignal('name')}!" ),
+  itemCount=( document.getSignal("items").length ),
+  isEven=( document.getSignal("count") % 2 === 0 ),
+]
+```
+The code string is a novac expression evaluated with `document` in scope. Results are stored under the computed name in the signal store and update reactively.
+---
+## @effect — Side Effects
+Effects run Nova code on the server (via `/_nvml/run`) when declared signal dependencies change.
+```nvml
+@effect [
+  // Single dependency → code string
+  count -> (
+    let c = document.getSignal("count")
+    if (c >= 10) {
+      document.toast("You reached 10!", 2000, "success")
+    }
+  ),
+  // Multiple dependencies → [dep1, dep2] list
+  [name, theme] -> (
+    document.console(f"name or theme changed", "log")
+  ),
+  // Wildcard: run on ANY signal change
+  * -> (
+    document.setSignal("lastUpdated", Date.now())
+  ),
+]
+```
+Format: `deps -> (novac code)` where deps is:
+- A single signal name: `count`
+- A bracket list: `[count, name]`
+- Wildcard: `*`
+---
+## @component — Component Definitions
+Define reusable components. A component is a named block of NVML elements that can be instantiated anywhere as `{ComponentName}`.
+```nvml
+@component Card [
+  {div} [
+    class='card',
+    [..]::ss [
+      {padding}='2rem',
+      {border-radius}='10px',
+      {background}='#1e1e1e',
+      {box-shadow}='0 4px 24px #0008',
+    ]
+    @slot header []   // named slot outlet
+    @slot []          // default slot outlet
+    @slot footer []
+  ]
+]
+@component Button [
+  {button} [
+    class='btn',
+    [..]::ss [
+      {background}='#6c63ff',
+      {color}='white',
+      {border}='none',
+      {border-radius}='6px',
+      {padding}='0.6rem 1.5rem',
+      {cursor}='pointer',
+      {font-size}='1rem',
+    ]
+    @slot []
+  ]
+]
+@component Badge [
+  {span} [
+    class='badge',
+    [..]::ss [
+      {background}='#6c63ff22',
+      {color}='#6c63ff',
+      {border-radius}='999px',
+      {padding}='0.2rem 0.7rem',
+      {font-size}='0.8rem',
+    ]
+    @slot []
+  ]
+]
+```
+### Using Components
+Declare used components with `@use`, then use as `{ComponentName}`:
+```nvml
+@use Card, Button, Badge
+@visual [
+  {Card} [
+    @slot header [
+      {h2}='Card Title'
+      {Badge}='New'
+    ]
+    @slot [
+      {p}='Card body content goes here.'
+      {Button}='Save'
+    ]
+    @slot footer [
+      {small}='Last updated today'
+    ]
+  ]
+]
+```
+Inline-defined components (in the same file) are instantiated directly. External components (declared via `@use` but defined elsewhere) render as `<div data-component="Name" data-props="...">` for client-side hydration.
+---
+## @use — Component Imports
+Declare which component names are used in this page. Required for external components; optional but recommended for inline-defined ones.
+```nvml
+@use Card, Button, Modal, Tooltip, Dropdown
+```
+---
+## @slot — Named Slot Content
+Define named slot content at the top level to pass into components:
+```nvml
+@slot header [
+  {h2}='Page Title'
+  {p}='Subtitle'
+]
+@slot footer [
+  {small}='© 2025 novac'
+]
+```
+Inside a `@component`, use `@slot name` as the insertion point:
+```nvml
+@component Layout [
+  {div} [
+    class='layout',
+    {header} [ @slot header ]
+    {main}   [ @slot ]          // unnamed = default slot
+    {footer} [ @slot footer ]
+  ]
+]
+```
+---
+## @route — Client-Side Router
+Define client-side routes. The reactive runtime includes a history API router that renders matching route bodies into `#nvml-router-outlet` (or `<body>` if absent). Route params inject into the signal store.
+```nvml
+@visual [
+  {nav} [
+    {a} [ data-nvml-link='/' ]='Home'
+    {a} [ data-nvml-link='/about' ]='About'
+    {a} [ data-nvml-link='/user/42' ]='Profile'
+  ]
+  {div} [ id='nvml-router-outlet' ]
+]
+@route '/' [
+  {h1}='Home Page'
+  {p}='Welcome!'
+]
+@route '/about' [
+  {h1}='About'
+  {p}='Built with NVML v2.'
+]
+@route '/user/:id' [
+  {h1}='User Profile'
+  {p} [ text -> id ]='Loading...'   // id signal auto-set from :id param
+]
+```
+Navigation: use `data-nvml-link="/path"` on any element, or call `window._nvmlNavigate('/path')` from JS. Route params (`:name`) are automatically written as signals when a route matches, so all bindings on them update reactively.
+---
+## Elements
+Any HTML tag name is valid as `{tagname}`:
+```nvml
+{div} {span} {p} {h1} {h2} {h3} {h4} {h5} {h6}
+{a} {button} {input} {form} {label} {select} {option} {textarea}
+{img} {video} {audio} {canvas} {iframe} {picture} {source}
+{ul} {ol} {li} {dl} {dt} {dd}
+{table} {thead} {tbody} {tfoot} {tr} {td} {th} {colgroup} {col}
+{nav} {header} {footer} {main} {section} {article} {aside} {figure} {figcaption}
+{details} {summary} {dialog} {template} {slot}
+{pre} {code} {blockquote} {cite} {q} {abbr} {time} {mark}
+{svg} {path} {circle} {rect} {line} {polyline} {polygon}
+// ... any valid HTML tag
+```
+### Namespaced Elements
+```nvml
+{element.button}   // → <button>
+{element.input}    // → <input>
+{ui.Card}          // → component named Card (last segment used as tag/component name)
+```
+### Void Elements (self-closing)
+`area base br col embed hr img input link meta param source track wbr`
+```nvml
+{img}   [ src='/logo.png', alt='Logo' ]
+{input} [ type='text', placeholder='Search', id='searchInput' ]
+{br}
+{hr}
+```
+---
+## Properties
+Set inside a `[ ... ]` block with `key=value` syntax:
+```nvml
+{div} [
+  id='main',
+  class='container dark',
+  style='padding: 1rem',
+  tabindex=0,
+  role='main',
+  aria-label='Main content',
+]
+```
+**Boolean properties** (no `=value`) render as bare attributes:
+```nvml
+{input} [ type='checkbox', checked, disabled ]
+{video} [ autoplay, loop, muted, controls ]
+{details} [ open ]
+```
+**Unknown property names** automatically render as `data-<name>`:
+```nvml
+{div} [ my-thing='hello' ]    // → <div data-my-thing="hello">
+```
+**Value types:**
+| Form | Example | Result |
+|------|---------|--------|
+| Single-quoted | `class='hero'` | String |
+| Double-quoted | `id="myDiv"` | String |
+| Paren multiline | `title=(long text)` | String |
+| Number | `tabindex=0` | Number → string |
+| Bare identifier | `type=text` | String |
+| Pipe list | `keywords=\|a, b\|` | Array |
+| Boolean flag | `checked` | bare attribute |
+---
+## Inline Text
+Set element text directly with `{tag}='text'`:
 ```nvml
 {h1}='Page Title'
-{p}='Some text'
+{p}='Some paragraph text.'
+{button}='Click Me'
+{a}='Go Home' [ href='/' ]
+{span}='inline'
+// Combined with property block:
+{h1}='Welcome' [ id='heading', class='hero-title' ]
 ```
-**Namespaced elements** (`namespaces=|element|` in config to enable):
+---
+## One-Way Binding (->)
+Bind an element property to a signal. The element updates automatically whenever the signal changes. The initial DOM value is set from the signal's current value.
 ```nvml
-{element.button} [ ... ]   // → <button>
-{element.div} [ ... ]      // → <div>
+{p}   [ text -> count ]          // textContent mirrors count
+{div} [ html -> richContent ]    // innerHTML with virtual DOM diffing
+{img} [ src -> avatarUrl ]
+{a}   [ href -> currentUrl ]
+{div} [ class -> activeClass ]
+{div} [ style -> dynamicStyle ]
+{div} [ hidden -> isHidden ]
+{input} [ placeholder -> hint ]
+{button} [ disabled -> isLoading ]
+{span} [ aria-label -> statusLabel ]
 ```
-**Nesting:**
+**Bindable prop names:**
+| Prop | Element update |
+|------|----------------|
+| `text` | `element.textContent` |
+| `html` | Virtual DOM patch of `element.innerHTML` |
+| `value` | `element.value` |
+| `checked` | `element.checked` |
+| `class` | `element.className` |
+| `style` | `element.style.cssText` |
+| `href` | `element.href` |
+| `src` | `element.src` |
+| `disabled` | `element.disabled` |
+| `hidden` | `element.style.display` |
+| `placeholder` | `element.placeholder` |
+| Any other name | `element.setAttribute(prop, val)` |
+---
+## Two-Way Binding (<->)
+Syncs an input element's value with a signal in both directions. When the signal changes → input updates. When the user types → signal updates.
+```nvml
+{input}    [ value <-> name, type='text', placeholder='Your name' ]
+{input}    [ checked <-> isLoggedIn, type='checkbox' ]
+{textarea} [ value <-> bio, rows=4 ]
+{select}   [ value <-> selectedTheme ]
+{input}    [ value <-> searchQuery, type='search' ]
+{input}    [ value <-> volume, type='range', min=0, max=100 ]
+```
+Listens on `input` events for `input`/`textarea`/`select`, `change` for everything else. Checkbox `<->` syncs `.checked` (boolean), all others sync `.value` (string).
+---
+## Conditional Rendering (?)
+Conditionally render an element based on signal truthiness. The element is shown/hidden reactively without being destroyed or re-created.
 ```nvml
 {div} [
-  class='card',
-  {h2}='Card Title'
-  {p}='Card body text.'
-  {button} [ onclick='doSomething()', "Click" ]
+  ? isLoggedIn  {div} [ class='dashboard' ]
+  ? isError     {div} [ class='error-box', text -> errorMsg ]
+  ? isLoading   {div} [ class='spinner' ]
 ]
 ```
+Multiple conditions can exist in the same parent. Each conditional element gets `data-nvml-if="signalName"`. The runtime shows/hides reactively when the signal changes. Combine with transitions for animated show/hide:
+```nvml
+? isOpen {div} [ class='modal', opacity ~ fade ]
+? hasNotif {div} [ class='notification', opacity ~ slide ]
+```
 ---
-### `[..]::ss` — element-scoped styles
+## @each — Reactive Lists
-Styles inside `[..]::ss` apply only to the parent element.
-The selector is automatically generated from the element's `id` (if set) or a `data-nvml-id` attribute.
+Render a list from a signal array with keyed diffing. The DOM updates efficiently when the array changes — only affected items are touched.
 ```nvml
-{p} [
-  id='intro',
-  [..]::ss [
-    {color}='#aaa',
-    {font-size}='1.2rem',
-    {margin-top}='1rem',
+{ul} [
+  @each items as item [
+    {li} [ text -> item ]
   ]
-  "Some text."
 ]
 ```
-Inside `[..]::ss`, the `{property}='value'` shorthand defines CSS declarations.
-Full CSS rules can also be written as `{selector} [ property='value' ]`.
+With index variable:
+```nvml
+{ol} [
+  @each todos as todo [
+    {li} [
+      {span} [ text -> todo ]
+    ]
+  ]
+]
+```
+Nested with bindings:
+```nvml
+{div} [ class='list' ]
+  @each users as user [
+    {div} [
+      class='user-card',
+      {h3} [ text -> user ]
+      {p}='Active'
+    ]
+  ]
+]
+```
+`@each` renders a container `<div data-nvml-each="signal" data-nvml-template="...template...">`. The reactive runtime clones the template per item and uses keyed diffing to patch the list when the signal array changes. Update the signal via `window.__nvml.set('items', newArray)` or via a triggered server script with `document.setSignal("items", newArray)`.
 ---
-### `@ss` — global styles
+## Transitions (~)
+Attach CSS enter/leave animations to elements. The transition name generates `@keyframes` rules automatically.
+```nvml
+{div} [ class='modal', opacity ~ fade ]
+{li} [ class='item', opacity ~ slide ]
+{div} [ class='toast', opacity ~ pop ]
+```
+This generates into `<head>`:
+```css
+.nvml-enter-fade { animation: nvml-enter-fade var(--nvml-dur-fade, 0.25s) ease both; }
+.nvml-leave-fade { animation: nvml-leave-fade var(--nvml-dur-fade, 0.25s) ease both; }
+@keyframes nvml-enter-fade { from { opacity:0; transform: translateY(8px); } to { opacity:1; transform: none; } }
+@keyframes nvml-leave-fade { from { opacity:1; transform: none; } to { opacity:0; transform: translateY(8px); } }
+```
+Control duration per transition via CSS variable in `@ss`:
 ```nvml
 @ss [
-  {body} [
-    background='#111',
-    color='white',
-    font-family='system-ui, sans-serif',
+  {:root} [
+    --nvml-dur-fade='0.3s',
+    --nvml-dur-slide='0.15s',
+    --nvml-dur-pop='0.2s',
   ]
-  {.container} [
-    max-width='900px',
-    margin='0 auto',
+]
+```
+The `hide`, `show`, and `remove` mutations also accept a transition name as their last argument:
+```nova
+document.hide("modal", "fade")
+document.show("drawer", "block", "slide")
+document.remove("toast", "pop")
+```
+---
+## Signal References (#)
+Reference a signal value inline using `#signalName`:
+```nvml
+// In @computed and @effect code
+@computed [
+  doubled=( #count * 2 ),
+  greeting=( f"Hello {#name}!" ),
+]
+// As a property value shorthand — equivalent to one-way binding
+{p}   [ text=#count ]      // same as: text -> count
+{img} [ src=#avatarUrl ]   // same as: src -> avatarUrl
+{div} [ class=#theme ]     // same as: class -> theme
+```
+---
+## Scoped Styles — [..]::ss
+Attaches CSS scoped to the parent element only. Renders as a `<style>` block immediately before the element, scoped to the element's `id` (or a generated `data-nvml-id`).
+```nvml
+{div} [
+  id='hero',
+  [..]::ss [
+    {background}='linear-gradient(135deg, #6c63ff, #3ecfcf)',
+    {min-height}='60vh',
+    {display}='flex',
+    {align-items}='center',
+    {justify-content}='center',
+    {padding}='4rem 2rem',
   ]
+  {h1}='Welcome'
 ]
 ```
+Renders as:
+```html
+<style>
+#hero {
+  background: linear-gradient(135deg, #6c63ff, #3ecfcf);
+  min-height: 60vh;
+  ...
+}
+</style>
+<div id="hero">
+  <h1>Welcome</h1>
+</div>
+```
+Full CSS rule blocks inside `[..]::ss`:
+```nvml
+{div} [
+  id='card',
+  [..]::ss [
+    {#card}        [ padding='2rem', border-radius='10px' ]
+    {#card:hover}  [ box-shadow='0 8px 32px #0006' ]
+    {#card h2}     [ font-size='1.4rem', font-weight='600' ]
+    {#card .badge} [ opacity='0.7' ]
+  ]
+]
+```
+Inline string form:
+```nvml
+{p} [ [..]::ss='color: red; font-weight: bold;' ]
+```
 ---
-### `{script}` — scripts
+## Scripts — {script}
+| Property | Values | Description |
+|----------|--------|-------------|
+| `language` / `lang` | `js`, `novac`, `nv`, `nodejs`, or any name registered with `@lang` | Script language (default: `js`) |
+| `scope` | `server`, `client` | Where code runs (default: `client`). For `nodejs` and `@lang` langs, scope is derived from `runtime_language`. |
+| `trigger` | `click`, `input`, `change`, `submit`, `keydown`, ... | Event(s) that trigger a server script. Comma-separated for multiple. |
+| `target` | element `id` | Element to attach the trigger to |
+| `src` | URL | External script source |
+| `defer` | boolean | Add `defer` attribute |
+| `async` | boolean | Add `async` attribute |
-**Client-side JS:**
+Code is set via `[..]::code`:
 ```nvml
 {script} [
   language='js',
   scope='client',
   [..]::code=(
-    document.querySelector('button').addEventListener('click', () => {
-      alert('hello');
+    window.__nvml.subscribe('theme', val => {
+      document.documentElement.setAttribute('data-theme', val);
     });
   )
 ]
 ```
-**Server-side Nova (runs at request time, can mutate the document):**
+---
+## Server-Side Nova Scripts
+`language='novac'` (or `'nv'`) + `scope='server'` with no `trigger` → runs **at render time**. Mutations are baked directly into the HTML. Rendered as an HTML comment.
 ```nvml
 {script} [
-  language='novac',
+  language='nv',
   scope='server',
   [..]::code=(
-    document.setConfig("title", "Dynamic Title")
-    document.set("myElementId", "Dynamic content")
+    document.setTitle("Dynamic Page Title")
+    document.setConfig("description", "Built with novac")
+    document.set("greeting", f"Hello from the server!")
+    document.addStyle(":root { --server-color: #6c63ff; }")
+    document.setSignal("initialCount", 42)
+    document.addClass("hero", "loaded")
   )
 ]
 ```
-**Client-side Nova (compiled to JS and embedded):**
+Output: `<!-- nv server script executed at render time -->`
+---
+## Triggered Server Scripts
+`scope='server'` + `trigger` + `target` → generates client-side JavaScript that POSTs to `/_nvml/run` on the specified event(s) and applies returned mutations to the DOM.
 ```nvml
+{button}='Submit' [ id='submitBtn' ]
 {script} [
-  language='novac',
-  scope='client',
+  language='nv', scope='server',
+  trigger='click', target='submitBtn',
+  [..]::code=(
+    let name = document.getValue("nameInput")
+    if (name equals "") {
+      document.toast("Name is required", 2000, "error")
+      give
+    }
+    document.setSignal("isLoading", true)
+    let result = fetch(https://api.example.com/submit({ name }))
+    document.setSignal("isLoading", false)
+    if (result.ok) {
+      document.toast(f"Welcome, {name}!", 3000, "success")
+      document.setSignal("isLoggedIn", true)
+      document.setSignal("userName", name)
+    } else {
+      document.toast("Submission failed", 2000, "error")
+    }
+  )
+]
+```
+Multiple events (comma-separated):
+```nvml
+{script} [
+  language='nv', scope='server',
+  trigger='click,keydown', target='searchInput',
   [..]::code=(
-    // Nova code compiled via Emitter and embedded as JS
-    print("hello from client")
+    let q = document.getValue("searchInput")
+    let results = fetch(https://api.example.com/search({ q }))
+    document.setSignal("results", results.body.items)
   )
 ]
 ```
-Supported `language` values: `js`, `javascript`, `novac`, `nv`
-Supported `scope` values: `server`, `client` (default: `client`)
+The generated client-side script:
+1. Snapshots the live DOM state (textContent, value, className of all `id`'d elements + current signal state)
+2. POSTs `{ code, live: { elements, state, title, url, query } }` to `/_nvml/run`
+3. Receives `{ mutations }` and applies each via `window.__nvml.applyMutations`
-Script code can also be written as multiline strings using `( ... )` parentheses:
+---
+## Server-Side Node.js Scripts
+`language='nodejs'` (or `'node'`) → runs **in Node.js** at render time (without a trigger) or on-demand via `/_nvml/run-node` (with a trigger). The full Node.js API, `require`, `process`, and `console` are available in scope.
+Both `document` and `bf` are always available in the Node.js scope (same API as Nova server scripts).
 ```nvml
-[..]::code=(
-  multi
-  line
-  code
-)
+// At render time — runs once, mutations baked into HTML
+{script} [
+  language='nodejs',
+  [..]::code=(
+    const os = require('os');
+    document.set('hostname', os.hostname());
+    document.set('platform', process.platform);
+    document.setTitle('Server: ' + os.hostname());
+  )
+]
+// Triggered — runs per event, sends mutations to client
+{button}='Get Server Info' [ id='infoBtn' ]
+{script} [
+  language='nodejs',
+  trigger='click', target='infoBtn',
+  [..]::code=(
+    const os = require('os');
+    document.set('hostname', os.hostname());
+    document.toast('Info loaded', 1500, 'success');
+  )
+]
 ```
+**Comparison — Nova vs nodejs:**
+| Feature | `language='nv'` | `language='nodejs'` |
+|---------|-----------------|---------------------|
+| Runtime | Nova interpreter | Node.js VM (`vm.runInContext`) |
+| `require()` | ✗ | ✓ (full Node.js modules) |
+| Async/await | ✗ (Nova sync) | ✓ |
+| Nova syntax | ✓ | ✗ |
+| `document` API | ✓ | ✓ |
+| `bf` object | ✓ | ✓ |
+| Render-time | ✓ | ✓ |
+| Triggered | ✓ | ✓ (via `/_nvml/run-node`) |
 ---
-### `[..]` parent reference
+## @lang — Custom Language Extensions
-`[..]` always refers to the nearest parent element. It's used for setting properties on the parent:
+Register a completely new language that can be used in `{script}` blocks. This is the plugin system for NVML — you can implement any language on top of it.
 ```nvml
-{div} [
-  [..]::ss [ {color}='red', ]       // set ss on the div
-  [..]::code=( console.log(1) )     // set code on the div
-  [..]::id='myDiv'                  // set id on the div
+@lang {languageName} [
+  runtime_language="nv"     // "nv" | "js" | "nodejs"
+  config=""                 // optional: JSON string, or path to a config.json file
+  src="path/to/impl.js"     // path to implementation file (server or client)
+  code=(                    // or: inline implementation code
+    ...implementation...
+  )
+]
+```
+### `runtime_language` — Scope & Execution Model
+| Value | Scope | How It Runs |
+|-------|-------|-------------|
+| `"nv"` / `"nova"` / `"novac"` | **Server** | Implementation + user code run in Nova interpreter. Same as a `scope='server'` nv script. |
+| `"nodejs"` / `"node"` | **Server** | Implementation + user code run in Node.js VM (`vm.runInContext`). Full `require`, `process`, etc. |
+| `"js"` | **Client** | Implementation is injected into the page as a `<script>`, then user code follows in the same IIFE. |
+### Object Availability in Every Lang Scope
+All three runtime contexts always receive:
+| Object | Description |
+|--------|-------------|
+| `document` | The full NVML document API (mutations collected and applied) |
+| `bf` | The Brainfuck runtime object (see [bf — Brainfuck Runtime](#bf--brainfuck-runtime)) |
+| `request` | Request context (triggered scripts): `{ method, path, query, state, elements }` |
+### How It Works
+**Server-side (`nv` or `nodejs`):**
+1. At executor time, NVML reads the `@lang` definition and stores a `NvmlLangDef` in `doc.langs[name]`.
+2. When a `{script}[language='myLang']` element is encountered, the executor concatenates `langDef.code + '\n' + userCode` and runs the combined code in the appropriate runtime (Nova runner or Node.js VM).
+3. At render time, the script element renders as a comment (render-time) or a fetch-based event handler (triggered).
+**Client-side (`js`):**
+1. The `@lang` implementation code is embedded in a `<script>` IIFE on the page.
+2. Each `{script}[language='myLang']` block appends user code into the same IIFE, with `bf` available via `window.__nvml_bf`.
+### Examples
+**A simple template language (client-side):**
+```nvml
+@lang tmpl [
+  runtime_language="js",
+  code=(
+    function tmplRender(template, data) {
+      return template.replace(/\{\{(\w+)\}\}/g, (_, k) => data[k] ?? '');
+    }
+  )
+]
+{script} [
+  language='tmpl',
+  [..]::code=(
+    const result = tmplRender('Hello, {{name}}!', { name: 'World' });
+    document.getElementById('out').textContent = result;
+  )
+]
+```
+**A data-processing language (server-side Node.js):**
+```nvml
+@lang dataql [
+  runtime_language="nodejs",
+  code=(
+    const fs = require('fs');
+    function query(file, fn) {
+      const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+      return Array.isArray(data) ? data.filter(fn) : data;
+    }
+  )
+]
+{script} [
+  language='dataql',
+  [..]::code=(
+    const users = query('./data/users.json', u => u.active);
+    document.setSignal('users', users);
+    document.set('userCount', String(users.length));
+  )
+]
+```
+**A Nova-powered macro language (server-side Nova):**
+```nvml
+@lang macros [
+  runtime_language="nv",
+  code=(
+    func defineCard(title, content) {
+      document.setHTML("cardTitle",   f"<h2>{title}</h2>")
+      document.setHTML("cardContent", f"<p>{content}</p>")
+    }
+  )
+]
+{script} [
+  language='macros',
+  [..]::code=(
+    defineCard("Welcome", "This content came from a custom Nova macro language.")
+  )
+]
+```
+**Config file (JSON):**
+```nvml
+@lang myLang [
+  runtime_language="nodejs",
+  config="langs/mylang.config.json",
+  src="langs/mylang.js"
 ]
 ```
+The `config` string (or the content of the JSON file) is available inside the implementation code via the `__langConfig` variable (parsed JSON object), injected before the implementation code runs.
 ---
-### Pipe lists
+## bf — Brainfuck Runtime
+**`bf` is available in every language scope** — Nova server scripts, Node.js server scripts, and client-side JavaScript. It's always injected automatically; no import or setup required.
+On the client, `bf` is exposed as `window.__nvml_bf`. A fresh instance can be created with `window.__nvml_bf_make()`.
+### Object Properties & Methods
+| Member | Type | Description |
+|--------|------|-------------|
+| `bf.tape` | `Uint8Array(30000)` | The cell tape. 30,000 cells, each a byte (0–255). |
+| `bf.pointer` | `number` (read-only) | Current data pointer index. |
+| `bf.output` | `string` (read-only) | Accumulated output from `.` instructions. |
+| `bf.input` | `string` (read/write) | Input buffer consumed by `,` instructions. |
+| `bf.cell(n?, v?)` | `number` | Get cell `n` (default: current). If `v` given, set cell `n` to `v & 0xFF`. |
+| `bf.run(code, input?)` | `string` | Execute BF source string. Returns output. |
+| `bf.reset()` | `bf` | Clear tape, pointer, and I/O buffers. Returns `bf` for chaining. |
+### Brainfuck Instruction Set
+| Instruction | Action |
+|-------------|--------|
+| `>` | Move pointer right (wraps at 30000) |
+| `<` | Move pointer left (wraps at 0) |
+| `+` | Increment cell (wraps 255 → 0) |
+| `-` | Decrement cell (wraps 0 → 255) |
+| `.` | Output cell as ASCII char → appended to `bf.output` |
+| `,` | Read one char from `bf.input` into cell (EOF → 0) |
+| `[` | Jump past matching `]` if cell is 0 |
+| `]` | Jump back to matching `[` if cell is non-zero |
+All other characters in the source are silently ignored (standard BF behaviour).
+### Safety Limits
+- Maximum **10,000,000 operations** per `bf.run()` call before throwing `Error('[bf] max ops exceeded')`.
+- Tape wraps both at the high end (30000 → 0) and low end (0 → 29999).
-For multi-value config keys:
+### Examples
 ```nvml
-@config [
-  namespaces=|element, custom|,
-  keywords=|nova, web, kit|,
+// Server-side (nv) — compute something with BF and put it in the page
+{script} [
+  language='nv', scope='server',
+  [..]::code=(
+    // Print "Hello World!" using Brainfuck
+    let bfHello = "++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++."
+    let result = bf.run(bfHello)
+    document.set("bfOutput", result)
+  )
+]
+// Server-side (nodejs) — same thing
+{script} [
+  language='nodejs',
+  [..]::code=(
+    const result = bf.run('++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.');
+    document.set('bfOutput', result);
+  )
+]
+// Client-side — run BF in the browser
+{script} [
+  language='js', scope='client',
+  [..]::code=(
+    const result = window.__nvml_bf.run('++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.');
+    document.getElementById('bfOutput').textContent = result;
+    // Fresh instance for another program
+    const bf2 = window.__nvml_bf_make();
+    bf2.input = 'A';
+    bf2.run(',.');  // echo 'A'
+    console.log(bf2.output); // 'A'
+  )
 ]
 ```
 ---
-## `document` API
-| Method | Description |
-|--------|-------------|
-| `document.setIndex(nvmlFile)` | Set NVML file for the `/` route |
-| `document.setPage(route, nvmlFile)` | Map a URL path to an NVML file |
-| `document.setNotFound(nvmlFile)` | Custom 404 page |
-| `document.serve(port)` | Start HTTP server (default: 3000) |
-| `document.stop()` | Stop the server |
-| `document.middleware(fn)` | Add middleware `fn(req, res, next)` |
-| `document.static(urlPath, dirPath)` | Serve static files from a directory |
-| `document.setHeader(key, value)` | Set a default HTTP response header |
-Routes support `:param` segments: `document.setPage("/user/:id", "user.nvml")`
+```nvml
+// Plain JavaScript — direct embed
+{script} [
+  language='js', scope='client',
+  [..]::code=(
+    window.__nvml.subscribe('theme', val => {
+      document.documentElement.className = val;
+    });
+    // restore theme from localStorage
+    const saved = localStorage.getItem('theme');
+    if (saved) window.__nvml.set('theme', saved);
+  )
+]
+// External script
+{script} [ src='/js/chart.js', defer ]
+{script} [ src='https://cdn.jsdelivr.net/npm/alpinejs', async ]
+```
 ---
-## Server-side Nova script API
+## document API
+Available inside `scope='server'` Nova scripts in both contexts (render time and triggered).
-Inside `scope='server'` Nova scripts, a `document` proxy is available:
+### At Render Time (baked into HTML)
 | Method | Description |
 |--------|-------------|
-| `document.setConfig(key, val)` | Set a config value |
-| `document.getConfig(key)` | Get a config value |
-| `document.setTitle(title)` | Set page title |
-| `document.setMeta(key, val)` | Set a meta tag value |
-| `document.set(id, content)` | Set element text content by id |
-| `document.get(id)` | Get element text content by id |
-| `document.addStyle(css)` | Append to global stylesheet |
+| `document.setConfig(key, val)` | Set a config key |
+| `document.setTitle(title)` | Set `<title>` |
+| `document.setMeta(key, val)` | Set a meta value |
+| `document.set(id, text)` | Set element textContent by id |
+| `document.setHTML(id, html)` | Set element innerHTML by id |
+| `document.get(id)` | Get element text by id |
+| `document.setProp(id, key, val)` | Set element attribute by id |
+| `document.getProp(id, key)` | Get element attribute by id |
+| `document.addClass(id, cls)` | Append class to element |
+| `document.setClass(id, cls)` | Replace element class |
+| `document.addStyle(css)` | Append to global styles |
+| `document.addElementStyle(id, css)` | Append to element scoped CSS |
+| `document.hide(id)` | Set `display:none` on element |
+| `document.show(id, display?)` | Set `display:block` or custom |
+| `document.setSignal(name, val)` | Set signal initial value (baked into state JSON) |
+| `document.config` | Direct reference to `doc.config` object |
+### At Request Time (triggered via `/_nvml/run`)
+All render-time methods plus reads from the live DOM snapshot:
+| Method | Description |
+|--------|-------------|
+| `document.get(id)` | Live `textContent` of element |
+| `document.getValue(id)` | Live `.value` of input |
+| `document.getClass(id)` | Live `.className` |
+| `document.getConfig(key)` | Live config (title, url, etc.) |
+| `document.getSignal(name)` | Current signal value from client |
+| `document.setSignal(name, val)` | Push signal update to client |
+| `document.remove(id, transition?)` | Remove element from DOM |
+| `document.appendChild(id, html)` | Append HTML child to element |
+| `document.insertBefore(id, html)` | Insert HTML before element |
+| `document.insertAfter(id, html)` | Insert HTML after element |
+| `document.setStyle(id, key, val)` | Set inline style property |
+| `document.setCSSVar(name, val)` | Set CSS custom property on `:root` |
+| `document.setAttr(id, key, val)` | Set attribute |
+| `document.removeAttr(id, key)` | Remove attribute |
+| `document.removeClass(id, cls)` | Remove class |
+| `document.toggleClass(id, cls, force?)` | Toggle class |
+| `document.focus(id)` | Focus element |
+| `document.blur(id)` | Blur element |
+| `document.scroll(id, behavior?)` | Scroll element into view |
+| `document.patchList(id, items, template, key?)` | Keyed list diff and patch |
+| `document.navigate(path)` | Client-side router navigate |
+| `document.reload()` | Reload page |
+| `document.redirect(url)` | Full redirect |
+| `document.toast(msg, duration?, type?)` | Show NVML toast (`info` `success` `error`) |
+| `document.console(msg, level?)` | `console.log/warn/error` in browser |
+| `document.alert(msg)` | Browser `alert()` |
+| `document.push(signalName, value)` | SSE-push signal update to all clients |
+| `document.pushMutations(mutations)` | SSE-push mutation array to all clients |
 ---
-## How it works
+## Reactive Runtime API (client-side)
+Injected into `<head>` automatically when `@state`, `@computed`, or `@effect` is present. Available as `window.__nvml`:
+```js
+// Signals
+window.__nvml.get('count')                    // read signal value
+window.__nvml.set('count', 42)                // write signal (triggers all subscribers + effects)
+window.__nvml.subscribe('count', val => { })  // subscribe; returns unsub function
+window.__nvml.notify('count')                 // manually trigger subscribers
+window.__nvml.state                           // raw signal object (direct access)
-Each request:
-1. The matching NVML file is read from disk (re-read every request — always fresh)
-2. NVML is tokenized → parsed → AST
-3. AST is executed: `@config` populates metadata, `@visual` builds an element tree
-4. `scope='server'` script blocks run immediately, mutating the document
-5. The document is rendered to HTML: `@config` → `<head>`, element tree → `<body>`
-6. `scope='client'` scripts are embedded as `<script>` tags
-7. HTML is sent as the response
+// Mutations
+window.__nvml.applyMutations([               // apply a mutation array
+  { type: 'setText', id: 'myEl', value: 'Hello' },
+  { type: 'setSignal', name: 'count', value: 5 },
+])
+// Triggered server script
+window.__nvmlRun(`nova code string`)         // POST to /_nvml/run, apply mutations
+// Router
+window._nvmlNavigate('/path')               // client-side navigate
+```
+---
+## Virtual DOM Diffing
+The `setHTML` mutation and `html ->` binding use structural diffing instead of `innerHTML =`. The algorithm:
+1. Walk old and new child nodes in parallel
+2. Append missing nodes, remove stale nodes
+3. For matching element nodes: diff attributes (`_diffAttrs`), recurse into children (`_diffChildren`)
+4. For text nodes: update `textContent` only if changed
+5. Replace mismatched node types or tag names entirely
+This means you can call `document.setHTML("section", newHTML)` or bind `html -> richContent` in a triggered script without losing input focus, scroll position, or event listeners on unchanged subtrees.
+The `patchList` mutation uses **keyed diffing**: existing list items are matched by a key field (or index), updated in-place, and stale items are removed — matching the behaviour of React/Vue key-based list reconciliation.
 ---
-## Installation
+## Server-Sent Events (SSE)
+NVML opens a persistent `GET /_nvml/sse` connection automatically when the page loads. The runtime reconnects after 3 seconds if the connection drops.
-Copy the `kitnovacweb/` directory into your `nova_modules/` folder:
+From any triggered Nova script, push updates to **all connected clients** simultaneously:
+```nova
+// Push a signal update to all clients
+document.push("liveScore", 42)
+document.push("onlineCount", 128)
+// Push arbitrary mutations to all clients
+document.pushMutations([
+  { type: "setText", id: "ticker", value: "BTC $65,000" },
+  { type: "toast", value: "Price updated!", duration: 2000, type: "info" },
+  { type: "setSignal", name: "lastPrice", value: 65000 },
+])
 ```
-nova_modules/
-  kitnovacweb/
-    kitdef.js
-    index.nova
-    nova.kit.json
-    nvml/
-      index.js
-      lexer.js
-      parser.js
-      executor.js
-      renderer.js
+SSE event types emitted by the server:
+| Event name | Data format | Description |
+|------------|-------------|-------------|
+| `signal` | `{ "name": "...", "value": any }` | Update one signal on all clients |
+| `mutations` | `[{ type, ... }, ...]` | Apply mutation array on all clients |
+This enables real-time features (live scores, dashboards, chat, notifications) without WebSockets.
+---
+## Mutation Types — Full Reference
+All returned from `/_nvml/run` as `{ mutations: [...] }` and applied by `window.__nvml.applyMutations`. Also usable directly from client JS.
+| `type` | Fields | Description |
+|--------|--------|-------------|
+| `setText` | `id, value` | `element.textContent = value` |
+| `setHTML` | `id, value` | Virtual-DOM patch of `innerHTML` |
+| `setProp` | `id, key, value` | `element.setAttribute(key, value)` |
+| `setAttr` | `id, key, value` | `element.setAttribute(key, value)` |
+| `removeAttr` | `id, key` | `element.removeAttribute(key)` |
+| `addClass` | `id, value` | `element.classList.add(value)` |
+| `removeClass` | `id, value` | `element.classList.remove(value)` |
+| `toggleClass` | `id, value, force?` | `element.classList.toggle(value, force)` |
+| `setClass` | `id, value` | `element.className = value` |
+| `addStyle` | `value` | Append `<style>` to `<head>` |
+| `addStyle` | `id, value` | Append scoped CSS for element |
+| `setStyle` | `id, key, value` | `element.style[key] = value` |
+| `setCSSVar` | `name, value` | `document.documentElement.style.setProperty(name, value)` |
+| `hide` | `id, transition?` | `display:none` with optional CSS transition |
+| `show` | `id, value?, transition?` | `display:block` or custom, with optional transition |
+| `remove` | `id, transition?` | Remove element from DOM with optional transition |
+| `appendChild` | `id, html` | Parse and append HTML as child |
+| `insertBefore` | `id, html` | Insert parsed HTML before element |
+| `insertAfter` | `id, html` | Insert parsed HTML after element |
+| `focus` | `id` | `element.focus()` |
+| `blur` | `id` | `element.blur()` |
+| `scroll` | `id, behavior?` | `element.scrollIntoView({ behavior })` |
+| `setSignal` | `name, value` | `window.__nvml.set(name, value)` |
+| `patchList` | `id, items, template, key?` | Keyed list diff and update |
+| `navigate` | `path` | Client-side router navigate |
+| `reload` | — | `location.reload()` |
+| `redirect` | `url` | `location.href = url` |
+| `alert` | `value` | `alert(value)` |
+| `toast` | `value, duration?, type?` | NVML toast (`info` `success` `error`) |
+| `console` | `value, level?` | `console[level](value)` |
+| `setConfig` | `key, value` | `key === 'title'` → `document.title = value` |
+---
+## Pipe Lists
+Multi-value syntax surrounded by `|`:
+```nvml
+@config [
+  stylesheet=|reset.css, main.css, theme.css|,
+  scripts=|vendor.js, app.js|,
+  keywords=|nova, reactive, web|,
+]
 ```
-Then in your Nova file:
+Generates one `<link>`/`<script>` per value for `stylesheet`/`scripts`. Joins with `, ` for `keywords`.
+---
+## kitnovacweb Integration
+Serve NVML files from a novac program:
 ```nova
 import "kitnovacweb"
+document.setIndex("index.nvml")
+document.setPage("/about", "about.nvml")
+document.setPage("/user/:id", "user.nvml")
+document.setNotFound("404.nvml")
+document.static("/public", "./public")
+document.middleware(func(req, res, next) => {
+  core.print(f"{req.method} {req.url}")
+  next()
+})
+document.setHeader("X-Powered-By", "novac")
+document.serve(3000)
+```
+| Method | Description |
+|--------|-------------|
+| `document.setIndex(file)` | NVML file for `/` |
+| `document.setPage(route, file)` | Map route to NVML file |
+| `document.setNotFound(file)` | 404 page |
+| `document.serve(port)` | Start HTTP server |
+| `document.stop()` | Stop server |
+| `document.middleware(fn)` | Add `fn(req, res, next)` middleware |
+| `document.static(urlPath, dirPath)` | Serve static files from directory |
+| `document.setHeader(key, val)` | Set a default response header |
+---
+## Full Example
+```nvml
+@config [
+  title='Counter App',
+  lang='en',
+  charset='UTF-8',
+  theme-color='#6c63ff',
+]
+@state [
+  count=0,
+  message='Click + or − to change the count.',
+  isNegative=false,
+]
+@computed [
+  doubled=( document.getSignal("count") * 2 ),
+  absCount=( Math.abs(document.getSignal("count")) ),
+]
+@effect [
+  count -> (
+    let c = document.getSignal("count")
+    document.setSignal("isNegative", c < 0)
+    if (c >= 10) {
+      document.toast(f"Reached {c}!", 2000, "success")
+    }
+  ),
+]
+@ss [
+  {:root} [ --brand='#6c63ff', --surface='#1e1e1e', --nvml-dur-fade='0.25s' ]
+  {*}    [ box-sizing='border-box', margin='0', padding='0' ]
+  {body} [ font-family='system-ui, sans-serif', background='#111', color='#eee', display='flex', align-items='center', justify-content='center', min-height='100vh' ]
+  {.card}     [ background='var(--surface)', border-radius='12px', padding='2.5rem 3rem', text-align='center', box-shadow='0 4px 32px #0008', min-width='320px' ]
+  {.count}    [ font-size='4rem', font-weight='700', margin='1rem 0', transition='color 0.2s' ]
+  {.negative} [ color='#fc8181' ]
+  {.controls} [ display='flex', gap='1rem', justify-content='center', margin-top='1.5rem' ]
+  {button}    [ background='var(--brand)', color='white', border='none', border-radius='8px', padding='0.7rem 2rem', font-size='1.1rem', cursor='pointer', transition='background 0.15s' ]
+  {button:hover} [ background='#5548e0' ]
+  {.sub} [ font-size='0.85rem', color='#888', margin-top='0.75rem' ]
+]
+@visual [
+  {div} [
+    class='card',
+    {h1}='Counter'
+    {div} [
+      id='countDisplay',
+      class='count',
+      text -> count,
+    ]
+    {p} [ id='msg', text -> message ]
+    {div} [
+      class='controls',
+      {button}='−' [ id='decBtn' ]
+      {button}='＋' [ id='incBtn' ]
+      {button}='Reset' [ id='resetBtn' ]
+    ]
+    {p} [
+      class='sub',
+      'Doubled: ',
+      {span} [ id='doubledDisplay', text -> doubled ]
+    ]
+  ]
+  // Server scripts
+  {script} [
+    language='nv', scope='server', trigger='click', target='incBtn',
+    [..]::code=(
+      let c = document.getSignal("count")
+      document.setSignal("count", c + 1)
+      document.set("msg", f"Incremented to {c + 1}")
+    )
+  ]
+  {script} [
+    language='nv', scope='server', trigger='click', target='decBtn',
+    [..]::code=(
+      let c = document.getSignal("count")
+      document.setSignal("count", c - 1)
+      document.set("msg", f"Decremented to {c - 1}")
+    )
+  ]
+  {script} [
+    language='nv', scope='server', trigger='click', target='resetBtn',
+    [..]::code=(
+      document.setSignal("count", 0)
+      document.set("msg", "Reset to zero.")
+      document.toast("Counter reset", 1500, "info")
+    )
+  ]
+  // Client-side: add/remove .negative class based on isNegative signal
+  {script} [
+    language='js', scope='client',
+    [..]::code=(
+      window.__nvml.subscribe('isNegative', neg => {
+        document.getElementById('countDisplay').classList.toggle('negative', neg);
+      });
+    )
+  ]
+]
 ```