# LumenJS V2 — Complete Reference for AI Models

> **Audience note for the reader (human or AI):** this document assumes you already know Vue and/or React well, and explains LumenJS **by contrast**. Wherever LumenJS syntax visually resembles Vue or React, assume it behaves like Vue/React **unless this document explicitly says otherwise**.

> **Target version: LumenJS V2, current release `2.5.3`** (`@lmjs/cli` +
> `@lmjs/core`, released together). Upgrading notes are in §13. V2 is a ground-up rewrite of the reactive
> engine, CLI, and build pipeline (`@lmjs/core`/`@lmjs/cli`, both published on
> npm). The single biggest change from V1: **`bind=` is gone.** V1 required
> every reactive variable to be explicitly declared reactive via `bind="name"`
> on an ancestor element; V2 makes every top-level `var`/`let`/`const` in a
> view's `<script>` (and in `index.js`/project scripts) automatically
> reactive, no declaration needed. If you're reading V1 code or an older
> guide that mentions `bind=`, that's V1 — do not mix it into V2 code, and
> see §5 below for what replaced it. Everything else — directives, routing,
> the BaaS query DSL, Mobius CSS — carries over from V1 largely unchanged;
> this document calls out every place it doesn't.

**Sources**: `@lmjs/core`'s real source (`packages/core/src/*.js` — `_re.js`
the reactive engine, `walk.js` the AST rewrite that makes top-level
declarations reactive, `ws.js` the realtime/HTTP client, `lstnrs.js` event
delegation), `@lmjs/cli`'s real source (`packages/cli/lib/fcs.js`), and the
V1 reference this document supersedes for anything not called out as
changed.

---

## 1. What LumenJS is

LumenJS is a small, **no-virtual-DOM** reactive framework. `.view` files are
plain HTML+JS+CSS that you write and edit with no build step. During
development (`lm serve`) the browser interprets them directly. For
production, `lm build` produces one deployable bundle with every view and
its `<script>` already compiled (since 2.5.1), so the shipped runtime has no
parser and pages render immediately. You never write a build config. It is paired with a companion CSS framework,
**Mobius CSS**, supplying utility classes (`w50`, `p20`, `fs16`, `c`, `l`,
`r`, ...) and layout tags (`<flx>`, `<tbl_nm>`, `<rw>`, `<cl>`) — not LumenJS
directives, Mobius's own flexbox/table abstraction. There is a companion CLI,
`@lmjs/cli` (`lm`/`lu`/`lumen`), that scaffolds, serves, and builds projects.

### Mental model, contrasted with Vue/React

| Concept | Vue / React | LumenJS V2 |
|---|---|---|
| Compilation | Vue SFCs / JSX compile to render functions | None to configure. `.view` files are HTML; `lm serve` interprets them live and `lm build` precompiles them automatically |
| State declaration | `data()`/`ref()`/`useState()` | **Any top-level `var`/`let`/`const` in a `<script>` tag is automatically reactive** — no declaration step (§5) |
| Routing | A router library with route config | URL path segments map directly to nested view files on disk; `nodes[n]` gives you the segments at runtime |
| Global store | Vuex/Pinia/Redux/Context | `_vt.Global` — cross-view state that survives navigation (§5.2), plus the older `globals` object (persisted to `localStorage`) |
| List rendering | `v-for` / `.map()` | `:for` — similar syntax, also accepts a bare integer to repeat N times |
| Conditional rendering | `v-if`/`v-else-if`/`v-else` | `:if`/`:else-if`/`:else` — same chaining semantics |
| Two-way form binding | `v-model` | Does not exist; forms are handled wholesale via `o-sub`/`b-sub` |
| Event binding | `@click` | `@click` — same syntax, handlers receive `(ev, el)`, `el` a jQuery-shim-wrapped element |
| HTTP client | fetch/axios | `API.get/post/put/delete/patch(path, data, headers, api_index)`, backends configured in `config.json` or the vault (§10) |
| Lifecycle hooks | `onMounted`/`useEffect` | `@before-render`/`@after-render` on `:for`/`:if` elements, or mount-only on any element (§5.3); `@init` for one-way data into a subview mount (§4) — new in V2 |
| npm packages | native | Real npm imports in `index.js`/project scripts, resolved at build time (§11) — new in V2 |

