aktion-runtime 0.5.3 → 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 (41) hide show
  1. package/README.md +119 -0
  2. package/dist/aktion.iife.js +34 -34
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +1823 -1644
  5. package/dist/aktion.js.map +1 -1
  6. package/dist/aktion.umd.cjs +34 -34
  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/types/aktion-modules.d.ts +22 -0
  29. package/dist/types/compiler/compile.d.ts +54 -0
  30. package/dist/types/compiler/emit.d.ts +15 -0
  31. package/dist/types/compiler/index.d.ts +14 -0
  32. package/dist/types/compiler/linker.d.ts +27 -0
  33. package/dist/types/compiler/runtime.d.ts +63 -0
  34. package/dist/types/compiler/sourcemap.d.ts +40 -0
  35. package/dist/types/element.d.ts +36 -0
  36. package/dist/types/index.d.ts +1 -0
  37. package/dist/types/language-api.d.ts +15 -0
  38. package/dist/types/parser/types.d.ts +38 -1
  39. package/dist/types/plugin/index.d.ts +10 -0
  40. package/dist/types/plugin/vite.d.ts +21 -0
  41. package/package.json +36 -5
package/README.md CHANGED
@@ -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)
@@ -328,6 +329,7 @@ surfaces from the *generated prompt*, build it via
328
329
  | `hydrateState(snapshot)` | Apply a snapshot to the live store and schedule a re-render. Atoms not in the snapshot are untouched. |
329
330
  | `loadSnapshot({ programText, state })` | Atomic program + state load. The next render plans the program with the hydrated state already in place. |
330
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). |
331
333
 
332
334
  ### Events
333
335
 
@@ -1305,6 +1307,123 @@ import {
1305
1307
 
1306
1308
  ---
1307
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
+
1308
1427
  ## Documentation site
1309
1428
 
1310
1429
  The `docs/` folder is the source for the live documentation site at