aktion-runtime 0.5.3 → 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 (46) hide show
  1. package/README.md +126 -31
  2. package/dist/aktion.iife.js +106 -460
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +5688 -5055
  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/language.js +15311 -0
  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/testing.js +29496 -0
  19. package/dist/testing.js.map +1 -0
  20. package/dist/types/aktion-modules.d.ts +18 -0
  21. package/dist/types/compiler/index.d.ts +12 -0
  22. package/dist/types/compiler/linker.d.ts +27 -0
  23. package/dist/types/compiler/project.d.ts +45 -0
  24. package/dist/types/compiler/runtime.d.ts +59 -0
  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 +76 -8
  31. package/dist/types/index.d.ts +1 -0
  32. package/dist/types/language-api.d.ts +15 -0
  33. package/dist/types/parser/types.d.ts +38 -1
  34. package/dist/types/plugin/index.d.ts +17 -0
  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 +35 -2
  45. package/dist/types/library/components/theme.d.ts +0 -2
  46. 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
 
@@ -46,6 +46,7 @@ HTML, or no framework at all.
46
46
  - [Internationalization (`$i18n`)](#internationalization)
47
47
  - [System prompt generator](#system-prompt-generator)
48
48
  - [Tooling](#tooling)
49
+ - [Build-time compiler & multi-file modules](#build-time-compiler--multi-file-modules)
49
50
  - [Documentation site](#documentation-site)
50
51
  - [Live examples](#live-examples)
51
52
  - [Project layout](#project-layout)
@@ -130,8 +131,8 @@ Everything you need at runtime ships in a single bundle:
130
131
  - **Seven built-in themes** (`light`, `dark`, `neon`, `pastel`, `glass`,
131
132
  `brutalist`, `skyline`) plus full custom-token support via CSS custom
132
133
  properties. **50+ design tokens** organised into `colors`, `radius`,
133
- `font`, `motion`, and `elevation` groups. Brand the UI from inside
134
- the script with `theme = $theme({...})`.
134
+ and `font` groups. Brand the UI from inside the script with
135
+ `$theme({...})` statement.
135
136
  - **`$i18n` factory.** `const { t, setCurrentLanguage, getCurrentLanguage } = $i18n({ defaultLanguage, currentLanguage, translations })` builds a translation bundle keyed by language, with `{name}` placeholder interpolation.
136
137
  - **Font Awesome 6.7.2** auto-loaded — every `icon` prop accepts a Free
137
138
  Font Awesome name (no `fa-` prefix). Use `Icon(name, { variant?, size? })`
@@ -211,18 +212,18 @@ Three equivalent ways:
211
212
 
212
213
  ```html
213
214
  <!-- as an attribute -->
214
- <aktion-app response='aktion = Card([CardHeader("Hi")])'></aktion-app>
215
+ <aktion-app response='$app(Card([CardHeader("Hi")]))'></aktion-app>
215
216
 
216
217
  <!-- as inner text (rendered on connect) -->
217
218
  <aktion-app>
218
- aktion = Card([CardHeader("Hi")])
219
+ $app(Card([CardHeader("Hi")]))
219
220
  </aktion-app>
220
221
 
221
222
  <!-- as a property/method -->
222
223
  <script>
223
224
  const el = document.querySelector("aktion-app");
224
225
  el.setResponse(`
225
- aktion = Column([greeting])
226
+ $app(Column([greeting]))
226
227
  greeting = Card([CardHeader("Hello", { subtitle: "Generative UI in plain HTML" })])
227
228
  `);
228
229
  </script>
@@ -406,13 +407,14 @@ pages = $router({
406
407
  default: NotFound()
407
408
  })
408
409
 
409
- aktion = pages
410
+ $app(pages)
410
411
  ```
411
412
 
412
413
  ### Key constructs
413
414
 
414
- - `aktion = …` — the reserved entry point. Every program renders from
415
- 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.
416
418
  - `$name = value` — reactive state. One kind. Read or write with the
417
419
  same sigil. Inside action / effect / lambda bodies, assignment
418
420
  operators (`= += -= *= /= ??= ++ --`) are all allowed.
@@ -536,7 +538,7 @@ aktion = pages
536
538
  shadow root. Use only when the standard component library cannot
537
539
  express the design.
538
540
  - **Hoisting & streaming** — references resolve from the entire
539
- top-level scope, not source order. Always emit `aktion = …` first
541
+ top-level scope, not source order. Always call `$app(…)` first
540
542
  so the reconciler has the page shell to attach streamed leaves to.
541
543
  - Comments: `//` line comments and `/* block */` comments — standard
542
544
  JS style.
@@ -576,7 +578,7 @@ chart = LineChart({
576
578
  series: [Series("Events", $data.data?.daily?.events ?? [])]
577
579
  })
578
580
 
579
- aktion = Column([CardHeader("Analytics"), filter, kpi, chart])
581
+ $app(Column([CardHeader("Analytics"), filter, kpi, chart]))
580
582
  ```
581
583
 
582
584
  Highlights:
@@ -591,7 +593,7 @@ Highlights:
591
593
  plus pluck (`$rows.title` → `[title1, title2, …]`).
592
594
  - Responsive prop maps on layout components:
593
595
  `Grid(items, { columns: { sm: 1, md: 2, lg: 4 }, gap: "l" })`.
594
- - Forward references are allowed — list `aktion = Column([...])` first
596
+ - Forward references are allowed — call `$app(Column([...]))` first
595
597
  and let the children stream in beneath it.
596
598
 
597
599
  ### Declarative todo app
@@ -615,11 +617,11 @@ row = t => Card([Stack([
615
617
  ])])
616
618
 
617
619
  list = $todos.map(t => row(t))
618
- aktion = Stack([
620
+ $app(Stack([
619
621
  Input("draft-input", { placeholder: "What needs doing?", value: $draft }),
620
622
  Button("Add", { onClick: add, variant: "primary" }),
621
623
  list
622
- ])
624
+ ]))
623
625
  ```
624
626
 
625
627
  ### Fine-grained reactivity
@@ -704,7 +706,7 @@ function Counter(label) {
704
706
  }
705
707
 
706
708
  // Two independent counters — each holds its own atom.
707
- aktion = Stack([Counter("A"), Counter("B")])
709
+ $app(Stack([Counter("A"), Counter("B")]))
708
710
  ```
709
711
 
710
712
  Every call site accepts a universal `key` named argument. The renderer
@@ -734,7 +736,7 @@ function Counter() {
734
736
  ])
735
737
  }
736
738
 
737
- aktion = Counter()
739
+ $app(Counter())
738
740
  ```
739
741
 
740
742
  - `$state(initial)` returns a `[value, setValue]` pair. `setValue(next)`
@@ -791,7 +793,7 @@ cart = $store({
791
793
  // Siblings with no relationship both talk to the same cart.
792
794
  function AddLatte() { return Button("Add", { onClick: () => cart.add({ price: 4.5 }) }) }
793
795
  function MiniCart() { return Text(`${cart.count()} items — ${$util.format(cart.total(), "currency")}`) }
794
- aktion = Column([AddLatte(), MiniCart()])
796
+ $app(Column([AddLatte(), MiniCart()]))
795
797
  ```
796
798
 
797
799
  Reads are fine-grained and per-component (changing `cart.items` re-renders
@@ -811,7 +813,7 @@ tree. Two `LiveClock()` calls produce two independent intervals — and
811
813
  removing one stops only that one:
812
814
 
813
815
  ```js
814
- aktion = Stack([LiveClock("UTC"), LiveClock("Local")])
816
+ $app(Stack([LiveClock("UTC"), LiveClock("Local")]))
815
817
 
816
818
  function LiveClock(label) {
817
819
  $now = $util.now()
@@ -952,7 +954,7 @@ board = KanbanBoard([
952
954
  ])
953
955
  follow = FollowUpBlock(["Show at-risk projects", "Compare to Q2", "Who needs help?"])
954
956
 
955
- aktion = Column([dashHeader, kpis, board, follow])
957
+ $app(Column([dashHeader, kpis, board, follow]))
956
958
  ```
957
959
 
958
960
  ### Adding your own components
@@ -1024,12 +1026,11 @@ el.setTheme({
1024
1026
 
1025
1027
  ### `$theme({...})` from inside a response
1026
1028
 
1027
- A response can brand itself by assigning a `$theme({...})` call to the
1028
- reserved top-level `theme` binding. The tokens land on the host as CSS
1029
- 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.
1030
1031
 
1031
1032
  ```js
1032
- theme = $theme({
1033
+ $theme({
1033
1034
  colors: {
1034
1035
  primary: "#0969da",
1035
1036
  border: "#d0d7de",
@@ -1043,12 +1044,12 @@ theme = $theme({
1043
1044
  radius: { button: "6px", input: "6px" }
1044
1045
  })
1045
1046
 
1046
- aktion = Column([CardHeader("GitHub-style page"), Buttons([Button("New repository")])])
1047
+ $app(Column([CardHeader("GitHub-style page"), Buttons([Button("New repository")])]))
1047
1048
  ```
1048
1049
 
1049
1050
  `$theme` expects the **structured** form — top-level groups `colors` /
1050
- `radius` / `font` / `motion` / `elevation` (plus metadata keys `name`
1051
- 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
1052
1053
  the base theme. Unknown keys are ignored silently, so typos in an
1053
1054
  LLM-emitted token map can never break the page.
1054
1055
 
@@ -1102,7 +1103,7 @@ kpis = Stats([
1102
1103
  StatCard("Orders", { value: "1,284", trend: "up", delta: "+8%", icon: "cart-shopping" }),
1103
1104
  StatCard("Refunds", { value: "12", trend: "down", delta: "-3", icon: "rotate-left" })
1104
1105
  ])
1105
- aktion = Stack([brandIcon, kpis, profileTab])
1106
+ $app(Stack([brandIcon, kpis, profileTab]))
1106
1107
  ```
1107
1108
 
1108
1109
  ---
@@ -1128,7 +1129,7 @@ nav = Row([
1128
1129
  NavLink("Users", { to: "/users" })
1129
1130
  ], { gap: "s" })
1130
1131
 
1131
- aktion = Stack([nav, pages])
1132
+ $app(Stack([nav, pages]))
1132
1133
 
1133
1134
  homePage = Card([CardHeader("Welcome")])
1134
1135
  dashboardPage = Card([CardHeader("Dashboard")])
@@ -1231,10 +1232,10 @@ const i18nInstance = $i18n({
1231
1232
  currentLanguage: $lang,
1232
1233
  translations: { hi: { en: "Hi", fr: "Salut", de: "Hallo" } }
1233
1234
  })
1234
- aktion = Column([
1235
+ $app(Column([
1235
1236
  Text(i18nInstance.t("hi")),
1236
1237
  Button("Deutsch", { onClick: () => { $lang = "de" } })
1237
- ])
1238
+ ]))
1238
1239
  ```
1239
1240
 
1240
1241
  ---
@@ -1305,6 +1306,100 @@ import {
1305
1306
 
1306
1307
  ---
1307
1308
 
1309
+ ## Build-time compiler & multi-file modules
1310
+
1311
+ > **Optional.** The CDN bundle and the streamed-string path
1312
+ > (`<aktion-app response="...">`, `setResponse`, `appendChunk`) work exactly as
1313
+ > before. This is an opt-in enhancement for NPM consumers who author UI by hand.
1314
+
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.
1320
+
1321
+ ### Multi-file modules
1322
+
1323
+ Named `import`/`export` with **true module scope** — a file's non-exported
1324
+ top-level names are private:
1325
+
1326
+ ```js
1327
+ // src/components/counter.aktion
1328
+ export $count = 0
1329
+ export function Counter() { return Button(`Clicked ${$count}`, { action: bump }) }
1330
+ function bump() { $count = $count + 1 } // private to this module
1331
+
1332
+ // src/app.aktion (entry — must define `aktion`)
1333
+ import { Counter, $count } from "./components/counter.aktion"
1334
+ aktion = Column([Markdown(`Shared count: ${$count}`), Counter()])
1335
+ ```
1336
+
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
1343
+
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`:
1346
+
1347
+ ```ts
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
+ ```
1357
+
1358
+ ```ts
1359
+ import "aktion-runtime";
1360
+ import app from "./app.aktion"; // a typed CompiledProgram (the linked graph)
1361
+ document.querySelector("aktion-app").mountCompiled(app);
1362
+ ```
1363
+
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
+ ```
1381
+
1382
+ ### Editor support
1383
+
1384
+ The [Aktion VS Code extension](./editors/vscode/) treats `.aktion` as
1385
+ TypeScript (highlighting) and adds inline diagnostics, hover, completions, and
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.
1388
+
1389
+ ### Package entry points
1390
+
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.
1400
+
1401
+ ---
1402
+
1308
1403
  ## Documentation site
1309
1404
 
1310
1405
  The `docs/` folder is the source for the live documentation site at