---

## 2. Project anatomy

```
src/
  index.js            # bootstrap — Reactor() call, runs once
  index.html          # shell HTML + mount point
  config.json         # API backends + dev server + FTP deploy config
  css/                # plain CSS
  js/                 # lm.js (the built @lmjs/core runtime) + extra scripts
  views/              # every .view file = one URL route
    home.view
    account/
      dashboard.view       -> /account/dashboard
      widgets/
        header.view         -> shared chrome, not a route
  tpls/                # row templates, tpl="name", used only on a :for element
  comps/               # optional: also searched for tpl="name" templates (comp= itself was removed)
package.json           # real npm dependencies for your own code (§11) — new in V2
```

`lm create <name>` scaffolds this in the current directory (not a new
subfolder). `lm serve` runs the dev server with hot reload.
`lm build --serverless` produces a static SPA in `dist/`, and adding
`--deploy` uploads it over SFTP/FTP using the `ftp` block in `config.json`.
Plain `lm build` produces a self-hosting Node server bundle instead. Need
real jQuery + a plugin? See selective plugin bundling (§12).

---

## 3. Bootstrapping: `Reactor(...)`

Unchanged from V1:

```js
Reactor({
  App: "[main]",           // mount target selector — any real selector works
  defaultView: "home",
  authView: "login",
  init: function () { /* runs once, before first render */ },
  tick: function () { /* runs after every re-render, anywhere */ },
  auth: function () { return true; },
});
```

---

## 4. Views, components, templates

Two kinds of reusable HTML in V2:

| Kind | Folder | Invoked with | Maps to a URL? |
|---|---|---|---|
| View | `views/` | automatically, by URL, or `view="path"` | Yes (top-level) / No (sub-view) |
| Template | `tpls/` (or `comps/`) | `tpl="name"` on a `:for` element only | Never |

**`comp="name"` was removed in 2.4.1.** It renders nothing and logs a
`[LumenJS]` error that names the replacement: put the `:for` on the element
and use `tpl=`, or use `view=` for a block that needs its own state.

```html
<div>
    This is your text: {{text}}
</div>
<script>
    var text = "Hello World!";   // reactive automatically — no bind= needed (§5)
</script>
<style>
    .textColor { color: green; }
</style>
```

A sub-view: `<div view="child"></div>`. A `<settings>` block still controls
chrome/auth per view (`hasNav`, `hasHeader`, `hasFooter`, `requireAuth`).
In V2, any bare attribute on a layout element (e.g. `<nav nav>`) declares a
widget region, filled from `src/views/widgets/<name>.view` by default. A
widget keeps its DOM and state across navigation.

**Per-instance scoping (new in V2, real behavior change from V1).** Every
mounted instance of the same subview file gets its own independent
variable scope — `_vt.View.views[i].vars` for the `i`-th subview mounted
inside a given view (nesting recursively: `_vt.View.views[0].views[2].vars`
for a subview hosted inside another subview). Mount the same subview twice
and each instance's top-level `var`s, and even its own `function`
declarations, are fully isolated — no collision, unlike V1 where every
instance silently shared one flat scope. A subview instance can still read
any variable it doesn't declare itself from its parent's scope (same
shadow-then-fallback rule as `_vt.Global` in §5.2). You never address
`_vt.View.views[i]` directly — this is what the engine does under the hood
when it compiles a subview's `<script>`; it's documented here because it
explains *why* two instances of the same subview never collide, which was
not true in V1.

**`@init="handlerName"` — one-way data into a subview mount (new in V2).**
For passing data from a parent view into a specific subview instance at
mount time (the `:data=` attribute some early V2 builds had is gone —
`@init` replaced it before it ever shipped):

```html
<div view="widgets/coin-price" @init="giveCoinId" :for="coins as coin"></div>
<script>
    function giveCoinId(ev, el, vrs) {
        return { coinId: vrs.coin.id };   // merged into this instance's own vars
    }
</script>
```

