aktion-runtime 0.5.2 → 0.5.4

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 (66) hide show
  1. package/README.md +773 -376
  2. package/dist/aktion.iife.js +798 -790
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +10238 -8024
  5. package/dist/aktion.js.map +1 -1
  6. package/dist/aktion.umd.cjs +798 -790
  7. package/dist/aktion.umd.cjs.map +1 -1
  8. package/dist/node/compile-BUw0GAvN.cjs +491 -0
  9. package/dist/node/compile-BUw0GAvN.cjs.map +1 -0
  10. package/dist/node/compile-DxttTzo8.js +492 -0
  11. package/dist/node/compile-DxttTzo8.js.map +1 -0
  12. package/dist/node/compiler.cjs +11 -0
  13. package/dist/node/compiler.cjs.map +1 -0
  14. package/dist/node/compiler.js +11 -0
  15. package/dist/node/compiler.js.map +1 -0
  16. package/dist/node/index-8OvnOYPI.js +14070 -0
  17. package/dist/node/index-8OvnOYPI.js.map +1 -0
  18. package/dist/node/index-DBgA3bHQ.cjs +14069 -0
  19. package/dist/node/index-DBgA3bHQ.cjs.map +1 -0
  20. package/dist/node/language.cjs +1244 -0
  21. package/dist/node/language.cjs.map +1 -0
  22. package/dist/node/language.js +1244 -0
  23. package/dist/node/language.js.map +1 -0
  24. package/dist/node/vite.cjs +65 -0
  25. package/dist/node/vite.cjs.map +1 -0
  26. package/dist/node/vite.js +65 -0
  27. package/dist/node/vite.js.map +1 -0
  28. package/dist/system_prompt.txt +595 -829
  29. package/dist/system_prompt_chat.txt +98 -263
  30. package/dist/types/aktion-modules.d.ts +22 -0
  31. package/dist/types/compiler/compile.d.ts +54 -0
  32. package/dist/types/compiler/emit.d.ts +15 -0
  33. package/dist/types/compiler/index.d.ts +14 -0
  34. package/dist/types/compiler/linker.d.ts +27 -0
  35. package/dist/types/compiler/runtime.d.ts +63 -0
  36. package/dist/types/compiler/sourcemap.d.ts +40 -0
  37. package/dist/types/element.d.ts +82 -26
  38. package/dist/types/index.d.ts +1 -0
  39. package/dist/types/language/grammar.d.ts +25 -9
  40. package/dist/types/language/index.d.ts +8 -6
  41. package/dist/types/language-api.d.ts +15 -0
  42. package/dist/types/library/components/content.d.ts +0 -1
  43. package/dist/types/library/components/escape-hatch.d.ts +3 -0
  44. package/dist/types/library/components/layout.d.ts +3 -0
  45. package/dist/types/library/components/wrappers.d.ts +12 -0
  46. package/dist/types/library/utils.d.ts +42 -0
  47. package/dist/types/parser/frontier.d.ts +3 -3
  48. package/dist/types/parser/lexer.d.ts +7 -17
  49. package/dist/types/parser/types.d.ts +276 -113
  50. package/dist/types/plugin/index.d.ts +10 -0
  51. package/dist/types/plugin/vite.d.ts +21 -0
  52. package/dist/types/prompt/generator.d.ts +0 -11
  53. package/dist/types/renderer/renderer.d.ts +53 -4
  54. package/dist/types/runtime/builtins.d.ts +10 -6
  55. package/dist/types/runtime/effects.d.ts +3 -28
  56. package/dist/types/runtime/evaluator.d.ts +333 -24
  57. package/dist/types/runtime/http.d.ts +35 -30
  58. package/dist/types/runtime/i18n.d.ts +23 -32
  59. package/dist/types/runtime/router.d.ts +5 -6
  60. package/dist/types/runtime/state.d.ts +77 -33
  61. package/dist/types/runtime/util.d.ts +88 -0
  62. package/dist/types/theme/styles.d.ts +1 -1
  63. package/dist/types/tooling/delta.d.ts +1 -1
  64. package/dist/types/tooling/inspector.d.ts +1 -1
  65. package/package.json +37 -6
  66. package/dist/types/language/builtins.d.ts +0 -33
