aktion-runtime 0.5.4 → 0.5.5

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 (68) hide show
  1. package/README.md +90 -114
  2. package/dist/aktion.iife.js +106 -460
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +5530 -5076
  5. package/dist/aktion.js.map +1 -1
  6. package/dist/aktion.umd.cjs +106 -460
  7. package/dist/aktion.umd.cjs.map +1 -1
  8. package/dist/devtools.js +1367 -0
  9. package/dist/devtools.js.map +1 -0
  10. package/dist/{node/index-8OvnOYPI.js → language.js} +13669 -12428
  11. package/dist/language.js.map +1 -0
  12. package/dist/plugin.cjs +2650 -0
  13. package/dist/plugin.cjs.map +1 -0
  14. package/dist/plugin.js +2650 -0
  15. package/dist/plugin.js.map +1 -0
  16. package/dist/system_prompt.txt +164 -447
  17. package/dist/system_prompt_chat.txt +33 -84
  18. package/dist/{node/index-DBgA3bHQ.cjs → testing.js} +28116 -12689
  19. package/dist/testing.js.map +1 -0
  20. package/dist/types/aktion-modules.d.ts +6 -10
  21. package/dist/types/compiler/index.d.ts +9 -11
  22. package/dist/types/compiler/linker.d.ts +11 -11
  23. package/dist/types/compiler/project.d.ts +45 -0
  24. package/dist/types/compiler/runtime.d.ts +22 -26
  25. package/dist/types/devtools/hook.d.ts +88 -0
  26. package/dist/types/devtools/index.d.ts +35 -0
  27. package/dist/types/devtools/panel.d.ts +109 -0
  28. package/dist/types/devtools/protocol.d.ts +130 -0
  29. package/dist/types/devtools/styles.d.ts +7 -0
  30. package/dist/types/element.d.ts +56 -24
  31. package/dist/types/index.d.ts +1 -1
  32. package/dist/types/language-api.d.ts +8 -8
  33. package/dist/types/parser/types.d.ts +8 -8
  34. package/dist/types/plugin/index.d.ts +13 -6
  35. package/dist/types/renderer/renderer.d.ts +28 -0
  36. package/dist/types/runtime/builtins.d.ts +5 -11
  37. package/dist/types/runtime/effects.d.ts +15 -0
  38. package/dist/types/runtime/http.d.ts +0 -1
  39. package/dist/types/testing/index.d.ts +201 -0
  40. package/dist/types/theme/index.d.ts +3 -3
  41. package/dist/types/theme/styles.d.ts +1 -1
  42. package/dist/types/tooling/formatter.d.ts +7 -1
  43. package/dist/types/tooling/index.d.ts +0 -3
  44. package/package.json +21 -19
  45. package/dist/node/compile-BUw0GAvN.cjs +0 -491
  46. package/dist/node/compile-BUw0GAvN.cjs.map +0 -1
  47. package/dist/node/compile-DxttTzo8.js +0 -492
  48. package/dist/node/compile-DxttTzo8.js.map +0 -1
  49. package/dist/node/compiler.cjs +0 -11
  50. package/dist/node/compiler.cjs.map +0 -1
  51. package/dist/node/compiler.js +0 -11
  52. package/dist/node/compiler.js.map +0 -1
  53. package/dist/node/index-8OvnOYPI.js.map +0 -1
  54. package/dist/node/index-DBgA3bHQ.cjs.map +0 -1
  55. package/dist/node/language.cjs +0 -1244
  56. package/dist/node/language.cjs.map +0 -1
  57. package/dist/node/language.js +0 -1244
  58. package/dist/node/language.js.map +0 -1
  59. package/dist/node/vite.cjs +0 -65
  60. package/dist/node/vite.cjs.map +0 -1
  61. package/dist/node/vite.js +0 -65
  62. package/dist/node/vite.js.map +0 -1
  63. package/dist/types/compiler/compile.d.ts +0 -54
  64. package/dist/types/compiler/emit.d.ts +0 -15
  65. package/dist/types/compiler/sourcemap.d.ts +0 -40
  66. package/dist/types/library/components/theme.d.ts +0 -2
  67. package/dist/types/plugin/vite.d.ts +0 -21
  68. package/dist/types/tooling/codemod.d.ts +0 -36