The handler's return value (a plain object) is merged into that mount's
own `vars` before its first render. `@init` handlers must be synchronous —
there's no awaited variant. For the specific case of a subview mounted
once per `:for` item purely to *render*, not to hold independent state
(a product card, a list row), prefer `tpl=` instead (§4b) — it's simpler
and doesn't create an isolated instance at all.

### 4b. `tpl=` — list-row templates (new syntax restriction in V2)

**V2 allows `tpl=` only on a `:for` element** (V1 allowed it anywhere). On
any other element it renders nothing and logs a `[LumenJS]` error. The
template is rendered once per row, *inside* that row's own scope: no
isolated `vars`, no `@init`, it sees the loop item and everything the
loop can see:

```html
<li :for="products as item; lok" tpl="product-card"></li>
```

```html
<!-- src/tpls/product-card.tpl -->
<div class="product-card">{{ item.name }} — ${{ item.price }} (row {{ lok }})</div>
```

A `.tpl` file may contain a `<script>`. It runs once per row, in that row's
scope, so it can read the loop item, but it does not give the row state of
its own. Use `view=` + `@init` instead if a list item genuinely needs
independent state or its own lifecycle.

---

## 5. Reactivity — the real V1→V2 change

### 5.1 No more `bind=` — every top-level declaration is reactive

**In V1**, a variable was tracked only if an ancestor element carried
`bind="varName"`, and had to be declared with `var` (never `let`/`const`).
**In V2, neither restriction exists.** Every top-level `var`, `let`, or
`const` in a view's `<script>` block is automatically reactive — the build
pipeline (`walk.js`) parses the script, finds top-level declarations, and
rewrites references to them into the reactive engine's own tracked storage.
You never write `bind=` at all:

```html
<div>
    <p>My name is: {{name}}</p>
</div>
<script>
    let name = "Raouf";   // reactive automatically, any of var/let/const
</script>
```

Mutating the variable later (`name = "someone else"`) triggers a re-render
of whatever interpolates it — no explicit subscription, no `bind` list to
maintain, no silent "forgot to bind it" failure mode. Function *declarations*
(`function fn(){}`) are deliberately **not** made reactive — they stay real
globals, so `onclick="fn()"`-style inline handlers keep working.

### 5.2 `_vt.Global` — state that survives navigation

A view's own top-level variables reset on navigation away and back (a fresh
view mount). For state that must survive navigation — an app-wide `isAdmin`
flag, a service-client instance — declare it in `index.js` instead of a
view's `<script>`; V2 extends the same reactive rewrite to `index.js` and to
any `/js/*.js` file your `index.html` references via `<script src>`. These
land in `_vt.Global` (a permanent root, unlike a view's own `_vt.View`,
which gets replaced wholesale on every navigation) — a view's own variable
of the same name shadows the global one, real JS scoping. No `<script>` tag
is needed for `index.js` in `index.html` — the runtime fetches and runs it
itself.

### 5.3 `@before-render` / `@after-render` — lifecycle hooks (new in V2)

Valid on `:for` and `:if`/`:else-if`/`:else` elements, and — mount-only, no
before/after distinction — on any plain element. Handler signature matches
`@click` etc.: `(ev, el)`, where `ev.cType` is `"before-render"`/
`"after-render"`, plus `ev.items`/`ev.actions` (`:for`) or `ev.visible`
(`:if`/`:else`). Both fire on first render too, so one `@after-render`
handler covers "initialize" and "re-initialize after a data change" — no
separate manual bootstrap call needed. Use this for anything that owns DOM a
reactive re-render would otherwise silently replace out from under it (a
carousel, a chart library):

```html
<div :for="items as item" @after-render="initCarousel">
    ...
</div>
<script>
    function initCarousel(ev, el) {
        if (ev.cType !== "after-render") return;
        // (re)initialize whatever plugin owns this DOM
    }
</script>
```

### 5.4 `watch`, `tick`, `globals`, `cookies`, `nodes`

These work as in V1: a single global `watch = { varName: fn }` object
(reassigning it wholesale still overwrites previously registered watchers —
the same sharp edge as V1); `tick()` inside `Reactor()`; `globals`
(persisted to `localStorage`, saved on change); `cookies`
(`.setItem`/`.getItem`/`.removeItem`); `nodes` (the URL path, pre-split).