package/README.md CHANGED
@@ -5,16 +5,16 @@
5
5
  [![PRs welcome](https://img.shields.io/badge/PRs-welcome-10b981.svg)](#contributing)
6
6
 
7
7
  A framework-agnostic web component that renders LLM-generated UI from
8
- **Aktion** — a compact, declarative language designed for chat
9
- assistants. Drop one `<script>` tag and one `<aktion-app>` tag into
10
- any HTML page and you have a streaming, interactive renderer for an LLM's
11
- response.
8
+ **Aktion** — a reactive language whose surface syntax is a strict subset of
9
+ JavaScript, designed for chat assistants. Drop one `<script>` tag and one
10
+ `<aktion-app>` tag into any HTML page and you have a streaming, interactive
11
+ renderer for an LLM's response.
12
12
 
13
13
  ```html
14
14
  <script type="module" src="https://asfand-dev.github.io/aktion/dist/aktion.js"></script>
15
15
  <aktion-app theme="light">
16
- _app_ = Card([
17
- CardHeader("Hello", subtitle: "Generative UI in plain HTML"),
16
+ aktion = Card([
17
+ CardHeader("Hello", { subtitle: "Generative UI in plain HTML" }),
18
18
  Markdown("This card was streamed in as **plain text**.")
19
19
  ])
20
20
  </aktion-app>
@@ -42,11 +42,11 @@ HTML, or no framework at all.
42
42
  - [Themes](#themes)
43
43
  - [Icons](#icons)
44
44
  - [Routing](#routing)
45
- - [JavaScript escape hatch](#javascript-escape-hatch)
46
- - [Built-in globals (`storage`, `console`)](#built-in-globals)
47
- - [Internationalization (`i18n`)](#internationalization)
45
+ - [Built-in globals (`$storage`, `$console`)](#built-in-globals)
46
+ - [Internationalization (`$i18n`)](#internationalization)
48
47
  - [System prompt generator](#system-prompt-generator)
49
48
  - [Tooling](#tooling)
49
+ - [Build-time compiler & multi-file modules](#build-time-compiler--multi-file-modules)
50
50
  - [Documentation site](#documentation-site)
51
51
  - [Live examples](#live-examples)
52
52
  - [Project layout](#project-layout)
@@ -62,61 +62,85 @@ HTML, or no framework at all.
62
62
  Everything you need at runtime ships in a single bundle:
63
63
 
64
64
  - **A streaming-first parser.** Line-oriented, error-tolerant. Each
65
- statement commits to the DOM as soon as it arrives. Single, double, and
66
- backtick-quoted strings (with `${expression}` interpolation). `js{ … }`
67
- opaque blocks and `{ … }` declaration bodies for `component` / `effect` /
68
- `action`.
69
- - **One reactive atom kind.** Declare any reactive state with `$name = value`
70
- and read or write it with `$name`. The runtime tracks dependencies
71
- automatically. Template literals, spread, bracket access, optional
72
- chaining, nullish coalescing, expression-form `if` / `match` / `for`,
73
- lambdas (`(p) => …`), `bind:prop: $atom` two-way binding, and **30+ pure
74
- `@`-functions** (`@Filter`, `@Sort`, `@Find`, `@GroupBy`, `@Format`,
75
- `@FormatDate`, `@Plural`, `@Case`, `@Range`, `@Pick`, …).
76
- - **One HTTP primitive.** `http({ url, method, headers, body, query, ... })`
77
- is the only network call. It returns a reactive resource bag exposing
65
+ statement commits to the DOM as soon as it arrives. The surface syntax
66
+ is a **strict subset of JavaScript** — `function` declarations,
67
+ `for...of`, `if/else`, `switch/case`, template literals with
68
+ `${expression}` interpolation, arrow functions, default parameters,
69
+ destructuring, spread, optional chaining (`a?.b`), nullish coalescing
70
+ (`a ?? b`), and object-literal named arguments. Every Aktion program
71
+ is valid JavaScript.
72
+ - **One reactive atom kind.** Declare any reactive state with
73
+ `$name = value` and read or write it with `$name`. The `$` prefix is
74
+ the only thing that makes a binding reactive — `let` / `const` /
75
+ `var` keywords are optional and have no effect on reactivity. The
76
+ runtime tracks dependencies automatically — and at **path
77
+ granularity**: reading `$user.name` subscribes to `user.name` alone,
78
+ so a write to `$user.role` never re-renders, recomputes, or re-fires
79
+ an effect that only read `name` (see *Fine-grained reactivity* below).
80
+ Automatic two-way binding
81
+ via direct state refs (and member chains rooted at one —
82
+ `value: $form.email`), and a **`$util` runtime namespace** of pure
83
+ helpers (`$util.filter`, `$util.sort`, `$util.find`, `$util.groupBy`,
84
+ `$util.format`, `$util.formatDate`, `$util.plural`, `$util.case`,
85
+ `$util.range`, `$util.pick`, …) callable from Aktion expressions and
86
+ ordinary JavaScript alike.
87
+ - **One component-call shape.** Every call follows the trailing-object
88
+ rule — `Component(positionalArg, { prop: value, … })`. At most one
89
+ positional argument; every other argument goes in a trailing
90
+ `{ }` object literal.
91
+ - **One HTTP primitive.** `$http({ url, method, headers, body, query, ... })`
92
+ is the only network call. Each call is self-contained (pass a full
93
+ absolute `url`; `GET` is the default; no host-wide defaults). It returns
94
+ a reactive resource bag exposing
78
95
  `data | error | status | loading | headers | lastUpdated`, plus the
79
- callables `refetch()` and `cancel()`. Re-runs automatically when any
80
- reactive input in the options object changes.
81
- - **`storage` and `console` globals.** Always in scope. `storage.set/get`
82
- (localStorage by default), `storage.session.*`, `storage.cookies.*` with
83
- named-arg options, and `console.log/error/warn/info/debug`. No `js{}`
84
- escape hatch needed.
96
+ callables `refetch()` and `cancel()`. Re-run a request via `refetch()`
97
+ or by wrapping it in an `$effect(..., [$dep])`.
98
+ - **`$storage` and `$console` globals.** Always in scope, no import,
99
+ lowercase. `$storage.set/get` (localStorage by default),
100
+ `$storage.session.*`, `$storage.cookies.*` with object-literal options,
101
+ and `console.log/error/warn/info/debug`.
85
102
  - **A React-like DOM reconciler.** Diffs each re-render against the live
86
103
  DOM. Text-input value, selection, IME state, scroll positions,
87
104
  `<details>.open`, and stateful primitives like `Tabs` are all preserved
88
105
  across renders. Components that need to hold UI state get a
89
106
  `helpers.useInstanceState(...)` slot keyed by their position in the tree.
90
- - **A rich component library** of **130+ components** spanning layout,
107
+ - **A rich component library** of **170+ components** spanning layout,
91
108
  forms, charts, data, feedback, navigation, patterns, app-shell composites,
92
109
  editors, advanced UI, and standard helpers. See [Component library](#component-library).
93
- - **Declarative side effects.** `effect [ ...deps ] { … }` for background
94
- work — anonymous blocks where the dependency list mixes state triggers
95
- (`$atom`), lifecycle triggers (`on:mount`, `on:unmount`, `on:every(N)`),
96
- and rate-limit modifiers (`debounce(N)`, `throttle(N)`). `effect { … }`
97
- with an empty list is equivalent to `effect [on:mount] { … }`. Declare
98
- an effect **at the top level** for program-wide work, or **inside a
99
- `component { … }` body** to scope it to a single instance — timers,
100
- watched atoms, and `cleanup(fn)` registrations tear down when the
101
- component leaves the tree. `action Name(args) { … }` declares
102
- click-driven mutations and may optionally `return` a value.
103
- - **A built-in router.** `pages = _router_({ "/path": Component(), "/users/:id": UserPage(id: params.id), default: NotFound() })` plus
104
- `NavLink(label, to)` and a reserved `_route_` handle that exposes
105
- `_route_.path`, `_route_.params`, `_route_.query`, `_route_.pattern`,
106
- and `_route_.navigate("/path")`. Hash-based, framework-agnostic,
107
- always wired up.
110
+ - **Declarative side effects.** `$effect(() => { body }, [...deps])` for
111
+ background work — anonymous blocks where the dependency list mixes
112
+ state triggers (`$atom`), lifecycle triggers (`"mount"`, `"unmount"`,
113
+ `"every(N)"`), and rate-limit modifiers (`"debounce(N)"`,
114
+ `"throttle(N)"`). `$effect(() => { … })` with no dependency array is
115
+ equivalent to `$effect(() => { … }, ["mount"])`. Declare an effect
116
+ **at the top level** for program-wide work, or **inside a component
117
+ function body** to scope it to a single instance — timers, watched
118
+ atoms, and `cleanup(fn)` registrations tear down when the component
119
+ leaves the tree. `function name(args) { … }` (camelCase) declares an
120
+ action — click-driven mutations that may optionally `return` a value.
121
+ - **Outbound events.** `$emit("name", { detail })` dispatches a
122
+ `CustomEvent` on the host element from inside any action / effect /
123
+ lambda body. The host listens with
124
+ `el.addEventListener("name", …)`.
125
+ - **A built-in router.**
126
+ `pages = $router({ "/path": Component(), "/users/:id": UserPage({ id: params.id }), default: NotFound() })`
127
+ plus `NavLink(label, { to })` and a reserved `route` handle that
128
+ exposes `route.path`, `route.params`, `route.query`, `route.pattern`,
129
+ and `route.navigate("/path")`. Hash-based, framework-agnostic, always
130
+ wired up.
108
131
  - **Seven built-in themes** (`light`, `dark`, `neon`, `pastel`, `glass`,
109
132
  `brutalist`, `skyline`) plus full custom-token support via CSS custom
110
133
  properties. **50+ design tokens** organised into `colors`, `radius`,
111
- `font`, `motion`, and `elevation` groups. Brand the UI from inside the
112
- script with `theme = Theme({...})`.
113
- - **`i18n` runtime.** `$i18n = i18n({ locale, messages, fallback })` plus
114
- a global `t("key", vars?)` builtin and a `Locale()` helper that feeds
115
- the active locale into `@Format` / `@FormatDate`.
134
+ `font`, `motion`, and `elevation` groups. Brand the UI from inside
135
+ the script with `theme = $theme({...})`.
136
+ - **`$i18n` factory.** `const { t, setCurrentLanguage, getCurrentLanguage } = $i18n({ defaultLanguage, currentLanguage, translations })` builds a translation bundle keyed by language, with `{name}` placeholder interpolation.
116
137
  - **Font Awesome 6.7.2** auto-loaded — every `icon` prop accepts a Free
117
- Font Awesome name (no `fa-` prefix). Use `Icon(name, variant?, size?)`
138
+ Font Awesome name (no `fa-` prefix). Use `Icon(name, { variant?, size? })`
118
139
  for standalone glyphs. Variant prefixes supported: `"regular:star"`,
119
140
  `"brands:github"`.
141
+ - **Markup escape hatches.** `HTMLTag(tag, { attributes?, children? })`
142
+ and `Styles(css)` are the last-resort raw-HTML / raw-CSS injectors
143
+ when no standard component captures the design.
120
144
  - **A system prompt generator.** Emits a clean, ordered prompt teaching
121
145
  the LLM exactly which components, builtins, and tools are available.
122
146
  Two flavours ship: `system_prompt.txt` (full — every feature) and
@@ -188,19 +212,19 @@ Three equivalent ways:
188
212
 
189
213
  ```html
190
214
  <!-- as an attribute -->
191
- <aktion-app response='_app_ = Card([CardHeader("Hi")])'></aktion-app>
215
+ <aktion-app response='aktion = Card([CardHeader("Hi")])'></aktion-app>
192
216
 
193
217
  <!-- as inner text (rendered on connect) -->
194
218
  <aktion-app>
195
- _app_ = Card([CardHeader("Hi")])
219
+ aktion = Card([CardHeader("Hi")])
196
220
  </aktion-app>
197
221
 
198
222
  <!-- as a property/method -->
199
223
  <script>
200
224
  const el = document.querySelector("aktion-app");
201
225
  el.setResponse(`
202
- _app_ = Stack([greeting])
203
- greeting = Card([CardHeader("Hello", subtitle: "Generative UI in plain HTML")])
226
+ aktion = Column([greeting])
227
+ greeting = Card([CardHeader("Hello", { subtitle: "Generative UI in plain HTML" })])
204
228
  `);
205
229
  </script>
206
230
  ```
@@ -242,24 +266,15 @@ const prompt = el.getSystemPrompt({
242
266
  mode: "full", // or "chat" for the compact read-only prompt
243
267
  preamble: "You are an analytics assistant.",
244
268
  additionalRules: ["Always end with a FollowUpBlock of 2 prompts."],
245
- tools: [{ name: "list_orders", description: "Return recent orders.", argsExample: { limit: 10 } }],
246
269
  });
247
270
  ```
248
271
 
249
- ### 6. (Optional) Provide tools
272
+ > Network calls are issued by the LLM-authored code itself via the
273
+ > `$http({ url, method, body, ... })` primitive. The host is not involved.
274
+ > Install `el.registerHttpInterceptors(...)` if you need to attach auth
275
+ > headers, retry on 401, or log every request.
250
276
 
251
- Register host-side async functions exposed to `js{}` bodies as
252
- `ctx.tools.<name>(args)`:
253
-
254
- ```js
255
- el.setTools({
256
- list_orders: async ({ limit }) => fetch(`/api/orders?limit=${limit}`).then(r => r.json()),
257
- update_order: async ({ id, status }) =>
258
- fetch(`/api/orders/${id}`, { method: "PATCH", body: JSON.stringify({ status }) }).then(r => r.json()),
259
- });
260
- ```
261
-
262
- ### 7. (Optional) Listen for assistant messages
277
+ ### 6. (Optional) Listen for assistant messages
263
278
 
264
279
  Wire LLM-driven follow-ups back into your chat loop:
265
280
 
@@ -284,9 +299,9 @@ All members live on the `<aktion-app>` element.
284
299
  | `response` | Aktion text | Sets the program declaratively. Re-renders whenever the attribute changes. |
285
300
  | `showerrors` | `true` / unset | If present and `true`, displays parse errors in the rendered UI. Defaults to off. |
286
301
 
287
- Routing and the JavaScript escape hatch (`js{ … }` inside `effect` /
288
- `action` bodies) are always available — no host attribute, no allow-list.
289
- To omit those surfaces from the *generated prompt*, build it via
302
+ Routing and JavaScript execution inside `effect` / action bodies are
303
+ always available — no host attribute, no allow-list. To omit those
304
+ surfaces from the *generated prompt*, build it via
290
305
  `getSystemPrompt({ mode: "chat" })`.
291
306
 
292
307
  ### Properties
@@ -306,129 +321,264 @@ To omit those surfaces from the *generated prompt*, build it via
306
321
  | `appendChunk(chunk)` | Append a streaming chunk and re-render. |
307
322
  | `clear()` | Reset state, queries, and the rendered output. |
308
323
  | `setTheme(name \| tokens)` | Apply a built-in theme by name or a partial token map. |
309
- | `setTools(tools)` | Register host async tools exposed to `js{}` blocks as `ctx.tools.<name>(args)`. Replaces previously-registered tools. |
310
324
  | `registerComponents(specs, root?)` | Extend the built-in library with your own components. |
311
- | `getSystemPrompt(options?)` | Build a system prompt that matches the current library and tools. Pass `{ mode: "chat" }` for the compact variant. |
325
+ | `getSystemPrompt(options?)` | Build a system prompt that matches the current library. Pass `{ mode: "chat" }` for the compact variant. |
312
326
  | `navigate(path)` | Programmatically navigate. Updates `window.location.hash`. |
313
- | `registerHttpInterceptors({ onRequest?, onResponse?, onError? })` | Install interceptors for the `http({...})` layer. `onResponse` receives a `retry()` one-shot for e.g. 401 refresh flows. |
327
+ | `registerHttpInterceptors({ onRequest?, onResponse?, onError? })` | Install interceptors for the `$http({...})` layer. `onResponse` receives a `retry()` one-shot for e.g. 401 refresh flows. |
314
328
  | `serializeState()` | Return every reactive atom as a plain JSON-friendly object (for SSR / resumption). |
315
329
  | `hydrateState(snapshot)` | Apply a snapshot to the live store and schedule a re-render. Atoms not in the snapshot are untouched. |
316
330
  | `loadSnapshot({ programText, state })` | Atomic program + state load. The next render plans the program with the hydrated state already in place. |
317
331
  | `applyDelta(ops)` | Apply a structured delta (`patch` / `replace` / `append` / `new` / `delete`). User `$state` is preserved across the diff. |
332
+ | `mountCompiled(compiled, state?)` | Mount a build-time-compiled program (from the [Vite/Rollup plugin](#build-time-compiler--multi-file-modules) or `compile()`), skipping the runtime parser. Optional `state` seeds reactive values (SSR / HMR). |
318
333
 
319
334
  ### Events
320
335
 
321
336
  | Event | Detail | When it fires |
322
337
  | -------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
323
- | `assistant-message` | `{ message: string }` | When an action or lambda emits `emit "assistant-message" { message: "..." }`. |
338
+ | `assistant-message` | `{ message: string }` | When an action or lambda calls `$emit("assistant-message", { message: "..." })`. |
324
339
  | `error` | `{ errors: ParseError[] }` | After each render whose source had parse errors. |
325
340
  | `route-change` | `{ path, previousPath, source }` | When the current hash path changes. `source` is `"init" \| "hashchange" \| "navigate" \| "external"`. |
326
- | `<custom-name>` | User-defined `{ ... }` | When script emits `emit "name" { ... }` inside an `action` / `effect` body. |
341
+ | `<custom-name>` | User-defined `{ ... }` | When script calls `$emit("name", { ... })` inside an action / effect body. |
327
342
 
328
343
  The `error` event always fires regardless of `showerrors`, so host apps
329
344
  can log or report errors even when the in-page banner is suppressed.
330
345
 
346
+ ### Runtime safety limits
347
+
348
+ Every program is evaluated under a per-render **runtime budget** that
349
+ bounds three independent dimensions so a partial / accidentally
350
+ recursive program (typed live in the playground, mid-stream LLM token,
351
+ …) can't freeze the browser:
352
+
353
+ | Dimension | Default | Triggers on |
354
+ | ------------------- | ------------ | -------------------------------------------------------- |
355
+ | `componentDepth` | 150 levels | `function Foo() { return Foo() }` and other recursive trees |
356
+ | `iterations` | 250 000 / render | unbounded `for`/`while` loops inside function bodies |
357
+ | `arrayLength` | 100 000 entries | `$util.range(0, 1e9)`, `$util.repeat(value, 1e9)` |
358
+
359
+ When a limit trips, the runtime aborts the render, emits an `error`
360
+ event whose detail is shaped like a parse error (`{ line: 0, column:
361
+ 0, message }`), and leaves the previous tick's DOM intact so the user
362
+ still sees something useful. The defaults comfortably fit any
363
+ realistic app; tighten or relax them by constructing a custom budget
364
+ via `createRuntimeBudget({ … })` and passing it through `createContext`
365
+ (or pass `null` to disable enforcement entirely in trusted offline
366
+ pipelines).
367
+
331
368
  ---
332
369
 
333
370
  ## Aktion — the language
334
371
 
335
- A program is a flat list of `name = expression` statements. The renderer
372
+ Aktion's surface syntax is a **strict subset of JavaScript**. Every
373
+ declaration uses standard JS constructs — `function`, `for...of`,
374
+ `if/else`, `switch/case`, arrow functions, object literals — so any
375
+ developer reading the output immediately knows what it does. The renderer
336
376
  commits each line as soon as it streams in, so the user sees the page
337
377
  shell before the leaves arrive.
338
378
 
339
- ```text
379
+ ```js
340
380
  $count = 0
341
381
  $theme = "dark"
342
382
 
343
- component Counter(label: "Count") {
383
+ function Counter(label = "Count") {
344
384
  return Stack([
345
385
  SectionHeader(label),
346
- Button("Inc", onClick: () => $count = $count + 1),
386
+ Button("Inc", { onClick: () => $count = $count + 1 }),
347
387
  Text(`Current: ${$count}`)
348
388
  ])
349
389
  }
350
390
 
351
- action loadOrders() {
352
- $orders = http({ url: "/api/orders", method: "GET" })
391
+ function loadOrders() {
392
+ $orders = $http({ url: "https://api.example.com/orders", method: "GET" })
353
393
  }
354
394
 
355
- effect [$draft, debounce(500)] {
356
- $save = http({ url: "/api/draft", method: "PUT", body: $draft })
357
- }
395
+ $effect(() => {
396
+ $save = $http({ url: "https://api.example.com/draft", method: "PUT", body: $draft })
397
+ }, [$draft, "debounce(500)"])
358
398
 
359
- $orders = http({
360
- url: "/api/users/42/orders",
399
+ $orders = $http({
400
+ url: "https://api.example.com/users/42/orders",
361
401
  method: "GET",
362
402
  query: { limit: 5 }
363
403
  })
364
404
 
365
- pages = _router_({
405
+ pages = $router({
366
406
  "/": Counter(),
367
- "/orders": Async($orders, loading: Spinner(), data: OrderTable($orders.data)),
407
+ "/orders": Async($orders, { loading: Spinner(), data: OrderTable($orders.data) }),
368
408
  default: NotFound()
369
409
  })
370
410
 
371
- _app_ = pages
411
+ aktion = pages
372
412
  ```
373
413
 
374
414
  ### Key constructs
375
415
 
376
- - `_app_ = …` — the reserved entry point. Every program starts with it.
416
+ - `aktion = …` — the reserved entry point. Every program renders from
417
+ it.
377
418
  - `$name = value` — reactive state. One kind. Read or write with the
378
- same sigil. Inside `action` / `effect` / lambda bodies, assignment
419
+ same sigil. Inside action / effect / lambda bodies, assignment
379
420
  operators (`= += -= *= /= ??= ++ --`) are all allowed.
380
- - `component Name(p: default) { return Expression }` — first-class
381
- declarations with default expressions, lexical scope, and per-instance
382
- state. Inside the body, `$x = expr` is a **declaration**: the
383
- initializer runs once when the instance first mounts, and re-renders
384
- preserve whatever value the user (or an action / effect) has written.
385
- **Always** end with an explicit `return`.
386
- - `action Name(args) { body }` — callable effects with optional
387
- `return`. Used as event handlers (`onClick: save`) or as expressions
388
- (`$result = greet("Ada")`).
389
- - `effect [ ...deps ] { body }` — declarative, anonymous side effects.
390
- The bracketed dependency list mixes state triggers (`$atom`),
391
- lifecycle / interval triggers (`on:mount`, `on:unmount`,
392
- `on:every(N)`), and rate-limit modifiers (`debounce(N)`,
393
- `throttle(N)`). `effect { ... }` (no brackets) is equivalent to
394
- `effect [on:mount] { ... }`. Declare at the program top level for
395
- global work, or inside a `component { … }` body to scope the effect
396
- to that instance — the runtime mounts it on first render and tears
397
- down its timers / subscriptions / `cleanup(fn)` handlers when the
398
- instance leaves the tree.
399
- - Expression-form control flow: `if cond { … } else { … }`,
400
- `match expr { "a": A() default: Else() }`, `for x in xs { Row(x) }`.
401
- Match and router arms use `:` and `default:` (not `->` / `_`).
402
- - `http({ url, method, headers, body, query, ... })` — the only network
403
- primitive. Returns a reactive resource with `.data`, `.error`,
421
+ `let/const/var` are optional and do not affect reactivity — only the
422
+ `$` prefix makes a value reactive.
423
+ - **Component-call shape** — every call follows the trailing-object
424
+ rule:
425
+
426
+ ```js
427
+ Component(positionalArg, { prop: value, … })
428
+ ```
429
+
430
+ Each component accepts **at most one positional argument** (typically
431
+ the title, children array, or primary value); every other argument
432
+ goes in a trailing `{ }` object literal. This is the *only* call
433
+ shape — `Button("Save", "primary", true)` is a schema error; write
434
+ `Button("Save", { variant: "primary", loading: true })` instead.
435
+ - `function Name(p = default) { return Expression }` — PascalCase name
436
+ means it's a component. Parameters use standard JS defaults (`=`).
437
+ Inside the body, `$x = expr` is a **declaration**: the initializer
438
+ runs once when the instance first mounts, and re-renders preserve
439
+ whatever value the user (or an action / effect) has written.
440
+ **Always** end with an explicit `return`. Components do not have a
441
+ `props` object — every parameter is a real JS parameter.
442
+ - `function name(args) { body }` — camelCase name means it's an action.
443
+ Callable effects with optional `return`. Used as event handlers
444
+ (`onClick: save`) or as expressions (`$result = greet("Ada")`).
445
+ - `$effect(() => { body }, [...deps])` — declarative, anonymous side
446
+ effects. The dependency array mixes state triggers (`$atom`),
447
+ lifecycle / interval triggers (`"mount"`, `"unmount"`, `"every(N)"`),
448
+ and rate-limit modifiers (`"debounce(N)"`, `"throttle(N)"`).
449
+ `$effect(() => { … })` (no second argument) is equivalent to
450
+ `$effect(() => { … }, ["mount"])`. Declare at the program top level
451
+ for global work, or inside a component function body to scope the
452
+ effect to that instance — the runtime mounts it on first render and
453
+ tears down its timers / subscriptions / `cleanup(fn)` handlers when
454
+ the instance leaves the tree.
455
+ - `$emit("name", { detail })` — dispatch an outbound `CustomEvent` on
456
+ the host element. Call from any action / effect / lambda body
457
+ whenever the surrounding host page needs to react to a user
458
+ interaction.
459
+ - Standard JS control flow — `if`, `switch`, `for`, `while`, `do…while`,
460
+ `try` are **statements**, exactly as in JavaScript. They run inside
461
+ any imperative body (`function`, lambda with `{ … }`, `effect`) but
462
+ cannot appear on the right-hand side of an assignment. Use ternaries
463
+ and `.map`/`.filter` for value-producing expressions. Bodies may be
464
+ either a block or a single statement (`if (!ok) return`):
465
+
466
+ ```js
467
+ banner = $error ? ErrorAlert($error) : Notice("All good")
468
+ rows = $items.map(item => Row(item))
469
+ // Multi-way dispatch: wrap a `switch` in a function and `return` per arm.
470
+ function viewFor(tab) {
471
+ switch (tab) {
472
+ case "list": return ListView($items)
473
+ case "grid": return GridView($items)
474
+ default: return EmptyState("Pick a view")
475
+ }
476
+ }
477
+ view = viewFor($tab)
478
+ ```
479
+ - Full operator set — arithmetic (`+`, `-`, `*`, `/`, `%`, `**`),
480
+ comparison (`==` / `!=` / `===` / `!==`, `<` / `>` / `<=` / `>=`),
481
+ logical (`&&`, `||`, `??`), bitwise / shift (`&`, `|`, `^`, `~`, `<<`,
482
+ `>>`, `>>>`), and the relational keywords `instanceof` / `in`. Every
483
+ compound-assignment form is supported too (`+=`, `-=`, `*=`, `/=`,
484
+ `%=`, `**=`, `&&=`, `||=`, `??=`, `&=`, `|=`, `^=`, `<<=`, `>>=`,
485
+ `>>>=`).
486
+ - Line continuations — any expression operator (`.`, `?.`, `?`, `:`,
487
+ `&&`, `||`, `??`, `==` / `!=` / `===` / `!==`, `<` / `>` / `<=` /
488
+ `>=`, `instanceof`, `+`, `-`, `*`, `/`, `%`, `**`) may appear at the
489
+ start of the next line and the parser keeps building the same
490
+ expression — matches JavaScript's ASI rules. Use this to split long
491
+ method chains, ternaries, and logical expressions across lines.
492
+ - `$http({ url, method, headers, body, query, ... })` — the only network
493
+ primitive (absolute `url`; `GET` default; no host-wide defaults).
494
+ Returns a reactive resource with `.data`, `.error`,
404
495
  `.status`, `.loading`, `.headers`, `.lastUpdated`, `.refetch()`,
405
- `.cancel()`.
406
- - `pages = _router_({ "/path": Component(), default: NotFound() })` —
407
- function-call router. The reserved `_route_` handle exposes the
408
- reactive surface and a `navigate("/path")` method; each arm body
409
- additionally receives a scoped `params` loop var with its captures.
410
- - `bind:value: $atom` — two-way binding sugar on inputs.
411
- - Lambdas `(args) => expr` and opaque `js{ … }` blocks placed inside
412
- `effect` / `action` bodies.
413
- - `emit "name" { detail }` — dispatch an outbound `CustomEvent` on the
414
- host element.
415
- - Comments: `// line`, `# line`, and `/* block */` — all stripped silently.
496
+ `.cancel()`, and a settable `.onDone` callback that fires each time the
497
+ request settles (handy for `$todos.refetch()` after a write).
498
+ - `pages = $router({ "/path": Component(), default: NotFound() })` —
499
+ function-call router. The reserved `route` handle exposes the
500
+ reactive surface (`route.path`, `route.params`, `route.query`,
501
+ `route.pattern`) and a `route.navigate("/path")` method; each arm
502
+ body additionally receives a scoped `params` loop var with its
503
+ captures.
504
+ - Two-way binding is implicit: pass a `$variable` (or a member chain
505
+ rooted at one — `value: $form.email`) as an input prop and the
506
+ runtime wires it both ways.
507
+ - Lambdas — every JavaScript arrow form is supported: `() => expr`,
508
+ `x => expr` (single param, no parens), `(x) => expr`, `(x, y) => expr`,
509
+ `(x = 0) => x + 1` (defaults), `(...args) => sum(args)` (rest),
510
+ `({ a, b }) => a + b` / `([x, y]) => x` (destructured params),
511
+ `(args) => { … }` (multi-statement, may `return`). The body can wrap
512
+ onto the next line (`x =>\n expr`).
513
+ - Destructured parameters — both `function` declarations and lambdas
514
+ accept array / object patterns (`function Card({ title, tone = "info" })`,
515
+ `function head([first, ...rest])`), with the same defaults / renames /
516
+ rest support as `let`-destructuring.
517
+ - JS expression niceties — array / object spread (`[...xs, y]`,
518
+ `{ ...base, k: v }`), array / object destructuring in `let` / `const`
519
+ / `var` (`let [a, b, ...rest] = arr`, `let { name, age = 0 } = user`),
520
+ computed property keys (`{ [$dynamic]: value }`), prefix and postfix
521
+ `++` / `--` (with JS-accurate return semantics), `new Constructor(...)`
522
+ with trailing member / call chains (`new Date(0).getTime()`), trailing
523
+ commas in function params / call args / literal lists. `async function`
524
+ is accepted as a no-op modifier; `await` is allowed in both statement
525
+ and expression position inside action / effect bodies.
526
+ - Top-level imperative statements — `if` / `for` / `while` / `try` and
527
+ bare expression statements written at the program top level run once
528
+ per plan (e.g. building a `$state` array with a `while` loop). Inside
529
+ a render they behave like a module init block; prefer pure expressions
530
+ (`.map`, `$util.range`) where you can.
531
+ - **`$util` runtime namespace** — pure, side-effect-free helpers for data
532
+ shaping, formatting, dates, math, and strings (`$util.filter`, `$util.sort`,
533
+ `$util.groupBy`, `$util.format`, `$util.formatDate`, `$util.plural`, `$util.range`,
534
+ `$util.addDays`, `$util.pick`, `$util.count`, …). Never carry hidden state —
535
+ safe to call anywhere.
536
+ - **Escape hatches** — `HTMLTag(tag, { attributes?, children? })` for
537
+ raw HTML elements and `Styles(css)` for raw CSS injected into the
538
+ shadow root. Use only when the standard component library cannot
539
+ express the design.
540
+ - **Hoisting & streaming** — references resolve from the entire
541
+ top-level scope, not source order. Always emit `aktion = …` first
542
+ so the reconciler has the page shell to attach streamed leaves to.
543
+ - Comments: `//` line comments and `/* block */` comments — standard
544
+ JS style.
545
+
546
+ #### Built-in globals at a glance
547
+
548
+ | Global | Purpose |
549
+ | --------- | -------------------------------------------------------------------- |
550
+ | `$storage` | Browser persistence — `$storage.set/get`, `$storage.session.*`, `$storage.cookies.*`. |
551
+ | `$console` | Forwards to the host console — `log` / `error` / `warn` / `info` / `debug`. |
552
+ | `route` | Reactive router handle — `path`, `params`, `query`, `pattern`, `navigate(path)`. |
553
+ | JS stdlib | The JS standard library — `Math`, `JSON`, `Object`, `Array`, `Number`, `String`, `Boolean`, `Date`, `Map`, `Set`, `RegExp`, `Promise`, plus `parseInt` / `parseFloat` / `isNaN` / `isFinite` / `encodeURIComponent` / … Use directly (`Math.max(a, b)`, `JSON.stringify(x)`, `Object.keys(o)`) or with `new` (`new Date()`, `new Map()`). |
554
+ | timers | `setTimeout` / `setInterval` / `clearTimeout` / `clearInterval` — like their JS counterparts, but tracked by the runtime and cleared automatically on re-plan/disconnect. Use inside an `effect` and clear in `cleanup`. |
555
+ | full JS globals | The **entire** JavaScript global surface is available — dialogs (`alert`, `confirm`, `prompt`), Web APIs (`fetch`, `URL`, `URLSearchParams`, `Blob`, `FormData`, `crypto`, `navigator`, `localStorage`, `atob`/`btoa`, `Intl`, `BigInt`, `Reflect`, …), and `window` / `document` themselves. Any `globalThis` member resolves by name. |
556
+
557
+ Both `$storage` and `$console` are **lowercase**; the `route` handle is
558
+ **reserved** (never declare a state slot named `route`). Author declarations
559
+ and built-in components always win over a same-named global (a library
560
+ `Text` / `Map` component is never shadowed by the DOM `Text` / `Map`), so the
561
+ global passthrough only resolves names you haven't otherwise defined. For
562
+ reactive data prefer `$http({...})` over raw `fetch`, and timers/listeners
563
+ belong inside an `$effect(...)` so they're cleaned up on unmount.
416
564
 
417
565
  ### The 60-second pitch
418
566
 
419
- ```text
567
+ ```js
420
568
  $days = "7"
421
- $data = http({ url: "/api/metrics", method: "GET", query: { days: $days } })
569
+ $data = $http({ url: "https://api.example.com/metrics", method: "GET", query: { days: $days } })
422
570
 
423
- filter = FormControl("Range", control: Select("days",
571
+ filter = FormControl("Range", { control: Select("days", {
424
572
  items: [SelectItem("7", "7d"), SelectItem("30", "30d")],
425
- value: $days))
426
- kpi = StatCard("Events", value: `${$data.data?.events ?? 0}`, trend: "up")
427
- chart = LineChart(
573
+ value: $days
574
+ }) })
575
+ kpi = StatCard("Events", { value: `${$data.data?.events ?? 0}`, trend: "up" })
576
+ chart = LineChart({
428
577
  labels: $data.data?.daily?.day ?? [],
429
- series: [Series("Events", $data.data?.daily?.events ?? [])])
578
+ series: [Series("Events", $data.data?.daily?.events ?? [])]
579
+ })
430
580
 
431
- _app_ = Stack([CardHeader("Analytics"), filter, kpi, chart])
581
+ aktion = Column([CardHeader("Analytics"), filter, kpi, chart])
432
582
  ```
433
583
 
434
584
  Highlights:
@@ -442,86 +592,239 @@ Highlights:
442
592
  - Array shortcuts: `$rows.length`, `$rows.first`, `$rows.last`,
443
593
  plus pluck (`$rows.title` → `[title1, title2, …]`).
444
594
  - Responsive prop maps on layout components:
445
- `Grid(items, columns: { sm: 1, md: 2, lg: 4 }, gap: "l")`.
446
- - Forward references are allowed — list `_app_ = Stack([...])` first
595
+ `Grid(items, { columns: { sm: 1, md: 2, lg: 4 }, gap: "l" })`.
596
+ - Forward references are allowed — list `aktion = Column([...])` first
447
597
  and let the children stream in beneath it.
448
598
 
449
- ### Declarative todo app (no JS required)
599
+ ### Declarative todo app
450
600
 
451
- ```text
601
+ ```js
452
602
  $todos = [{ id: 1, text: "Welcome — try editing", done: false }]
453
603
  $draft = ""
454
604
 
455
- action add() {
605
+ function add() {
456
606
  $todos = [...$todos, { id: $todos.length + 1, text: $draft, done: false }]
457
607
  $draft = ""
458
608
  }
459
609
 
460
- action remove(id) {
461
- $todos = @Filter($todos, "id", "!=", id)
610
+ function remove(id) {
611
+ $todos = $util.filter($todos, "id", "!=", id)
462
612
  }
463
613
 
464
- row = (t) => Card([Stack([
614
+ row = t => Card([Stack([
465
615
  Text(t.text),
466
- Button("Delete", onClick: () => remove(t.id), variant: "ghost")
616
+ Button("Delete", { onClick: () => remove(t.id), variant: "ghost" })
467
617
  ])])
468
618
 
469
- list = for t in $todos { row(t) }
470
- _app_ = Stack([
471
- Input("draft-input", placeholder: "What needs doing?", value: $draft),
472
- Button("Add", onClick: add, variant: "primary"),
619
+ list = $todos.map(t => row(t))
620
+ aktion = Stack([
621
+ Input("draft-input", { placeholder: "What needs doing?", value: $draft }),
622
+ Button("Add", { onClick: add, variant: "primary" }),
473
623
  list
474
624
  ])
475
625
  ```
476
626
 
627
+ ### Fine-grained reactivity
628
+
629
+ Dependencies are tracked at the **path** you read, not the whole atom.
630
+ Reading `$user.name` subscribes to `user.name` — so a write to a
631
+ **sibling** field leaves that reader untouched, while replacing the whole
632
+ atom (an ancestor) or writing a descendant still wakes it. This is the
633
+ auto-tracking of MobX, the path-granularity of Solid, and the
634
+ "recompute-only-on-input-change" of Redux selectors — with no selectors
635
+ or special syntax. You just read the path.
636
+
637
+ ```js
638
+ $user = { name: "Ada", role: "Engineer" }
639
+
640
+ // Reads `user.name` → depends on `user.name` only.
641
+ greeting = Text(`Hi ${$user.name}`)
642
+
643
+ // Writing the sibling `role` does NOT re-render `greeting`, recompute a
644
+ // `$user.name`-derived value, or fire a `[$user.name]` effect.
645
+ function promote() { $user.role = "Manager" } // greeting stays put
646
+ function rename(next) { $user.name = next } // greeting updates
647
+ ```
648
+
649
+ The rule that keeps it predictable:
650
+
651
+ | You read… | You depend on… |
652
+ | --- | --- |
653
+ | `$user` | `user` (the whole atom) |
654
+ | `$user.name` | `user.name` |
655
+ | `$user.address.city` | `user.address.city` |
656
+ | `$rows[i]` / `$rows.name` (array index / pluck) | `rows` (the array) |
657
+ | `$obj[$key]` (dynamic key) | `obj` + whatever `$key` reads |
658
+
659
+ A change to path **C** wakes a dependency on path **D** exactly when one
660
+ is a prefix of the other (equal, ancestor, or descendant) — sibling paths
661
+ never interfere. Object fields are tracked field-by-field; reading into an
662
+ array (or through a dynamic key) subscribes at the array/container, so
663
+ mutating any element re-renders the list. The same model powers the four
664
+ places work is triggered: **render scheduling** (the app re-renders only
665
+ when a changed path overlaps what it displayed), **computed values**
666
+ (`$total = $util.sum($cart.lines)` recomputes only when `cart.lines`
667
+ changes), **effects** (`$effect(..., [$user.name])`), and **per-component
668
+ re-rendering** (below).
669
+
670
+ #### Per-component re-rendering
671
+
672
+ A component only re-executes when **its own inputs change** — its args
673
+ (props) or a `$state` path its body read. This is the granularity of
674
+ `React.memo` / Solid, but automatic: no `memo()` wrapper. If `$user.age`
675
+ changes, a `ShowName($user.name)` that only read `name` is skipped (its
676
+ body — and any `console.log` in it — doesn't run); only the components that
677
+ actually depend on `age` re-execute.
678
+
679
+ ```js
680
+ function App() {
681
+ $user = { name: "Ada", age: 30 }
682
+ return [ShowName($user.name), ShowAge($user.age)] // siblings, independent
683
+ }
684
+ // Changing $user.age re-runs ShowAge only; ShowName is reused (memoized).
685
+ ```
686
+
687
+ Args are compared shallowly (`Object.is`), so — exactly as in React —
688
+ passing a **fresh inline lambda** each render (`onClick: () => …`) makes the
689
+ receiving component re-render every time; hoist the handler to a stable
690
+ binding if you want it skipped. State changes the path-tracker can't see
691
+ (hook setters, timers, HTTP, effects) fall back to a full re-render.
692
+
693
+ > Granularity is at both the *subscription* and *component* level. When a
694
+ > component does re-execute, Aktion rebuilds its render tree and the morph
695
+ > reconciler patches only the DOM that actually differs.
696
+
477
697
  ### Per-instance state & content-addressed identity
478
698
 
479
- ```text
480
- component Counter(label) {
699
+ ```js
700
+ function Counter(label) {
481
701
  $n = 0
482
702
  return Stack([
483
703
  Text(`${label}: ${$n}`),
484
- Button("inc", onClick: () => $n = $n + 1)
704
+ Button("inc", { onClick: () => $n = $n + 1 })
485
705
  ])
486
706
  }
487
707
 
488
- # Two independent counters — each holds its own atom.
489
- _app_ = Stack([Counter("A"), Counter("B")])
708
+ // Two independent counters — each holds its own atom.
709
+ aktion = Stack([Counter("A"), Counter("B")])
490
710
  ```
491
711
 
492
- Every call site accepts a universal `key:` named argument. The renderer
712
+ Every call site accepts a universal `key` named argument. The renderer
493
713
  uses it as the instance suffix instead of source location, so reordering
494
714
  siblings keeps per-instance state attached to the right element:
495
715
 
496
- ```text
497
- component TaskRow(task) {
498
- return Stack([Text(task.title)], key: task.id)
716
+ ```js
717
+ function TaskRow(task) {
718
+ return Stack([Text(task.title)], { key: task.id })
719
+ }
720
+ ```
721
+
722
+ ### Hooks — `$state`, `$memo`, and custom `$name`
723
+
724
+ A function whose name starts with `$` is a **hook**, mirroring React's
725
+ `use*` convention. Hooks are the composable way to manage per-instance
726
+ state. Built-in `$state` and `$memo` mirror React's `useState` and
727
+ `useMemo`:
728
+
729
+ ```js
730
+ function Counter() {
731
+ const [count, setCount] = $state(0)
732
+ const label = $memo(() => `Count: ${count}`, [count])
733
+ return Stack([
734
+ Text(label),
735
+ Button("+1", { onClick: () => setCount(c => c + 1) })
736
+ ])
737
+ }
738
+
739
+ aktion = Counter()
740
+ ```
741
+
742
+ - `$state(initial)` returns a `[value, setValue]` pair. `setValue(next)`
743
+ replaces the value; `setValue(prev => next)` derives it from the
744
+ previous value. The initializer is evaluated once, on first render.
745
+ - `$memo(() => compute, [deps])` returns a cached value and recomputes
746
+ only when a dependency changes (shallow `Object.is` compare). Omit the
747
+ deps array to recompute every render.
748
+
749
+ Declare your own hooks with `function $name(...)`. A custom hook's
750
+ body runs **inline in the calling component's hook scope**, so its
751
+ `$state` / `$memo` calls attach to that component — exactly how a React
752
+ custom hook shares its caller's slots:
753
+
754
+ ```js
755
+ function $useCounter(start) {
756
+ const [count, setCount] = $state(start)
757
+ return { count: count, increment: () => setCount(c => c + 1) }
758
+ }
759
+
760
+ function Counter(label) {
761
+ const c = $useCounter(0)
762
+ return Stack([Text(`${label}: ${c.count}`), Button("+1", { onClick: c.increment })])
499
763
  }
500
764
  ```
501
765
 
766
+ Two rules, both inherited from React: call hooks **unconditionally and in
767
+ a stable order** at the top level of a component / hook body (slots are
768
+ matched by call order across renders), and remember that hook state
769
+ **resets when the instance leaves the tree** — a remounted component
770
+ starts again from its initial value. `$state` and `$memo` are reserved
771
+ names. The lighter `$name = value` per-instance form above remains
772
+ available when an atom is written directly by the component's actions.
773
+
774
+ ### Global stores — `$store({...})`
775
+
776
+ For state shared across components — the role Redux / Zustand / Pinia play
777
+ elsewhere — declare a **store**. Non-function entries are reactive state;
778
+ function entries are methods that receive the store handle `s` first. Read
779
+ state with `store.field` (fine-grained), call methods with
780
+ `store.method(args)`, and mutate inside a method with `s.field = …`. The
781
+ handle is an app-global singleton with reference-stable methods, so any
782
+ component reads it or calls its actions directly — no prop drilling.
783
+
784
+ ```js
785
+ cart = $store({
786
+ items: [], // state
787
+ count: (s) => s.items.length, // getter → cart.count()
788
+ total: (s) => $util.sum(s.items.map(i => i.price)), // getter → cart.total()
789
+ add: (s, item) => { s.items = [...s.items, item] }, // action → cart.add(item)
790
+ clear: (s) => { s.items = [] },
791
+ })
792
+
793
+ // Siblings with no relationship both talk to the same cart.
794
+ function AddLatte() { return Button("Add", { onClick: () => cart.add({ price: 4.5 }) }) }
795
+ function MiniCart() { return Text(`${cart.count()} items — ${$util.format(cart.total(), "currency")}`) }
796
+ aktion = Column([AddLatte(), MiniCart()])
797
+ ```
798
+
799
+ Reads are fine-grained and per-component (changing `cart.items` re-renders
800
+ only components that read it), and store fields support two-way binding
801
+ (`Input(value: form.draft)`). Use a `$store` for shared state; use a
802
+ component's local `$state` / `$name = value` for state one component owns.
803
+ See the [Global state guide](https://asfand-dev.github.io/aktion/stores.html).
804
+
502
805
  ### Component-scoped effects
503
806
 
504
- `effect [ ...deps ] { … }` blocks can live at the program top level
505
- **or** inside a `component { … }` body. Inside a component body the
807
+ `$effect(() => { … }, [...deps])` blocks can live at the program top level
808
+ **or** inside a component function body. Inside a component body the
506
809
  runtime mounts the effect when the instance first renders and tears it
507
810
  down (clearing timers, unsubscribing watched atoms, firing every
508
811
  registered `cleanup(fn)`) the moment the instance disappears from the
509
812
  tree. Two `LiveClock()` calls produce two independent intervals — and
510
813
  removing one stops only that one:
511
814
 
512
- ```text
513
- _app_ = Stack([LiveClock("UTC"), LiveClock("Local")])
514
-
515
- component LiveClock(label) {
516
- $now = @Now()
517
- effect [on:every(1000)] {
518
- $now = @Now()
519
- }
520
- return Stack([Text(label), Text(@FormatDate($now, "time"))])
815
+ ```js
816
+ aktion = Stack([LiveClock("UTC"), LiveClock("Local")])
817
+
818
+ function LiveClock(label) {
819
+ $now = $util.now()
820
+ $effect(() => {
821
+ $now = $util.now()
822
+ }, ["every(1000)"])
823
+ return Stack([Text(label), Text($util.formatDate($now, "time"))])
521
824
  }
522
825
  ```
523
826
 
524
- Use a top-level `effect [...] { … }` for global work (analytics,
827
+ Use a top-level `$effect(() => { … }, [...])` for global work (analytics,
525
828
  app-wide keyboard shortcuts, hydration of shared atoms); use a
526
829
  component-local effect whenever the background work logically belongs
527
830
  to the UI it serves.
@@ -532,10 +835,10 @@ to the UI it serves.
532
835
  [`src/library/index.js`](./src/library/index.ts)) emits **hard errors**
533
836
  for:
534
837
 
535
- - Closed-token enum mismatches (`Button("Save", variant: "magic")`).
536
- - Unknown named args (`Stack(junk: 1)`).
838
+ - Closed-token enum mismatches (`Button("Save", { variant: "magic" })`).
839
+ - Unknown named args (`Stack({ junk: 1 })`).
537
840
  - One-positional-max violations (`Button("Save", "primary", true)` →
538
- "use `variant: "primary"`, `loading: true`").
841
+ "use `{ variant: "primary", loading: true }`").
539
842
 
540
843
  The host element merges these into `program.errors` so the on-screen
541
844
  banner surfaces every violation.
@@ -555,7 +858,7 @@ deep authoring guide [`coding-gen-skill.md`](./coding-gen-skill.md).
555
858
 
556
859
  ## Component library
557
860
 
558
- The bundle ships **130+ components** grouped by domain. Reach for **pattern composites**
861
+ The bundle ships **170+ components** grouped by domain. Reach for **pattern composites**
559
862
  (`Hero`, `PageHeader`, `Stats`, `Toolbar`, `EmptyState`, `Timeline`,
560
863
  `KanbanBoard`, `DescriptionList`, `PricingTable`, …) before hand-rolling
561
864
  the equivalent with `Card` + `Stack` — they're tuned to produce dense,
@@ -563,8 +866,8 @@ production-quality SaaS UI in a single line.
563
866
 
564
867
  | Group | Components |
565
868
  | ------------------ | ---------- |
566
- | **Layout** | `Stack`, `StackItem`, `Grid`, `GridItem`, `Container`, `Box`, `Spacer`, `Card`, `CardHeader`, `CardFooter`, `Separator`, `Tabs`, `TabItem`, `Accordion`, `AccordionItem`, `Modal`, `Drawer`, `Steps`, `AspectRatio`, `ScrollArea`, `Sticky`, `ResizablePanels`, `MasonryGrid` |
567
- | **Content** | `Text`, `Image`, `Icon`, `Link`, `Badge`, `BadgeList`, `Callout`, `Quote`, `CodeBlock`, `Skeleton`, `Spinner`, `Markdown`, `Kbd` |
869
+ | **Layout** | `Column`, `Row`, `Center`, `Stack`, `StackItem`, `Grid`, `GridItem`, `Container`, `Box`, `Spacer`, `Card`, `CardHeader`, `CardFooter`, `Separator`, `Tabs`, `TabItem`, `Accordion`, `AccordionItem`, `Modal`, `Drawer`, `Steps`, `AspectRatio`, `ScrollArea`, `Sticky`, `ResizablePanels`, `MasonryGrid` |
870
+ | **Content** | `Text`, `Image`, `Icon`, `Badge`, `BadgeList`, `Callout`, `Quote`, `CodeBlock`, `Skeleton`, `Spinner`, `Markdown`, `Kbd` |
568
871
  | **Forms** | `Form`, `FormControl`, `FormSection`, `FieldSet`, `ValidationSummary`, `Input`, `TextArea`, `PasswordInput`, `MaskedInput`, `MentionInput`, `TagInput`, `Select`, `SelectItem`, `Combobox`, `MultiSelect`, `Checkbox`, `CheckBoxGroup`, `CheckBoxItem`, `Radio`, `Switch`, `ToggleGroup`, `Button`, `Buttons`, `SearchBar`, `Slider`, `NumberInput`, `ColorPicker`, `DatePicker`, `DateRangePicker`, `TimePicker`, `DateTimePicker`, `FileUpload`, `PinInput`, `MultiStepForm` |
569
872
  | **Data** | `Table`, `Col`, `DataGrid`, `List`, `ListItem`, `StatCard`, `Stats`, `Sparkline`, `Tile`, `Progress`, `ProgressRing`, `Pagination`, `Tree`, `TreeNode`, `CalendarView`, `ComparisonTable`, `InfiniteList` |
570
873
  | **Charts** | `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `ScatterChart`, `Histogram`, `Heatmap`, `Gauge`, `Series` |
@@ -574,11 +877,56 @@ production-quality SaaS UI in a single line.
574
877
  | **Editors** | `RichTextEditor`, `CodeEditor` |
575
878
  | **Chat** | `SectionBlock`, `ListBlock`, `FollowUpBlock`, `FollowUpItem`, `ActionLink`, `ChatBubble` |
576
879
  | **Patterns** | `Hero`, `PageHeader`, `SectionHeader`, `Toolbar`, `EmptyState`, `Timeline`, `TimelineItem`, `ActivityLog`, `FeatureGrid`, `FeatureItem`, `MediaCard`, `Testimonial`, `ProfileCard`, `Comment`, `Banner`, `Notification`, `InboxPanel`, `OnboardingChecklist`, `KanbanBoard`, `KanbanColumn`, `KanbanCard`, `DescriptionList`, `DescriptionItem`, `StatusDot`, `PricingTable`, `PricingCard`, `LoadingState`, `ErrorState`, `SuccessState`, `Tour`, `Spotlight` |
577
- | **App shell** | `AppShell`, `Sidebar`, `SidebarSection`, `SidebarItem`, `SplitView` |
880
+ | **App shell** | `AppShell`, `Sidebar`, `SidebarSection`, `SidebarItem` (supports `to` for router navigation), `SplitView` |
578
881
  | **Advanced UI** | `IconButton`, `CommandPalette`, `FilterChips`, `FieldRepeater`, `VirtualList`, `QueryBuilder`, `DiffViewer`, `JsonTree`, `Gantt`, `Truncate`, `InlineEdit`, `NotificationBell` |
579
882
  | **Helpers** | `Async`, `Show`, `Portal`, `Redirect`, `Lazy`, `ErrorBoundary` |
580
- | **Theming** | `Theme` |
581
- | **Routing** | `_router_({ … })`, `NavLink` |
883
+ | **Behaviour wrappers** | `OnClick`, `OnMouse`, `OnKeyboard`, `OnFocus`, `OnIntersect`, `Css`, `Link` — attach click / mouse / keyboard / focus / intersection listeners or raw class / style to ANY component without it needing a dedicated prop. `Link(label_or_child, { to?, href?, external? })` wraps either a string or a component as a router-aware anchor. |
884
+ | **Escape hatches** | `HTMLTag`, `Styles` (last-resort raw HTML / CSS — see [language.html](https://asfand-dev.github.io/aktion/language.html#escape-hatches)) |
885
+ | **Theming** | `$theme` |
886
+ | **Routing** | `$router({ … })`, `NavLink` |
887
+
888
+ ### Form `onChange` callback
889
+
890
+ Every input component accepts an optional `onChange(value)` callable
891
+ that fires with the freshly-read value on every change. Use it alongside
892
+ (or instead of) `$variable` two-way binding when you need to react
893
+ beyond a state write (debounce a search, persist a setting, kick off
894
+ a fetch).
895
+
896
+ ```js
897
+ Input("query", { onChange: q => $results = $http({ url: `https://api.example.com/search?q=${q}` }) })
898
+ Slider("vol", { min: 0, max: 100, value: $vol, onChange: v => $storage.set("volume", v) })
899
+ Switch("dark", { value: $theme == "dark", onChange: on => $theme = on ? "dark" : "light" })
900
+ ```
901
+
902
+ ### Behaviour wrappers
903
+
904
+ Six tiny wrappers attach behaviour to any component:
905
+
906
+ ```js
907
+ // Clickable / tappable card
908
+ OnClick(Card([Text("View order")]), { onClick: () => route.navigate("/orders/4821") })
909
+
910
+ // Lazy-load sentinel — fires once when the placeholder scrolls into view
911
+ OnIntersect(Skeleton({ variant: "card" }), { onEnter: $items.refetch, once: true })
912
+
913
+ // Drop zone — uses standard HTML5 drag-and-drop
914
+ OnMouse(Card([Text("Drop files here")]), {
915
+ dragOver: e => e.preventDefault(),
916
+ drop: e => { e.preventDefault(); $files = e.dataTransfer.files }
917
+ })
918
+
919
+ // Apply a custom class / style without breaking out of the component
920
+ Css(Card([Text("Highlighted")]), { class: "highlight", style: "border-color: #f59e0b;" })
921
+ ```
922
+
923
+ `OnClick` / `OnMouse` / `OnKeyboard` / `OnFocus` render the child via a
924
+ transparent wrapper (`display: contents`) so the visual tree is
925
+ unchanged — only events bubble through the wrapper. `OnIntersect` uses
926
+ `IntersectionObserver` and disposes cleanly when the component leaves
927
+ the tree. `Css` merges classes / inline styles directly onto the
928
+ rendered child element. `Link` is the same wrapper applied as an
929
+ `<a>` anchor with optional router-aware navigation (`to`).
582
930
 
583
931
  The full catalog with positional signatures, prop tables, enum values, and
584
932
  live previews is at
@@ -586,27 +934,27 @@ live previews is at
586
934
 
587
935
  ### Rich pattern composites
588
936
 
589
- ```text
590
- action export_q3() { $exp = http({ url: "/exports/q3", method: "POST" }) }
591
- action new_project() { _route_.navigate("/projects/new") }
937
+ ```js
938
+ function export_q3() { $exp = $http({ url: "https://api.example.com/exports/q3", method: "POST" }) }
939
+ function new_project() { route.navigate("/projects/new") }
592
940
 
593
- dashHeader = PageHeader("Engineering Q3", subtitle: "12 active · 4 at risk", breadcrumbs: ["Workspace", "Engineering"], actions: dashActions, status: Badge("On track", "success"))
594
- dashActions = [Button("Export", onClick: export_q3, variant: "secondary"), Button("New project", onClick: new_project, variant: "primary")]
941
+ dashHeader = PageHeader("Engineering Q3", { subtitle: "12 active · 4 at risk", breadcrumbs: ["Workspace", "Engineering"], actions: dashActions, status: Badge("On track", "success") })
942
+ dashActions = [Button("Export", { onClick: export_q3, variant: "secondary" }), Button("New project", { onClick: new_project, variant: "primary" })]
595
943
  kpis = Stats([
596
- StatCard("Active", value: "12", trend: "flat"),
597
- StatCard("At risk", value: "4", trend: "up", delta: "+2"),
598
- StatCard("Shipped", value: "8", trend: "up", delta: "+3"),
599
- StatCard("On-time", value: "87%", trend: "down", delta: "-3%")
944
+ StatCard("Active", { value: "12", trend: "flat" }),
945
+ StatCard("At risk", { value: "4", trend: "up", delta: "+2" }),
946
+ StatCard("Shipped", { value: "8", trend: "up", delta: "+3" }),
947
+ StatCard("On-time", { value: "87%", trend: "down", delta: "-3%" })
600
948
  ])
601
949
  board = KanbanBoard([
602
- KanbanColumn("To do", items: [KanbanCard("Migrate auth", description: "Roll out new SDK.", tags: ["auth"], assignee: "Asha")]),
603
- KanbanColumn("Doing", items: [KanbanCard("Streaming UI v2", description: "20 new components.", tags: ["frontend"], assignee: "Alex", tone: "primary")]),
604
- KanbanColumn("Review", items: [KanbanCard("Mobile onboarding", description: "Awaiting design.", tags: ["mobile"], assignee: "Wren", tone: "warning")]),
605
- KanbanColumn("Done", items: [KanbanCard("Activity timeline", description: "Shipped to 100%.", tags: ["shipped"], assignee: "Mira", tone: "success")])
950
+ KanbanColumn("To do", { items: [KanbanCard("Migrate auth", { description: "Roll out new SDK.", tags: ["auth"], assignee: "Asha" })] }),
951
+ KanbanColumn("Doing", { items: [KanbanCard("Streaming UI v2", { description: "20 new components.", tags: ["frontend"], assignee: "Alex", tone: "primary" })] }),
952
+ KanbanColumn("Review", { items: [KanbanCard("Mobile onboarding", { description: "Awaiting design.", tags: ["mobile"], assignee: "Wren", tone: "warning" })] }),
953
+ KanbanColumn("Done", { items: [KanbanCard("Activity timeline", { description: "Shipped to 100%.", tags: ["shipped"], assignee: "Mira", tone: "success" })] })
606
954
  ])
607
955
  follow = FollowUpBlock(["Show at-risk projects", "Compare to Q2", "Who needs help?"])
608
956
 
609
- _app_ = Stack([dashHeader, kpis, board, follow])
957
+ aktion = Column([dashHeader, kpis, board, follow])
610
958
  ```
611
959
 
612
960
  ### Adding your own components
@@ -676,14 +1024,14 @@ el.setTheme({
676
1024
  });
677
1025
  ```
678
1026
 
679
- ### `Theme({...})` from inside a response
1027
+ ### `$theme({...})` from inside a response
680
1028
 
681
- A response can brand itself by assigning a `Theme({...})` call to the
682
- reserved `theme` binding. The tokens land on the host as CSS variables on
683
- top of the base theme.
1029
+ A response can brand itself by assigning a `$theme({...})` call to the
1030
+ reserved top-level `theme` binding. The tokens land on the host as CSS
1031
+ variables on top of the base theme.
684
1032
 
685
- ```text
686
- theme = Theme({
1033
+ ```js
1034
+ theme = $theme({
687
1035
  colors: {
688
1036
  primary: "#0969da",
689
1037
  border: "#d0d7de",
@@ -697,12 +1045,12 @@ theme = Theme({
697
1045
  radius: { button: "6px", input: "6px" }
698
1046
  })
699
1047
 
700
- _app_ = Stack([CardHeader("GitHub-style page"), Buttons([Button("New repository")])])
1048
+ aktion = Column([CardHeader("GitHub-style page"), Buttons([Button("New repository")])])
701
1049
  ```
702
1050
 
703
- `Theme` expects the **structured** form — top-level groups `colors` /
1051
+ `$theme` expects the **structured** form — top-level groups `colors` /
704
1052
  `radius` / `font` / `motion` / `elevation` (plus metadata keys `name`
705
- and `direction`). Removing the `Theme(...)` line snaps the UI back to
1053
+ and `direction`). Removing the `$theme(...)` line snaps the UI back to
706
1054
  the base theme. Unknown keys are ignored silently, so typos in an
707
1055
  LLM-emitted token map can never break the page.
708
1056
 
@@ -737,8 +1085,8 @@ shadow root. Host apps do **not** need to add a stylesheet.
737
1085
  `"circle-check"`, `"triangle-exclamation"`, `"sack-dollar"`.
738
1086
  - Optional variant prefix: `"regular:star"`, `"brands:github"`. The
739
1087
  default variant is `solid`.
740
- - Use the dedicated `Icon(name, variant?, size?)` component to render a
741
- standalone glyph (`size` ∈ `xs`, `sm`, `md`, `lg`, `xl`).
1088
+ - Use the dedicated `Icon(name, { variant?, size? })` component to render
1089
+ a standalone glyph (`size` ∈ `xs`, `sm`, `md`, `lg`, `xl`).
742
1090
  - Every component prop named `icon` — `NavLink`, `SidebarItem`, `Banner`,
743
1091
  `Notification`, `FeatureItem`, `Badge`, `StatCard`, `ListItem`,
744
1092
  `TimelineItem`, `DescriptionItem`, `Tile`, `EmptyState`, … — expects a
@@ -747,16 +1095,16 @@ shadow root. Host apps do **not** need to add a stylesheet.
747
1095
  stripped silently so legacy emoji leftovers still resolve to the
748
1096
  proper icon.
749
1097
 
750
- ```text
751
- brandIcon = Icon("rocket", "solid", "lg")
1098
+ ```js
1099
+ brandIcon = Icon("rocket", { variant: "solid", size: "lg" })
752
1100
  homeIcon = Icon("house")
753
- profileTab = NavLink("Profile", to: "/profile", variant: "ghost", icon: "user")
1101
+ profileTab = NavLink("Profile", { to: "/profile", variant: "ghost", icon: "user" })
754
1102
  kpis = Stats([
755
- StatCard("Revenue", value: "$48k", trend: "up", delta: "+12%", icon: "sack-dollar"),
756
- StatCard("Orders", value: "1,284", trend: "up", delta: "+8%", icon: "cart-shopping"),
757
- StatCard("Refunds", value: "12", trend: "down", delta: "-3", icon: "rotate-left")
1103
+ StatCard("Revenue", { value: "$48k", trend: "up", delta: "+12%", icon: "sack-dollar" }),
1104
+ StatCard("Orders", { value: "1,284", trend: "up", delta: "+8%", icon: "cart-shopping" }),
1105
+ StatCard("Refunds", { value: "12", trend: "down", delta: "-3", icon: "rotate-left" })
758
1106
  ])
759
- _app_ = Stack([brandIcon, kpis, profileTab])
1107
+ aktion = Stack([brandIcon, kpis, profileTab])
760
1108
  ```
761
1109
 
762
1110
  ---
@@ -768,39 +1116,39 @@ stay in sync with the URL (`#/dashboard`, `#/users/42`). Browser
768
1116
  back/forward, bookmarks, and deep links all work — and the host page
769
1117
  never reloads.
770
1118
 
771
- ```text
772
- pages = _router_({
1119
+ ```js
1120
+ pages = $router({
773
1121
  "/": homePage,
774
1122
  "/dashboard": dashboardPage,
775
- "/users/:id": userPage(id: params.id),
1123
+ "/users/:id": userPage({ id: params.id }),
776
1124
  default: notFoundPage
777
1125
  })
778
1126
 
779
- nav = Stack([
780
- NavLink("Home", to: "/", exact: true),
781
- NavLink("Dashboard", to: "/dashboard"),
782
- NavLink("Users", to: "/users")
783
- ], direction: "row", gap: "s")
1127
+ nav = Row([
1128
+ NavLink("Home", { to: "/", exact: true }),
1129
+ NavLink("Dashboard", { to: "/dashboard" }),
1130
+ NavLink("Users", { to: "/users" })
1131
+ ], { gap: "s" })
784
1132
 
785
- _app_ = Stack([nav, pages])
1133
+ aktion = Stack([nav, pages])
786
1134
 
787
1135
  homePage = Card([CardHeader("Welcome")])
788
1136
  dashboardPage = Card([CardHeader("Dashboard")])
789
1137
  userPage = (id) => Card([CardHeader(`User ${id}`)])
790
- notFoundPage = Callout("Not found", description: `We couldn't find ${_route_.path}.`, variant: "warning")
1138
+ notFoundPage = Callout("Not found", { description: `We couldn't find ${route.path}.`, variant: "warning" })
791
1139
  ```
792
1140
 
793
- - `pages = _router_({ "/path": Component(), default: Fallback() })` picks
1141
+ - `pages = $router({ "/path": Component(), default: Fallback() })` picks
794
1142
  the matching arm based on the current hash path. First match wins;
795
1143
  `default:` is the fallback.
796
1144
  - Route patterns support literal segments (`"/about"`), parameter
797
1145
  segments (`"/users/:id"` → `params.id`), and trailing wildcards
798
1146
  (`"/docs/*"` → `params._`).
799
- - `NavLink(label, to:, variant?, exact?, icon?)` is a router-aware anchor
800
- that intercepts clicks and reflects `data-active="true"` for the
1147
+ - `NavLink(label, { to, variant?, exact?, icon? })` is a router-aware
1148
+ anchor that intercepts clicks and reflects `data-active="true"` for the
801
1149
  current path.
802
- - The reactive `_route_` handle exposes `_route_.path`, `_route_.params`,
803
- `_route_.query`, and `_route_.pattern`. Call `_route_.navigate("/path")`
1150
+ - The reactive `route` handle exposes `route.path`, `route.params`,
1151
+ `route.query`, and `route.pattern`. Call `route.navigate("/path")`
804
1152
  from inside the script, or `el.navigate("/path")` from the host.
805
1153
 
806
1154
  The default ("full") system prompt teaches the LLM about routing. The
@@ -810,88 +1158,27 @@ for the full walkthrough.
810
1158
 
811
1159
  ---
812
1160
 
813
- ## JavaScript escape hatch
814
-
815
- `js{ … }` blocks live inside `effect` or `action` bodies — no host
816
- attribute, no allow-list. Reach for them only when no declarative path
817
- captures the behaviour (timers, clipboard, audio, complex computations,
818
- host-tool calls).
819
-
820
- ```text
821
- $todos = []
822
-
823
- action toggle(id) {
824
- js {
825
- const todos = ctx.state.get("todos") || []
826
- ctx.state.set("todos", todos.map(t => t.id === ctx.args.id ? { ...t, done: !t.done } : t))
827
- }
828
- }
829
-
830
- row = (t) => Card([Stack([
831
- Text(t.text),
832
- Button("Toggle", onClick: () => toggle(t.id))
833
- ])])
834
-
835
- list = for t in $todos { row(t) }
836
- _app_ = Stack([list])
837
- ```
838
-
839
- Inside the `js{ … }` block:
840
-
841
- - `ctx.state.get(name)` / `ctx.state.set(name, value)` read and write
842
- reactive atoms.
843
- - `ctx.args` exposes the action's positional parameters keyed by name.
844
- - `ctx.cleanup(fn)` (effects only) registers a teardown to fire on
845
- re-run and unmount.
846
- - `ctx.host` is the host element, for DOM-observing effects.
847
- - `ctx.tools` is a host-registered async tool registry (see `el.setTools(...)`).
848
-
849
- The body runs inside `(async () => { … })()` so `await` is free. Errors
850
- are caught and logged — a broken body never crashes the host page.
851
-
852
- For long-lived behaviour, prefer an `effect`:
853
-
854
- ```text
855
- effect [$draft, debounce(500)] {
856
- js {
857
- await fetch("/save", { method: "POST", body: JSON.stringify({ draft: ctx.state.get("draft") }) })
858
- }
859
- }
860
- ```
861
-
862
- The default (full) system prompt teaches `effect` / `action` / `js{}`;
863
- the chat-flavoured prompt (`getSystemPrompt({ mode: "chat" })`) omits
864
- the JS section entirely.
865
-
866
- See the
867
- [JavaScript interactions guide](https://asfand-dev.github.io/aktion/javascript-interactions.html)
868
- or the deep
869
- [`coding-gen-skill.md`](./coding-gen-skill.md)
870
- for a full walkthrough.
871
-
872
- ---
873
-
874
1161
  ## Built-in globals
875
1162
 
876
- Two namespace globals are always in scope inside a Aktion
877
- program — no import, no `js{}` block required. Both follow the standard
878
- `obj.method(args)` method-call syntax and accept named-arg options.
1163
+ Two namespace globals are always in scope inside an Aktion
1164
+ program — no import required. Both follow the standard
1165
+ `obj.method(args)` method-call syntax and accept object-literal options.
879
1166
 
880
- ```text
881
- # localStorage is the default; `storage.local` is its alias.
882
- storage.set("name", "John")
883
- $name = storage.get("name")
1167
+ ```js
1168
+ // localStorage is the default; `$storage.local` is its alias.
1169
+ $storage.set("name", "John")
1170
+ $name = $storage.get("name")
884
1171
 
885
- # Per-tab sessionStorage.
886
- storage.session.set("draft", $draft)
887
- $draft = storage.session.get("draft")
1172
+ // Per-tab sessionStorage.
1173
+ $storage.session.set("draft", $draft)
1174
+ $draft = $storage.session.get("draft")
888
1175
 
889
- # Cookies — named-arg options become a single options object.
890
- storage.cookies.set("user", "John", expires: 7, path: "/", sameSite: "Lax")
891
- $user = storage.cookies.get("user")
892
- storage.cookies.remove("user", path: "/")
1176
+ // Cookies — options as an object literal.
1177
+ $storage.cookies.set("user", "John", { expires: 7, path: "/", sameSite: "Lax" })
1178
+ $user = $storage.cookies.get("user")
1179
+ $storage.cookies.remove("user", { path: "/" })
893
1180
 
894
- # Forwards to the host console.
1181
+ // Forwards to the host console.
895
1182
  console.log("Hello", $user)
896
1183
  console.error("Something failed", $error)
897
1184
  ```
@@ -912,28 +1199,45 @@ for the full surface.
912
1199
 
913
1200
  ## Internationalization
914
1201
 
915
- The `$i18n = i18n({...})` declaration configures the active locale,
916
- message bundles, and fallback. A global `t(key, vars?)` builtin and a
917
- `Locale()` helper feed the active locale into `@Format` / `@FormatDate`.
918
-
919
- ```text
920
- $i18n = i18n({
921
- locale: "fr-FR",
922
- fallback: "en",
923
- messages: {
924
- greeting: "Bonjour, ${name}!",
925
- orders: { title: "Commandes récentes" }
1202
+ Call `$i18n({...})` to build a translation bundle. You can destructure
1203
+ `t`, `setCurrentLanguage`, and `getCurrentLanguage`, or keep the result
1204
+ as an instance and call its methods.
1205
+
1206
+ ```js
1207
+ const { t, setCurrentLanguage, getCurrentLanguage } = $i18n({
1208
+ defaultLanguage: "en",
1209
+ currentLanguage: "fr",
1210
+ translations: {
1211
+ greeting: { en: "Hello, {name}!", fr: "Bonjour, {name}!" },
1212
+ orders_title:{ en: "Recent orders", fr: "Commandes récentes" },
1213
+ items_count: { en: "{count} items", fr: "{count} objets" }
926
1214
  }
927
1215
  })
928
1216
 
929
- welcome = Text(t("greeting", { name: $user.name }))
930
- sectionTitle = SectionHeader(t("orders.title"))
931
- formatted = Text(@Format(1234.5, "currency", "EUR", Locale()))
1217
+ welcome = Text(t("greeting", { name: $user.name }))
1218
+ sectionTitle = SectionHeader(t("orders_title"))
1219
+ count = Text(t("items_count", { count: 5 }))
932
1220
  ```
933
1221
 
934
- Keys support dot paths. Variables are interpolated using `${name}`
935
- placeholders. Missing keys fall back to the fallback locale's bundle,
936
- then to the bare key as a literal string.
1222
+ Lookups resolve `translations[key][currentLanguage]`, fall back to
1223
+ `translations[key][defaultLanguage]`, then to the bare key as a literal
1224
+ string. Variables are interpolated using `{name}` placeholders.
1225
+
1226
+ For reactive language switching, drive `currentLanguage` from a state
1227
+ atom and either call `setCurrentLanguage(...)` or rebuild the bundle:
1228
+
1229
+ ```js
1230
+ $lang = "fr"
1231
+ const i18nInstance = $i18n({
1232
+ defaultLanguage: "en",
1233
+ currentLanguage: $lang,
1234
+ translations: { hi: { en: "Hi", fr: "Salut", de: "Hallo" } }
1235
+ })
1236
+ aktion = Column([
1237
+ Text(i18nInstance.t("hi")),
1238
+ Button("Deutsch", { onClick: () => { $lang = "de" } })
1239
+ ])
1240
+ ```
937
1241
 
938
1242
  ---
939
1243
 
@@ -988,8 +1292,8 @@ import {
988
1292
  ```
989
1293
 
990
1294
  - `formatProgram` projects the parsed AST back to canonical source —
991
- `prop: value` named args, double-quoted strings, two-space block
992
- indentation, `bind:` preserved, template literals intact.
1295
+ object-literal named args, double-quoted strings, two-space block
1296
+ indentation, template literals intact.
993
1297
  - `inspectAST(source)` returns a JSON-friendly view of the Committed +
994
1298
  Drafting ASTs at the current byte position — bindings (with
995
1299
  kind / line / column / summary), in-flight names, and any parse errors.
@@ -1003,6 +1307,123 @@ import {
1003
1307
 
1004
1308
  ---
1005
1309
 
1310
+ ## Build-time compiler & multi-file modules
1311
+
1312
+ > **Optional.** The CDN bundle and the streamed-string path
1313
+ > (`<aktion-app response="...">`, `setResponse`, `appendChunk`) work exactly as
1314
+ > before. This is an opt-in enhancement for NPM consumers who author UI by hand
1315
+ > and want multi-file modules, type-safety, source maps, and IDE integration.
1316
+
1317
+ When you install `aktion-runtime` from NPM you can author UI in `.aktion` files
1318
+ and let a Vite/Rollup plugin **compile them at build time** into the
1319
+ already-parsed, schema-validated component tree. The browser then mounts that
1320
+ pre-parsed AST without running the parser. The runtime stays fully reactive —
1321
+ `$state`, `$http`, effects, and routing all run in the browser as usual; only
1322
+ parsing, linking, and validation move to build time.
1323
+
1324
+ **What you get:** multi-file `import`/`export`; parse + schema errors become
1325
+ **build errors** (unknown component / prop / enum, surfaced in Vite's overlay
1326
+ with a code frame); a typed `CompiledProgram` default export; **source maps**
1327
+ back to your `.aktion` file; and editor diagnostics/hover/completions (see
1328
+ [Editor support](#editor-support)). HMR is automatic and **preserves live
1329
+ `$state`** across edits — even when you edit an imported module.
1330
+
1331
+ ### Setup
1332
+
1333
+ ```ts
1334
+ // vite.config.ts
1335
+ import { defineConfig } from "vite";
1336
+ import aktion from "aktion-runtime/vite";
1337
+
1338
+ export default defineConfig({ plugins: [aktion()] });
1339
+ ```
1340
+
1341
+ ```jsonc
1342
+ // tsconfig.json — make TypeScript resolve `import ui from "./app.aktion"`
1343
+ { "compilerOptions": { "types": ["aktion-runtime/aktion-modules"] } }
1344
+ ```
1345
+
1346
+ ### Authoring
1347
+
1348
+ A `.aktion` file is pure DSL (identical grammar to a streamed response):
1349
+
1350
+ ```
1351
+ // src/dashboard.aktion
1352
+ $count = 0
1353
+ aktion = Card([
1354
+ CardHeader("Counter"),
1355
+ Button(`Clicked ${$count} times`, { action: increment })
1356
+ ])
1357
+ function increment() { $count = $count + 1 }
1358
+ ```
1359
+
1360
+ ### Multi-file modules
1361
+
1362
+ `.aktion` files `import`/`export` like JS/TS, with **true module scope** — a
1363
+ file's non-exported top-level names (components, actions, `$state`, helpers) are
1364
+ private to that file:
1365
+
1366
+ ```
1367
+ // src/components/counter.aktion
1368
+ export $count = 0
1369
+ export function Counter() {
1370
+ return Button(`Clicked ${$count}`, { action: bump })
1371
+ }
1372
+ function bump() { $count = $count + 1 } // private to this module
1373
+ ```
1374
+
1375
+ ```
1376
+ // src/app.aktion (entry — must define `aktion`)
1377
+ import { Counter, $count } from "./components/counter.aktion"
1378
+ aktion = Column([Markdown(`Shared count: ${$count}`), Counter()])
1379
+ ```
1380
+
1381
+ Named imports only (`import { A, B as C, $shared } from "./mod.aktion"`); a
1382
+ `$state` import keeps its `$`. The compiler resolves the import graph at build
1383
+ time and links it into one program, renaming each module's private names so two
1384
+ files can reuse a name without clashing. The **entry** keeps its own names
1385
+ canonical (the `aktion` binding and the `$state` names that `serializeState` /
1386
+ `applyDelta` target). Importing is a build-time feature — the streaming runtime
1387
+ path stays single-file.
1388
+
1389
+ ### Mounting
1390
+
1391
+ ```ts
1392
+ import "aktion-runtime"; // registers <aktion-app>
1393
+ import app from "./app.aktion"; // a typed CompiledProgram (the whole linked graph)
1394
+
1395
+ document.querySelector("aktion-app").mountCompiled(app);
1396
+ ```
1397
+
1398
+ Editing any file in the graph hot-reloads in place: the plugin recompiles
1399
+ (imported files are registered as watched dependencies), and the self-accepting
1400
+ module re-mounts the program while replaying the current `$state` via
1401
+ `serializeState()`, so live state survives the edit.
1402
+
1403
+ ### Editor support
1404
+
1405
+ The [Aktion VS Code extension](./editors/vscode/) treats `.aktion` as
1406
+ TypeScript (highlighting) and adds inline diagnostics, hover, completions, and
1407
+ snippets via the DOM-free `aktion-runtime/language` API — the same schema-aware
1408
+ language service the docs playground uses.
1409
+
1410
+ ### Package entry points
1411
+
1412
+ | Import | Runs in | Purpose |
1413
+ | ------------------------------- | ------- | ------------------------------------------------------------- |
1414
+ | `aktion-runtime` | browser | the `<aktion-app>` element + `mountCompiled` |
1415
+ | `aktion-runtime/vite` | Node | the Vite/Rollup plugin (`aktion()`) |
1416
+ | `aktion-runtime/compiler` | Node | `compile(source, opts)` for programmatic/build use |
1417
+ | `aktion-runtime/language` | Node | DOM-free diagnostics/hover/completions/snippets (editors/LSP) |
1418
+ | `aktion-runtime/aktion-modules` | types | ambient `*.aktion` module declarations |
1419
+
1420
+ The plugin, compiler, and language service ship as a **separate Node entry**
1421
+ (`dist/node/`) and never enter the browser bundle, so `dist/aktion.js` is
1422
+ unchanged. A runnable example lives in
1423
+ [`examples/vite-compiler/`](./examples/vite-compiler/).
1424
+
1425
+ ---
1426
+
1006
1427
  ## Documentation site
1007
1428
 
1008
1429
  The `docs/` folder is the source for the live documentation site at
@@ -1016,14 +1437,16 @@ consumes from the CDN.
1016
1437
  | `get-started.html` | Step-by-step integration walkthrough. |
1017
1438
  | `frameworks.html` | Integration recipes for React, Next.js, Vue, Angular, Svelte, plain HTML. |
1018
1439
  | `language.html` | Full Aktion language reference. |
1440
+ | `http.html` | HTTP guide — the `$http({...})` primitive, config options, the reactive resource bag, `Async`, refetch/cancel patterns, and a full CRUD walkthrough. |
1019
1441
  | `components.html` | Every built-in component with a live preview, positional signatures, prop tables, and enum values. |
1020
- | `actions.html` | `action Name() { … }` guide — declarative state mutations, optimistic snapshot/rollback, lambda-based click handlers, navigation, and end-to-end examples. |
1021
- | `side-effects.html` | `effect [ ...deps ] { … }` guide — anonymous side effects, dependency entries (state, lifecycle, intervals, debounce/throttle), top-level vs. component-local scope, cleanup, and effect vs. action. |
1022
- | `javascript-interactions.html` | `effect [ ...deps ] { js { … } }` + action `js{}` bodies — the JS escape hatch. |
1442
+ | `actions.html` | `function name() { … }` guide — declarative state mutations, optimistic snapshot/rollback, lambda-based click handlers, navigation, and end-to-end examples. |
1443
+ | `side-effects.html` | `$effect(() => { … }, [...deps])` guide — anonymous side effects, dependency entries (state, lifecycle, intervals, debounce/throttle), top-level vs. component-local scope, cleanup, and effect vs. action. |
1444
+ | `javascript-interactions.html` | Effect + action bodies — the JavaScript execution surface. |
1023
1445
  | `routing.html` | Hash-based routing guide — always available at runtime. |
1024
1446
  | `themes.html` | Built-in themes gallery, live picker, side-by-side compare, and the token customization studio. |
1025
1447
  | `examples.html` | Curated showcase of real-world block UIs (auth, products, FAQ, cart, todos, …). |
1026
1448
  | `playground.html` | CodeMirror 6 editor with custom highlighting / autocomplete, live preview, share links, hover-over component info, and an inspection mode. |
1449
+ | `visual-editor.html` | Drag-and-drop visual editor for the full 170+ component library. Three canvas modes (Raw Edit / Visual Edit / Preview), an Outline tab for top-level entity navigation, typed prop editors, cross-entity selection, and import / export of `.aktion` + self-contained HTML via an editable Source drawer. |
1027
1450
  | `chat-bot.html` | OpenRouter-powered streaming chat with four generation modes (Chat Compact, Chat Full, Website Builder, App Builder), image / PDF attachment support, and download-as-standalone-HTML. |
1028
1451
  | `live-examples.html` | Catalog page that links every demo into the shared `live-example.html?example=<slug>` shell. |
1029
1452
  | `live-example.html` | Shared shell for the bundled live examples — picks the demo from the `?example=<slug>` query parameter. |
@@ -1034,20 +1457,19 @@ consumes from the CDN.
1034
1457
 
1035
1458
  Every standalone demo is served by a single shell page
1036
1459
  (`docs/live-example.html`) and a single JS bundle
1037
- (`docs/assets/live-example.js`) that ships every demo's UI Script source
1460
+ (`docs/assets/live-example.js`) that ships every demo's Aktion source
1038
1461
  and setup code together. Open any example with
1039
1462
  `live-example.html?example=<slug>` — the shell renders the original
1040
1463
  hero / source / output layout, so each demo doubles as an integration
1041
- recipe for `setResponse`, `appendChunk`, `setTools`, and `setTheme`.
1464
+ recipe for `setResponse`, `appendChunk`, and `setTheme`.
1042
1465
 
1043
1466
  | Demo slug | Highlights |
1044
1467
  | ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
1045
- | `routing-demo` | A four-page app driven by `pages = _router_({ … })` + `NavLink`, deep links, browser back/forward. |
1046
1468
  | `settings-app` | Tabs, `Switch`, `ToggleGroup`, `Progress`, `Kbd`, danger-zone confirmation `Drawer`. |
1047
1469
  | `data-explorer` | Analytics surface: sortable `DataGrid` + bulk toolbar, `Gauge` SLA dials, `LineChart`, `Heatmap`, `RadarChart`, `ScatterChart`, `Histogram`, `InfiniteList`, `ActivityLog`. |
1048
1470
  | `media-gallery` | Travel magazine: `Carousel` hero, `Gallery` + click-to-zoom `Lightbox`, `VideoPlayer`, `AudioPlayer`, Leaflet-backed `Map`. |
1049
1471
  | `content-studio` | CMS-style authoring surface: `RichTextEditor`, `CodeEditor`, `MultiStepForm`, `ColorPicker`, `TagInput`, `MentionInput`, `PinInput`, `ValidationSummary`, `TopBar`. |
1050
- | `brand-themes.html` | Same UI reskinned with `Theme({...})` for **GitHub**, **Apple**, **Stripe**, **IONOS**, **Notion**, **Vercel** (bespoke UI on its own page). |
1472
+ | `brand-themes.html` | Same UI reskinned with `$theme({...})` for **GitHub**, **Apple**, **Stripe**, **IONOS**, **Notion**, **Vercel** (bespoke UI on its own page). |
1051
1473
 
1052
1474
  The full catalog with tag filters lives at
1053
1475
  [`docs/live-examples.html`](https://asfand-dev.github.io/aktion/live-examples.html).
@@ -1064,12 +1486,12 @@ The full catalog with tag filters lives at
1064
1486
  │ │ ├── builtins.ts # pure @-function helpers
1065
1487
  │ │ ├── evaluator.ts # program planner + binding resolver
1066
1488
  │ │ ├── state.ts # reactive store — `$name = value`
1067
- │ │ ├── effects.ts # EffectRunner + ActionDeclRunner + js{} executor
1068
- │ │ ├── http.ts # http({...}) reactive HTTP primitive + interceptors
1069
- │ │ ├── i18n.ts # $i18n runtime + t() / Locale() builtins
1070
- │ │ ├── storage.ts # storage.local / .session / .cookies bridge
1489
+ │ │ ├── effects.ts # EffectRunner + ActionDeclRunner
1490
+ │ │ ├── http.ts # $http({...}) reactive HTTP primitive + interceptors
1491
+ │ │ ├── i18n.ts # $i18n({...}) factory — returns { t, setCurrentLanguage, getCurrentLanguage }
1492
+ │ │ ├── $storage.ts # $storage.local / .session / .cookies bridge
1071
1493
  │ │ ├── console.ts # console.* host bridge
1072
- │ │ └── router.ts # Hash-based router for _router_({…}) calls and NavLink
1494
+ │ │ └── router.ts # Hash-based router for $router({…}) calls and NavLink
1073
1495
  │ ├── library/ # Component specs and registry
1074
1496
  │ │ └── components/ # layout / content / forms / data / charts / chat /
1075
1497
  │ │ # feedback / navigation / menu / patterns / helpers / router
@@ -1156,23 +1578,14 @@ script.
1156
1578
  npm test
1157
1579
  ```
1158
1580
 
1159
- The suite covers:
1160
-
1161
- - Parser / lexer correctness (`tests/parser.test.ts`).
1162
- - Runtime evaluator + reactive state + `http({...})` (`tests/runtime.test.ts`).
1163
- - `effect` / `action` declarations + `js{}` execution (`tests/javascript-integration.test.ts`).
1164
- - Hash-based router + `NavLink` (`tests/router.test.ts`).
1165
- - Theme resolution and token application (`tests/theme.test.ts`).
1166
- - In-script `Theme(...)` overrides (`tests/in-script-theme.test.ts`).
1167
- - Component library smoke tests (`tests/library.test.ts`).
1168
- - Element-level integration via happy-dom (`tests/element.test.ts`).
1169
- - System prompt generator output (`tests/prompt.test.ts`).
1170
- - Storage + console globals (`tests/storage-console.test.ts`).
1171
- - End-to-end programs (`tests/suis2-end-to-end.test.ts`).
1172
- - Language support spec for editor / tooling integrations (`tests/language.test.ts`).
1173
- - One-positional-max enforcement (`tests/suis2-one-positional.test.ts`).
1174
- - Component prop aliases (`tests/suis2-prop-aliases.test.ts`).
1175
- - Icon rendering (`tests/icons.test.ts`).
1581
+ The suite covers parser/lexer, runtime evaluator + reactive state +
1582
+ `$http({...})`, effects / actions, the hash-based router + `NavLink`,
1583
+ theme resolution, in-script `$theme(...)` overrides, the component
1584
+ library, element-level integration via happy-dom, the system prompt
1585
+ generator, storage / console globals, the language-support spec for
1586
+ editor tooling, prop aliases & one-positional-max enforcement, icon
1587
+ rendering, and language-concept coverage (computed values, math,
1588
+ lambdas, hoisting, i18n, `for` extensions, user components).
1176
1589
 
1177
1590
  ### Build the documentation site
1178
1591
 
@@ -1197,7 +1610,7 @@ Then open <http://localhost:4321/index.html>.
1197
1610
 
1198
1611
  The library treats every LLM-supplied attribute as untrusted and runs
1199
1612
  it through a small set of sanitisers before it lands on the DOM. HTTP
1200
- requests issued by the LLM through `http({...})` flow through your host's
1613
+ requests issued by the LLM through `$http({...})` flow through your host's
1201
1614
  `registerHttpInterceptors({ onRequest, onResponse, onError })` chain so
1202
1615
  auth headers, CORS workarounds, and refresh-token retries stay under
1203
1616
  host control.
@@ -1215,37 +1628,21 @@ renderer get `rel="noopener noreferrer"` so the destination cannot
1215
1628
  read the opener's `document.referrer`.
1216
1629
 
1217
1630
  If you embed `<aktion-app>` behind a CSP, the bundle does not
1218
- use `eval`. `js{}` bodies inside `effect` / `action` declarations are
1219
- evaluated with `new Function(...)` which requires `'unsafe-eval'` if
1220
- you want them to work; if you cannot relax CSP, simply avoid emitting
1221
- `js{}` blocks from the LLM — every other part of the runtime keeps
1222
- working without the JS escape hatch.
1631
+ use `eval`. Effect and action bodies are evaluated with
1632
+ `new Function(...)` which requires `'unsafe-eval'` if you want them to
1633
+ run arbitrary JavaScript; if you cannot relax CSP, simply avoid emitting
1634
+ complex JS expressions from the LLM — declarative constructs (component
1635
+ trees, `$http()`, `@`-functions) keep working without `unsafe-eval`.
1223
1636
 
1224
1637
  ---
1225
1638
 
1226
1639
  ## CDN deployment
1227
1640
 
1228
- This repository ships its own copy of the bundle on GitHub Pages, so
1229
- most users do not need to host anything themselves:
1230
-
1231
- ```html
1232
- <script type="module" src="https://asfand-dev.github.io/aktion/dist/aktion.js"></script>
1233
- <aktion-app theme="dark"></aktion-app>
1234
- ```
1235
-
1236
- …plus a fetch of `system_prompt.txt` server-side to build LLM messages:
1237
-
1238
- ```bash
1239
- curl https://asfand-dev.github.io/aktion/dist/system_prompt.txt
1240
- ```
1241
-
1242
- To ship your own copy, run `npm run build` and serve the `dist/` folder
1243
- from any static host — every artifact in `dist/` is self-contained.
1244
-
1245
- GitHub Pages deployment for this repo is automated via
1246
- [`.github/workflows/deploy-pages.yml`](.github/workflows/deploy-pages.yml).
1247
- Push to `main` and the workflow will build, test, assemble `site/`, and
1248
- publish.
1641
+ This repo serves its own bundle on GitHub Pages (see Quick start §1).
1642
+ To ship your own copy, run `npm run build` and serve `dist/` from any
1643
+ static host — every artifact in `dist/` is self-contained. Push to
1644
+ `main` and [`.github/workflows/deploy-pages.yml`](.github/workflows/deploy-pages.yml)
1645
+ builds, tests, and publishes.
1249
1646
 
1250
1647
  ---
1251
1648