package/README.md CHANGED
@@ -13,10 +13,10 @@ renderer for an LLM's response.
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
- aktion = Card([
16
+ $app(Card([
17
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>
21
21
  ```
22
22
 
@@ -131,8 +131,8 @@ Everything you need at runtime ships in a single bundle:
131
131
  - **Seven built-in themes** (`light`, `dark`, `neon`, `pastel`, `glass`,
132
132
  `brutalist`, `skyline`) plus full custom-token support via CSS custom
133
133
  properties. **50+ design tokens** organised into `colors`, `radius`,
134
- `font`, `motion`, and `elevation` groups. Brand the UI from inside
135
- the script with `theme = $theme({...})`.
134
+ and `font` groups. Brand the UI from inside the script with
135
+ `$theme({...})` statement.
136
136
  - **`$i18n` factory.** `const { t, setCurrentLanguage, getCurrentLanguage } = $i18n({ defaultLanguage, currentLanguage, translations })` builds a translation bundle keyed by language, with `{name}` placeholder interpolation.
137
137
  - **Font Awesome 6.7.2** auto-loaded — every `icon` prop accepts a Free
138
138
  Font Awesome name (no `fa-` prefix). Use `Icon(name, { variant?, size? })`
@@ -212,18 +212,18 @@ Three equivalent ways:
212
212
 
213
213
  ```html
214
214
  <!-- as an attribute -->
215
- <aktion-app response='aktion = Card([CardHeader("Hi")])'></aktion-app>
215
+ <aktion-app response='$app(Card([CardHeader("Hi")]))'></aktion-app>
216
216
 
217
217
  <!-- as inner text (rendered on connect) -->
218
218
  <aktion-app>
219
- aktion = Card([CardHeader("Hi")])
219
+ $app(Card([CardHeader("Hi")]))
220
220
  </aktion-app>
221
221
 
222
222
  <!-- as a property/method -->
223
223
  <script>
224
224
  const el = document.querySelector("aktion-app");
225
225
  el.setResponse(`
226
- aktion = Column([greeting])
226
+ $app(Column([greeting]))
227
227
  greeting = Card([CardHeader("Hello", { subtitle: "Generative UI in plain HTML" })])
228
228
  `);
229
229
  </script>
@@ -329,7 +329,6 @@ surfaces from the *generated prompt*, build it via
329
329
  | `hydrateState(snapshot)` | Apply a snapshot to the live store and schedule a re-render. Atoms not in the snapshot are untouched. |
330
330
  | `loadSnapshot({ programText, state })` | Atomic program + state load. The next render plans the program with the hydrated state already in place. |
331
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). |
333
332
 
334
333
  ### Events
335
334
 
@@ -408,13 +407,14 @@ pages = $router({
408
407
  default: NotFound()
409
408
  })
410
409
 
411
- aktion = pages
410
+ $app(pages)
412
411
  ```
413
412
 
414
413
  ### Key constructs
415
414
 
416
- - `aktion = …` — the reserved entry point. Every program renders from
417
- it.
415
+ - `$app(…)` — the reserved entry point. Every program renders from
416
+ it. It accepts a single root node, an array of nodes (rendered as
417
+ siblings), or variadic nodes.
418
418
  - `$name = value` — reactive state. One kind. Read or write with the
419
419
  same sigil. Inside action / effect / lambda bodies, assignment
420
420
  operators (`= += -= *= /= ??= ++ --`) are all allowed.
@@ -538,7 +538,7 @@ aktion = pages
538
538
  shadow root. Use only when the standard component library cannot
539
539
  express the design.
540
540
  - **Hoisting & streaming** — references resolve from the entire
541
- top-level scope, not source order. Always emit `aktion = …` first
541
+ top-level scope, not source order. Always call `$app(…)` first
542
542
  so the reconciler has the page shell to attach streamed leaves to.
543
543
  - Comments: `//` line comments and `/* block */` comments — standard
544
544
  JS style.
@@ -578,7 +578,7 @@ chart = LineChart({
578
578
  series: [Series("Events", $data.data?.daily?.events ?? [])]
579
579
  })
580
580
 
581
- aktion = Column([CardHeader("Analytics"), filter, kpi, chart])
581
+ $app(Column([CardHeader("Analytics"), filter, kpi, chart]))
582
582
  ```
583
583
 
584
584
  Highlights:
@@ -593,7 +593,7 @@ Highlights:
593
593
  plus pluck (`$rows.title` → `[title1, title2, …]`).
594
594
  - Responsive prop maps on layout components:
595
595
  `Grid(items, { columns: { sm: 1, md: 2, lg: 4 }, gap: "l" })`.
596
- - Forward references are allowed — list `aktion = Column([...])` first
596
+ - Forward references are allowed — call `$app(Column([...]))` first
597
597
  and let the children stream in beneath it.
598
598
 
599
599
  ### Declarative todo app
@@ -617,11 +617,11 @@ row = t => Card([Stack([
617
617
  ])])
618
618
 
619
619
  list = $todos.map(t => row(t))
620
- aktion = Stack([
620
+ $app(Stack([
621
621
  Input("draft-input", { placeholder: "What needs doing?", value: $draft }),
622
622
  Button("Add", { onClick: add, variant: "primary" }),
623
623
  list
624
- ])
624
+ ]))
625
625
  ```
626
626
 
627
627
  ### Fine-grained reactivity
@@ -706,7 +706,7 @@ function Counter(label) {
706
706
  }
707
707
 
708
708
  // Two independent counters — each holds its own atom.
709
- aktion = Stack([Counter("A"), Counter("B")])
709
+ $app(Stack([Counter("A"), Counter("B")]))
710
710
  ```
711
711
 
712
712
  Every call site accepts a universal `key` named argument. The renderer
@@ -736,7 +736,7 @@ function Counter() {
736
736
  ])
737
737
  }
738
738
 
739
- aktion = Counter()
739
+ $app(Counter())
740
740
  ```
741
741
 
742
742
  - `$state(initial)` returns a `[value, setValue]` pair. `setValue(next)`
@@ -793,7 +793,7 @@ cart = $store({
793
793
  // Siblings with no relationship both talk to the same cart.
794
794
  function AddLatte() { return Button("Add", { onClick: () => cart.add({ price: 4.5 }) }) }
795
795
  function MiniCart() { return Text(`${cart.count()} items — ${$util.format(cart.total(), "currency")}`) }
796
- aktion = Column([AddLatte(), MiniCart()])
796
+ $app(Column([AddLatte(), MiniCart()]))
797
797
  ```
798
798
 
799
799
  Reads are fine-grained and per-component (changing `cart.items` re-renders
@@ -813,7 +813,7 @@ tree. Two `LiveClock()` calls produce two independent intervals — and
813
813
  removing one stops only that one:
814
814
 
815
815
  ```js
816
- aktion = Stack([LiveClock("UTC"), LiveClock("Local")])
816
+ $app(Stack([LiveClock("UTC"), LiveClock("Local")]))
817
817
 
818
818
  function LiveClock(label) {
819
819
  $now = $util.now()
@@ -954,7 +954,7 @@ board = KanbanBoard([
954
954
  ])
955
955
  follow = FollowUpBlock(["Show at-risk projects", "Compare to Q2", "Who needs help?"])
956
956
 
957
- aktion = Column([dashHeader, kpis, board, follow])
957
+ $app(Column([dashHeader, kpis, board, follow]))
958
958
  ```
959
959
 
960
960
  ### Adding your own components
@@ -1026,12 +1026,11 @@ el.setTheme({
1026
1026
 
1027
1027
  ### `$theme({...})` from inside a response
1028
1028
 
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.
1029
+ A response can brand itself with a `$theme({...})` statement. The tokens land on the host as CSS variables on top
1030
+ of the base theme.
1032
1031
 
1033
1032
  ```js
1034
- theme = $theme({
1033
+ $theme({
1035
1034
  colors: {
1036
1035
  primary: "#0969da",
1037
1036
  border: "#d0d7de",
@@ -1045,12 +1044,12 @@ theme = $theme({
1045
1044
  radius: { button: "6px", input: "6px" }
1046
1045
  })
1047
1046
 
1048
- aktion = Column([CardHeader("GitHub-style page"), Buttons([Button("New repository")])])
1047
+ $app(Column([CardHeader("GitHub-style page"), Buttons([Button("New repository")])]))
1049
1048
  ```
1050
1049
 
1051
1050
  `$theme` expects the **structured** form — top-level groups `colors` /
1052
- `radius` / `font` / `motion` / `elevation` (plus metadata keys `name`
1053
- and `direction`). Removing the `$theme(...)` line snaps the UI back to
1051
+ `radius` / `font` (plus metadata keys `name` and `direction`). Removing
1052
+ the `$theme(...)` line snaps the UI back to
1054
1053
  the base theme. Unknown keys are ignored silently, so typos in an
1055
1054
  LLM-emitted token map can never break the page.
1056
1055
 
@@ -1104,7 +1103,7 @@ kpis = Stats([
1104
1103
  StatCard("Orders", { value: "1,284", trend: "up", delta: "+8%", icon: "cart-shopping" }),
1105
1104
  StatCard("Refunds", { value: "12", trend: "down", delta: "-3", icon: "rotate-left" })
1106
1105
  ])
1107
- aktion = Stack([brandIcon, kpis, profileTab])
1106
+ $app(Stack([brandIcon, kpis, profileTab]))
1108
1107
  ```
1109
1108
 
1110
1109
  ---
@@ -1130,7 +1129,7 @@ nav = Row([
1130
1129
  NavLink("Users", { to: "/users" })
1131
1130
  ], { gap: "s" })
1132
1131
 
1133
- aktion = Stack([nav, pages])
1132
+ $app(Stack([nav, pages]))
1134
1133
 
1135
1134
  homePage = Card([CardHeader("Welcome")])
1136
1135
  dashboardPage = Card([CardHeader("Dashboard")])
@@ -1233,10 +1232,10 @@ const i18nInstance = $i18n({
1233
1232
  currentLanguage: $lang,
1234
1233
  translations: { hi: { en: "Hi", fr: "Salut", de: "Hallo" } }
1235
1234
  })
1236
- aktion = Column([
1235
+ $app(Column([
1237
1236
  Text(i18nInstance.t("hi")),
1238
1237
  Button("Deutsch", { onClick: () => { $lang = "de" } })
1239
- ])
1238
+ ]))
1240
1239
  ```
1241
1240
 
1242
1241
  ---
@@ -1311,116 +1310,93 @@ import {
1311
1310
 
1312
1311
  > **Optional.** The CDN bundle and the streamed-string path
1313
1312
  > (`<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
1313
+ > before. This is an opt-in enhancement for NPM consumers who author UI by hand.
1332
1314
 
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
- ```
1315
+ Author UI in `.aktion` files that `import`/`export` from one another like JS/TS
1316
+ modules, then mount the pre-parsed, linked program with
1317
+ `el.mountCompiled(program)` — the runtime parser never runs in the browser. The
1318
+ runtime stays fully reactive (`$state`, `$http`, effects, routing run as usual);
1319
+ only parsing + linking move ahead of time.
1359
1320
 
1360
1321
  ### Multi-file modules
1361
1322
 
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:
1323
+ Named `import`/`export` with **true module scope** — a file's non-exported
1324
+ top-level names are private:
1365
1325
 
1366
- ```
1326
+ ```js
1367
1327
  // src/components/counter.aktion
1368
1328
  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
- ```
1329
+ export function Counter() { return Button(`Clicked ${$count}`, { action: bump }) }
1330
+ function bump() { $count = $count + 1 } // private to this module
1374
1331
 
1375
- ```
1376
1332
  // src/app.aktion (entry — must define `aktion`)
1377
1333
  import { Counter, $count } from "./components/counter.aktion"
1378
1334
  aktion = Column([Markdown(`Shared count: ${$count}`), Counter()])
1379
1335
  ```
1380
1336
 
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.
1337
+ The linker merges the graph into one program, renaming each module's private
1338
+ names so two files can reuse a name without clashing; the entry keeps its own
1339
+ names canonical (the `aktion` binding + the `$state` names that `serializeState`
1340
+ / `applyDelta` target).
1341
+
1342
+ ### Vite plugin
1388
1343
 
1389
- ### Mounting
1344
+ The `aktion-runtime/vite` plugin compiles `.aktion` files at build time so you
1345
+ can import them directly, with HMR that preserves live `$state`:
1390
1346
 
1391
1347
  ```ts
1392
- import "aktion-runtime"; // registers <aktion-app>
1393
- import app from "./app.aktion"; // a typed CompiledProgram (the whole linked graph)
1348
+ // vite.config.ts
1349
+ import aktion from "aktion-runtime/vite";
1350
+ export default { plugins: [aktion()] };
1351
+ ```
1352
+
1353
+ ```jsonc
1354
+ // tsconfig.json — resolve `import app from "./app.aktion"`
1355
+ { "compilerOptions": { "types": ["aktion-runtime/aktion-modules"] } }
1356
+ ```
1394
1357
 
1358
+ ```ts
1359
+ import "aktion-runtime";
1360
+ import app from "./app.aktion"; // a typed CompiledProgram (the linked graph)
1395
1361
  document.querySelector("aktion-app").mountCompiled(app);
1396
1362
  ```
1397
1363
 
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.
1364
+ Scaffold a ready-made Vite + TypeScript project with **`npm create aktion@latest`**
1365
+ (see [`create-aktion`](./create-aktion/)). A runnable example lives in
1366
+ [`examples/vite-compiler/`](./examples/vite-compiler/).
1367
+
1368
+ ### Link in the browser (no bundler)
1369
+
1370
+ The linker is browser-safe and re-exported from the package root, so a host (or
1371
+ the playground) can link a project in-page from raw sources:
1372
+
1373
+ ```ts
1374
+ import { linkProject, defineCompiledProgram } from "aktion-runtime";
1375
+ const { program, source } = await linkProject({
1376
+ entry: "app.aktion",
1377
+ files: { "app.aktion": "…", "components/counter.aktion": "…" },
1378
+ });
1379
+ el.mountCompiled(defineCompiledProgram({ __aktionCompiled: 1, program, source, path: "app.aktion" }));
1380
+ ```
1402
1381
 
1403
1382
  ### Editor support
1404
1383
 
1405
1384
  The [Aktion VS Code extension](./editors/vscode/) treats `.aktion` as
1406
1385
  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.
1386
+ snippets via the DOM-free `aktion-runtime/language` API. Its README covers local
1387
+ F5 debugging **and** publishing to the VS Code Marketplace + Open VSX.
1409
1388
 
1410
1389
  ### Package entry points
1411
1390
 
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/).
1391
+ | Import | Runs in | Purpose |
1392
+ | ------------------------------- | ------- | --------------------------------------------------------------------------- |
1393
+ | `aktion-runtime` | browser | `<aktion-app>` + `mountCompiled` + the browser-safe linker (`linkProject`) |
1394
+ | `aktion-runtime/vite` | Node | the Vite/Rollup plugin (`aktion()`) |
1395
+ | `aktion-runtime/language` | Node | DOM-free diagnostics / hover / completions / snippets (editors, LSP) |
1396
+ | `aktion-runtime/aktion-modules` | types | ambient `*.aktion` module declarations |
1397
+
1398
+ The plugin + language service ship as separate entries and never enter the
1399
+ browser bundle, so `dist/aktion.js` is unchanged.
1424
1400
 
1425
1401
  ---
1426
1402