**There is no `session` global in V2.** Use the browser's `sessionStorage`
directly, with `JSON.stringify`/`JSON.parse` for objects.

**A function call inside `{{ }}` is evaluated when the block renders and is
not re-run when the data it reads changes.** `{{ total() }}` stays stale
after `items.push(...)`. Keep the value in a top-level variable and update
it, or interpolate the data directly (`{{ items.length }}`).

### 5.4b `wait()` / `resume()` and the loader

`wait()` pauses rendering and `resume()` resumes it. Neither shows or
hides the page loader. The loader is entirely under your control:
`_loader.show()` / `_loader.hide()`.

### 5.5 Layout slots and HST versioning (new in V2)

Layouts support named slots (`slot="name"` on both the layout's placeholder
and the view content that fills it), a generalization of V1's single-slot
layout model. The compiled view/layout wire format (HST) is versioned:
2.5.1+ builds emit **HST v3** (precompiled scripts). The runtime a project
ships is its own `src/js/lm.js`, so after upgrading the CLI run
**`lm update-core`** before building (§13). An older `lm.js` cannot read v3
output. Since 2.5.3 `lm build` stops with an error in that case; older
CLIs only printed a warning and produced a broken site.

---

## 6. Directives — reference

Unchanged from V1 unless noted. Two prefixes: `:` for data/structural
bindings, `@` for events.

### 6.1 `:for` — loops

```html
<li :for="items">The number is: {{number}}</li>
<div :for="3">Item {{index}}</div>
<li :for="cartItems as item">{{ item }}</li>
<li :for="myObject as key, value">{{ key }}: {{ value }}</li>
<li :for="newItems as item; myIndex">{{ myIndex + 1 }}. {{ item }}</li>
```

Modifiers: `:for-limit`, `:for-offset`, `:for-if` (per-item filter).

In V2, loops nest freely (an inner `:for` over `g.items` inside an outer
`:for="groups as g"`), and loop variables interpolate directly in any
attribute, including on the looping element itself
(`<li :for="items as it" data-id="{{it.id}}">`). V1's backtick form
(`` data-id="`{{it.id}}`" ``) is still accepted for migrated markup.

**Attribute order is priority.** When `:if` and `:for` sit on the same
element, whichever is written first applies first:
`<i :if="show" :for="nums as n">` hides or shows the whole loop, while
`<i :for="nums as n" :if="n > 1">` filters individual rows.

### 6.2 `:if` / `:else-if` / `:else`

Unchanged — Vue-identical chaining semantics, DOM-structural (materialized
only when true, not merely hidden).

### 6.3 Events — `@eventName="handler"`

Unchanged — handlers receive `(ev, el)`, `el` a jQuery-shim-wrapped element
(`el.css(...)`, `el.data(...)`, `el[0]` for the raw DOM node). Every V1
event name still works: click/tap family, swipe, mouse (hyphenated —
`@mouse-over`, not `@mouseover`), scroll, `drag`/`sort` (with the matching
bare attribute on the element), forms, file-drop, modal, Select2 (`@sl-
select`/`@sl-unselect`).

**Delegation note (fixed in V2, worth knowing if you're debugging an old
build)**: every `@event` binding is delegated from a stable ancestor, so a
handler on dynamically-inserted HTML fires without any manual re-scan step.
This includes elements created by your own script and Iconify icons
(fixed in 2.5.2).

A bare `stop` attribute on an element stops propagation for every handler
on it: `<button stop @click="save()">`.

### 6.4–6.10 Draggable/sortable, modals, forms, Select2, DOM utility
directives, nav active-state matching, misc attributes

All unchanged from V1. See the V1 reference for the full exhaustive table if
migrating existing markup — none of these directive names or semantics
changed in V2.

---

## 7. Global built-ins

| Name | What it is |
|---|---|
| `globals` | Persisted to `localStorage`, reactive automatically (§5). |
| `wait()` / `resume()` | Pause / resume rendering. Never touch the loader (§5.4b). |
| `_loader.show()` / `_loader.hide()` | The page loader, shown and hidden only by your code. |
| `lmCheckForUpdate()` | Built pages check for a newer deploy and offer "A new version is available — Reload". Configure with `Reactor({ updateCheck: false })` or `Reactor({ updateCheck: { interval, message, buttonText, url, onUpdate } })`. Off under `lm serve`. |
| `cookies` | `.setItem`/`.getItem`/`.removeItem`/`.hasItem`/`.keys()`. |
| `nodes` | URL path split on `/`. |
| `pushURL(path, data?)` | Programmatic SPA navigation. |
| `watch` | Global watcher object (§5.4). |
| `API.get/post/put/delete/patch(path, data, headers, api_index, opts)` | Built-in HTTP client, §10. |
| `LIVE` | Global WebSocket client (`_Live`), `._emit(event, payload, isBinary)` — real-time features. |
| `cl(...)` | `console.log` shorthand. |

---

## 8. Modals, § 9. Routing

Unchanged from V1 — `modal="path"` + `modal-class`/`modal-title`/`modal-
description`, `close-modal`, the `@modal-open`/`@modal-close`/`@modal-
beforeclose` events, `view.scope(function(view, props){...})` for
parent↔modal data. Routing is still the same three primitives: `<a href>`,
`pushURL()`, `<form>` — no route-config file, file-system nesting maps URL
segments to `.view` files directly.

---

## 10. HTTP / data fetching, and the vault (new in V2)

`config.json`'s `apis[]` array still works exactly as in V1:

```json
{
    "apis": [
        { "baseURL": "YOUR_API_URL", "headers": { "X-BEA-Application-ID": "...", "X-BEA-Authorization": "..." } }
    ]
}
```

```js
API.get("path", data, headers, api_index).then(...).catch(...);
```

**New in V2 — the vault**, for never having to put a raw secret in
`config.json` at all: `lm login` (delegates to `roxyon login`, one real
account login with OTP — never reimplemented per-project), then `lm api set
<name>` (interactive prompt for url + headers, stored server-side, never
written to any local file — only a non-sensitive reference is). `lm api
get/update/list/remove` manage existing entries. At `lm build`, every
vault-managed entry is resolved fresh and merged into the same `apis[]`
array `config.json`'s own entries already populate — the token-minting flow
below is completely unchanged either way.

Whatever ends up in `apis[]` (from `config.json` directly, the vault, or
both) is sent once, at build time, to a token-minting endpoint that returns
an encrypted token embedded in the production bundle — the raw credentials
never ship to a visitor's browser. At runtime, the page opens a WebSocket,
trades that token for a short-lived session key, and every `API.*` call is
tagged with that key instead of a real credential — the server resolves and
proxies the actual request. This is true for **any** backend you configure
this way, not just LumenJS's own — a Stripe key, a Firebase config, a custom
server's credentials all flow through the identical mechanism.

## 10b. The BaaS query DSL

Unchanged from V1 in its entirety — the class/object model, `where`
operators, `include` (forward and reverse), aggregates, `_then` chaining,
`on_duplicate` upserts, `/batch`, field type encoding, `/Schemas` for
reading/changing schema. See the V1 reference's §10b for the full,
exhaustive version; nothing here is V2-specific.

---

## 11. npm dependencies in your own code (new in V2)

`index.js` and any project script can use real npm imports:

```js
import { nanoid } from "nanoid";
var id = nanoid();   // still reactive automatically (§5)
```

`lm create` scaffolds an empty `package.json`; `npm install` your
dependency, then just `import` it. Resolved at build/serve time via a
synthetic shim that keeps your own top-level declarations reactive while
never leaking a dependency's internal variable names into the reactive
namespace. Zero cost if you don't use it — a project with no dependencies
builds exactly as before.

---

## 12. Selective plugin bundling (new in V2)

18 commonly-used jQuery plugins (Select2, Flickity, GSAP, jQuery UI,
bootstrap-colorpicker, bootstrap-datetimepicker, and others) — everything
V1's `bea.js` bundled — are available on demand. List only the specific
libraries you need as real `package.json` dependencies (the same names as
npm — `select2`, `flickity`, ...) and `lm build`/`lm serve` bundle real
jQuery plus exactly that subset, plus their real dependencies. A project
with none of these listed pays nothing extra — no jQuery, no plugins, the
default lightweight runtime only.

`[sl]`/`[color]`/`[time]`/`[date]`/`[datetime]` elements auto-initialize
their matching widget on mount (V1's `renderPlugins()` behavior, ported
faithfully) whenever the matching plugin is selected — guarded so a
project that hasn't selected one safely no-ops instead of throwing.

---

## 13. Versions and upgrading

- Current release: **`2.5.3`**. `@lmjs/cli` and `@lmjs/core` share a version
  number and are released together. Check what's live with
  `npm view @lmjs/cli version`.
- Every project ships **its own runtime**, `src/js/lm.js`, copied in at
  `lm create`. Upgrading the CLI does not upgrade it. After any CLI upgrade,
  run `lm update-core` in the project, then confirm `src/js/lm.js` contains
  `EXPECTED_HST_FORMAT_VERSION=3` before building.
- To build a project with a specific version without changing a global
  install: `npx -y -p @lmjs/cli@2.5.3 lm update-core`, then
  `npx -y -p @lmjs/cli@2.5.3 lm build --serverless`.
- Release history:
  - **2.4.1** — `tpl` only on `:for`, `comp` removed, per-mount sub-view
    state, bare `stop`, attribute order = priority, built-in update prompt.
  - **2.5.0** — smaller bundles and faster heavy views.
  - **2.5.1** — views precompiled at build, no parser in production.
  - **2.5.2** — `@`-events on Iconify icons and script-created elements.
  - **2.5.3** — `lm create` writes `AGENTS.md` + `CLAUDE.md` for AI coding agents (`lm update-core` adds them
    to existing projects); `lm build` stops on an older project runtime. Runtime unchanged.

---

## Full syntax-contrast table (Vue/React → LumenJS V2)

| Looks like… | In Vue/React | In LumenJS V2 |
|---|---|---|
| `:for="items as item"` | not valid Vue syntax | Loop directive; also accepts a bare integer to repeat N times |
| `:if`/`:else-if`/`:else` | reads as `v-if` minus the prefix | Same chaining semantics as Vue |
| `{{ expr }}` | text-only in Vue, always escaped | Works in text and directly inside quoted HTML attributes. A value that looks like HTML markup is rendered **as HTML** (as in V1), so escape untrusted strings yourself |
| `` `{{ expr }}` `` | not valid Vue/React | Safe interpolation form for attribute values whose expression contains its own quotes |
| `@click="handler"` | calls `handler($event)` | Calls `handler(ev, el)` — `el` is a jQuery-shim-wrapped element |
| `@mouseover` | native DOM event name | Spelled `@mouse-over` (hyphenated) |
| `v-model` | two-way field binding | Does not exist — whole-form `o-sub`/`b-sub` instead |
| any top-level `var`/`let`/`const` | reactive only via a framework hook | **Automatically reactive** — no `bind=`, no declaration step at all (§5) |
| `view="path"` | closest analogue: `<component :is>` | Renders another `.view` file inline, resolved against the filesystem; each instance gets its own isolated scope (§4) |
| `@init="fn"` | closest analogue: a prop passed at mount | One-way data into a specific subview instance, merged into its own scope before first render (§4) |
| `comp="name"` | N/A | **Removed in 2.4.1** — renders nothing and logs an error. Use `tpl=` on a `:for`, or `view=` |
| `{{ fn() }}` | re-evaluated on every render | Evaluated once per block render; not re-run when the data it reads changes (§5.4) |
| `tpl="name"` | N/A | Renders a file from `tpls/` — **must** be used with `:for` in V2 (V1 allowed it anywhere); shares the calling `:for` item's own scope, no isolated instance (§4b) |
| Component props object | `props` | Only exists for modals (`view.scope(...)`) — ordinary sub-views/components use implicit same-name variable binding |
| `watch: {...}` | per-component, additive | One global `watch` object; reassigning it wholesale overwrites previous watchers |
| Router with a route table | declarative config | No route table — URL segments map 1:1 to view files on disk |
| `onMounted`/`useEffect` | per-component lifecycle | `@after-render` (mount) / `@before-render`+`@after-render` (`:for`/`:if` only), §5.3 |
| `npm install` + `import` | standard | Works the same in `index.js`/project scripts (§11) — new in V2 |