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
@@ -1,94 +1,49 @@
1
1
  /**
2
2
  * AST types for Aktion.
3
3
  *
4
- * The grammar is line-oriented:
5
- * identifier = Expression
6
- * $stateVariable = LiteralDefault
7
- * name = Query(...) | Mutation(...)
4
+ * The surface syntax is a strict subset of JavaScript. Identifiers prefixed
5
+ * with `$` denote reactive state; everything else is standard JS:
8
6
  *
9
- * Expressions form a tree of literals, references, calls, and operators.
7
+ * $count = 0
8
+ * let name = "Ada"
9
+ * function Counter(initial) { return ... }
10
+ * effect(() => { ... }, [$count, "mount"])
10
11
  */
11
- export type Expression = LiteralExpr | IdentifierExpr | StateRefExpr | ArrayExpr | ObjectExpr | MemberExpr | UnaryExpr | BinaryExpr | TernaryExpr | CallExpr | MethodCallExpr | BuiltinCallExpr | TemplateLiteralExpr | SpreadExpr | NamedArgExpr | IfExpr | MatchExpr | ForExpr | LambdaExpr | JsBlockExpr | BindExpr | BlockExpr;
12
- /** `if cond { ... } else { ... }` expression — see §8.1. */
13
- export interface IfExpr {
14
- kind: "If";
15
- test: Expression;
16
- consequent: BlockExpr;
17
- alternate?: IfExpr | BlockExpr;
18
- loc?: SourceLocation;
19
- }
20
- /** `match value { pat -> expr, _ -> expr }` expression — see §8.2. */
21
- export interface MatchExpr {
22
- kind: "Match";
23
- discriminant: Expression;
24
- arms: ReadonlyArray<MatchArm>;
25
- loc?: SourceLocation;
26
- }
27
- export interface MatchArm {
28
- /** Literal pattern (string / number / boolean / null / identifier) or `_`. */
29
- pattern: Expression | "_";
30
- body: Expression;
31
- }
32
- /** `for x in arr { body }` expression — see §8.3. */
33
- export interface ForExpr {
34
- kind: "For";
35
- /** Item binding name. */
36
- item: string;
37
- /** Optional `(item, idx)` destructuring index name. */
38
- index?: string;
39
- /** Optional `{a, b, c}` destructuring — binds each named field of the row. */
40
- destructure?: ReadonlyArray<string>;
41
- iterable: Expression;
42
- body: BlockExpr;
43
- loc?: SourceLocation;
12
+ export type Expression = LiteralExpr | IdentifierExpr | StateRefExpr | ArrayExpr | ObjectExpr | MemberExpr | UnaryExpr | BinaryExpr | TernaryExpr | CallExpr | MethodCallExpr | InvokeExpr | BuiltinCallExpr | NewExpr | TemplateLiteralExpr | SpreadExpr | LambdaExpr | BlockExpr;
13
+ export interface SwitchCase {
14
+ /** `null` for the `default` case. */
15
+ test: Expression | null;
16
+ body: ReadonlyArray<Statement>;
44
17
  }
45
- /** `(args) => body` lambda. The body is a single expression OR a `js{}` block. */
18
+ /** `(args) => body` lambda / arrow function. */
46
19
  export interface LambdaExpr {
47
20
  kind: "Lambda";
48
21
  params: ReadonlyArray<LambdaParam>;
49
- body: Expression | JsBlockExpr;
22
+ body: Expression;
50
23
  loc?: SourceLocation;
51
24
  }
52
25
  export interface LambdaParam {
53
26
  name: string;
54
27
  defaultValue?: Expression;
55
- }
56
- /** `js{ ... raw js ... }` opaque block. Runs verbatim under an `effect` or `action` body. */
57
- export interface JsBlockExpr {
58
- kind: "JsBlock";
59
- body: string;
60
- loc?: SourceLocation;
61
- }
62
- /**
63
- * `bind:prop: stateRef` argument. Desugars at runtime to
64
- * `prop: stateRef, on<Prop>Change: (v) => stateRef = v`.
65
- */
66
- export interface BindExpr {
67
- kind: "Bind";
68
- prop: string;
69
- target: Expression;
70
- loc?: SourceLocation;
28
+ /** True for `...rest` parameters — must be the final param. */
29
+ rest?: boolean;
30
+ /**
31
+ * Destructuring pattern parameter — `(x => …)` stays a plain name, but
32
+ * `({ a, b }) => …` / `([a, b]) => …` carry the pattern here. When set,
33
+ * `name` is empty and the binder fans the argument out into the pattern.
34
+ */
35
+ pattern?: DestructuringPattern;
71
36
  }
72
37
  /**
73
- * Statement block delimited by `{ ... }`. Used as the body of `component`,
74
- * `effect`, `action`, `if`, `match`, `for`, and lambdas with multiple
75
- * statements. The last expression in the block (if any) is its value.
38
+ * Statement block delimited by `{ ... }`. Used as the body of `function`,
39
+ * `effect`, `if`, `switch`, `for`, and lambdas with multiple statements.
40
+ * The last expression in the block (if any) is its value.
76
41
  */
77
42
  export interface BlockExpr {
78
43
  kind: "Block";
79
44
  body: ReadonlyArray<Statement>;
80
45
  loc?: SourceLocation;
81
46
  }
82
- /**
83
- * Named component argument inside a call list: `GridItem(child, span: "1/4")`.
84
- * Only valid in `(...)` argument lists, not inside `[...]` arrays.
85
- */
86
- export interface NamedArgExpr {
87
- kind: "NamedArg";
88
- name: string;
89
- value: Expression;
90
- loc?: SourceLocation;
91
- }
92
47
  export interface SourceLocation {
93
48
  line: number;
94
49
  column: number;
@@ -118,6 +73,12 @@ export interface ObjectProperty {
118
73
  value: Expression;
119
74
  /** True for `{...source}` shorthand — `key` is ignored when set. */
120
75
  spread?: boolean;
76
+ /**
77
+ * Computed property key: `{ [expr]: value }`. When set the literal
78
+ * `key` field is ignored and the key is resolved at runtime by
79
+ * evaluating this expression. Falls back to a string coercion.
80
+ */
81
+ computedKey?: Expression;
121
82
  }
122
83
  export interface ObjectExpr {
123
84
  kind: "Object";
@@ -162,11 +123,13 @@ export interface TemplateLiteralExpr {
162
123
  }
163
124
  export interface UnaryExpr {
164
125
  kind: "Unary";
165
- operator: "!" | "-";
126
+ operator: "!" | "-" | "+" | "~" | "typeof" | "void" | "delete";
166
127
  argument: Expression;
167
128
  loc?: SourceLocation;
168
129
  }
169
- export type BinaryOperator = "+" | "-" | "*" | "/" | "%" | "==" | "!=" | ">" | "<" | ">=" | "<=" | "&&" | "||"
130
+ export type BinaryOperator = "+" | "-" | "*" | "/" | "%" | "**" | "==" | "!=" | "===" | "!==" | ">" | "<" | ">=" | "<=" | "&&" | "||" | "instanceof" | "in"
131
+ /** Bitwise / shift operators — coerced through ToInt32 / ToUint32 like JS. */
132
+ | "&" | "|" | "^" | "<<" | ">>" | ">>>"
170
133
  /**
171
134
  * Nullish coalescing — returns `left` unless it is `null` or `undefined`.
172
135
  * Distinct from `||`, which also short-circuits on `0`, `""`, and `false`.
@@ -195,10 +158,7 @@ export interface CallExpr {
195
158
  /**
196
159
  * `object.method(args...)` invocation. Used for namespaced globals like
197
160
  * `storage.set(...)`, `console.log(...)`, and chained member calls on
198
- * runtime values (`$res.refetch()`). Named args inside the argument list
199
- * are collected into a single trailing options object — so
200
- * `storage.cookies.set("k", "v", expires: 1, path: "/")` resolves to
201
- * `set("k", "v", { expires: 1, path: "/" })`.
161
+ * runtime values (`$res.refetch()`).
202
162
  */
203
163
  export interface MethodCallExpr {
204
164
  kind: "MethodCall";
@@ -209,67 +169,137 @@ export interface MethodCallExpr {
209
169
  optional?: boolean;
210
170
  loc?: SourceLocation;
211
171
  }
172
+ /**
173
+ * Postfix call on an arbitrary expression — `(fn)(args)`, IIFE
174
+ * `(() => { … })()`, or `arr[i](args)`. The dedicated `Call` node is
175
+ * still used for bare-identifier callees so the evaluator can resolve
176
+ * component / action / library lookups by name.
177
+ */
178
+ export interface InvokeExpr {
179
+ kind: "Invoke";
180
+ callee: Expression;
181
+ arguments: Expression[];
182
+ /** True for `expr?.()` — short-circuits when `callee` is null/undefined. */
183
+ optional?: boolean;
184
+ loc?: SourceLocation;
185
+ }
212
186
  export interface BuiltinCallExpr {
213
187
  kind: "BuiltinCall";
214
188
  name: string;
215
189
  arguments: Expression[];
216
190
  loc?: SourceLocation;
217
191
  }
192
+ /** `new Constructor(args)` expression. */
193
+ export interface NewExpr {
194
+ kind: "New";
195
+ callee: Expression;
196
+ arguments: Expression[];
197
+ loc?: SourceLocation;
198
+ }
218
199
  export interface AssignmentStatement {
219
200
  kind: "Assignment";
220
201
  identifier: string;
221
202
  isState: boolean;
222
203
  expression: Expression;
204
+ /**
205
+ * True when prefixed with `export` (multi-file modules). Build-time only —
206
+ * the linker uses it to decide importability; the runtime ignores it.
207
+ */
208
+ exported?: boolean;
223
209
  loc?: SourceLocation;
224
210
  }
225
211
  /**
226
- * `component Name(p, q: default, slots: { footer? }) { ... }` declaration.
227
- * The body is a `BlockExpr`; the last expression is the rendered output.
212
+ * Single specifier in an `import { … } from "./mod.aktion"`. Names are stored
213
+ * WITHOUT the leading `$`; `isState` records that the surface syntax used `$`
214
+ * (so `import { $shared }` and `export $shared = …` line up by bare name).
215
+ */
216
+ export interface ImportSpecifier {
217
+ /** Name as exported by the source module (bare, no `$`). */
218
+ imported: string;
219
+ /** Local alias bound in this module (bare, no `$`). */
220
+ local: string;
221
+ /** True when the binding is a `$state` atom. */
222
+ isState?: boolean;
223
+ }
224
+ /**
225
+ * `import { A, B as C, $shared } from "./other.aktion"` — named imports for
226
+ * multi-file `.aktion` programs. Resolved + linked at BUILD TIME by the
227
+ * compiler/linker into a single merged program; the streaming runtime treats
228
+ * `Import` as a no-op (it has no filesystem to resolve against).
229
+ */
230
+ export interface ImportStatement {
231
+ kind: "Import";
232
+ specifiers: ReadonlyArray<ImportSpecifier>;
233
+ /** Raw module specifier, e.g. "./components/counter.aktion". */
234
+ source: string;
235
+ loc?: SourceLocation;
236
+ }
237
+ /**
238
+ * `function Name(p, q) { ... }` declaration. PascalCase names are treated
239
+ * as component declarations; camelCase/snake_case as action declarations.
240
+ * Components MUST have an explicit `return` statement.
228
241
  */
229
242
  export interface ComponentDeclaration {
230
243
  kind: "ComponentDeclaration";
231
244
  name: string;
232
245
  params: ReadonlyArray<DeclParam>;
233
- /** Names of the declared slots, e.g. `{ footer? }` -> `["footer"]`. */
246
+ /** Names of the declared slots (from props object convention). */
234
247
  slots: ReadonlyArray<string>;
235
248
  body: BlockExpr;
249
+ /** True when prefixed with `export` (multi-file modules; build-time only). */
250
+ exported?: boolean;
236
251
  loc?: SourceLocation;
237
252
  }
238
253
  /**
239
- * Parameter on a `component`, `action`, or `effect` declaration. Distinct
240
- * from `library/components` `ComponentParam` (the editor-level surface
241
- * projection) — kept under a different name to avoid an ambiguous re-export
242
- * from the package root.
254
+ * Parameter on a `function` declaration. Distinct from `library/components`
255
+ * `ComponentParam` (the editor-level surface projection).
243
256
  */
244
257
  export interface DeclParam {
245
258
  name: string;
246
259
  defaultValue?: Expression;
247
260
  optional?: boolean;
261
+ /** True for `...rest` parameters — must be the final param. */
262
+ rest?: boolean;
263
+ /**
264
+ * Destructuring pattern parameter — `function Foo({ name }) { … }` /
265
+ * `function Foo([a, b]) { … }`. When set, `name` is empty and the
266
+ * argument value is fanned out into the pattern's bindings.
267
+ */
268
+ pattern?: DestructuringPattern;
248
269
  }
249
270
  /**
250
- * `effect [ ...dependencies ] { body }` declaration.
271
+ * A destructuring pattern shared by `let`-declarations and
272
+ * function / lambda parameters. `kind` selects positional (array) vs.
273
+ * keyed (object) destructuring.
274
+ */
275
+ export interface DestructuringPattern {
276
+ kind: "array" | "object";
277
+ bindings: DestructuringBinding[];
278
+ }
279
+ /**
280
+ * `effect(() => { body }, [deps])` declaration.
251
281
  *
252
282
  * Effects are anonymous — the parser auto-assigns a stable name from the
253
283
  * declaration's source location so the runtime can keep track of them
254
- * across re-parses. The optional bracketed dependency list mixes state
255
- * triggers (`$name`), lifecycle / interval triggers (`on:mount`,
256
- * `on:unmount`, `on:every(N)`), and rate-limit modifiers (`debounce(N)`,
257
- * `throttle(N)`) in any order.
284
+ * across re-parses. The dependency array mixes state triggers (`$name`),
285
+ * lifecycle tokens (`"mount"`, `"unmount"`), interval tokens
286
+ * (`"every(N)"`), and rate-limit modifiers (`"debounce(N)"`,
287
+ * `"throttle(N)"`) in any order.
258
288
  *
259
- * `effect { ... }` (no brackets) and `effect [on:mount] { ... }` are
260
- * equivalent — both run the body once on mount.
289
+ * `effect(() => { ... })` (no deps) and `effect(() => { ... }, ["mount"])`
290
+ * are equivalent — both run the body once on mount.
261
291
  */
262
292
  export interface EffectDeclaration {
263
293
  kind: "EffectDeclaration";
264
294
  /** Auto-generated name (`__effect_L{line}_C{column}`) — used as a runtime key. */
265
295
  name: string;
266
296
  triggers: ReadonlyArray<EffectTrigger>;
267
- /** Optional rate-limit modifier (`debounce(N)` / `throttle(N)`). */
297
+ /** Optional rate-limit modifier (`"debounce(N)"` / `"throttle(N)"`). */
268
298
  rateLimit?: EffectRateLimit;
269
299
  body: BlockExpr;
270
300
  loc?: SourceLocation;
271
301
  }
272
- /** Trigger literal (`$state`, `on:mount`, `on:unmount`, `on:every(N)`). */
302
+ /** Trigger literal (`$state`, `"mount"`, `"unmount"`, `"every(N)"`). */
273
303
  export type EffectTrigger = {
274
304
  kind: "state";
275
305
  name: string;
@@ -280,16 +310,16 @@ export type EffectTrigger = {
280
310
  kind: "every";
281
311
  intervalMs: number;
282
312
  };
283
- /** Rate-limit modifier on an `effect` (`debounce(N)` / `throttle(N)`). */
313
+ /** Rate-limit modifier on an `effect` (`"debounce(N)"` / `"throttle(N)"`). */
284
314
  export interface EffectRateLimit {
285
315
  kind: "debounce" | "throttle";
286
316
  /** Window in milliseconds. */
287
317
  ms: number;
288
318
  }
289
319
  /**
290
- * `action Name(args) [optimistic] { body }` declaration. Actions are
291
- * explicit-call effects; their body runs whenever the action is invoked
292
- * from an event handler (`onClick: actionName`).
320
+ * `function Name(args) { body }` for actions (camelCase names).
321
+ * Actions are explicit-call effects; their body runs whenever the action
322
+ * is invoked from an event handler (`onClick: actionName`).
293
323
  */
294
324
  export interface ActionDeclaration {
295
325
  kind: "ActionDeclaration";
@@ -297,28 +327,44 @@ export interface ActionDeclaration {
297
327
  params: ReadonlyArray<DeclParam>;
298
328
  optimistic: boolean;
299
329
  body: BlockExpr;
330
+ /** True when prefixed with `export` (multi-file modules; build-time only). */
331
+ exported?: boolean;
300
332
  loc?: SourceLocation;
301
333
  }
302
- /** `emit "name" { detail }` outbound event statement. */
303
- export interface EmitStatement {
304
- kind: "Emit";
305
- eventName: string;
306
- detail: Expression;
307
- loc?: SourceLocation;
308
- }
309
- /** `cleanup(fn)` registration call — only valid inside `effect` bodies. */
310
- export interface CleanupStatement {
311
- kind: "Cleanup";
312
- callback: Expression;
334
+ /**
335
+ * `function $name(args) { body }` — a **hook** declaration (the `$` sigil
336
+ * on the function name is the marker, mirroring React's `use*` convention).
337
+ *
338
+ * Hooks are the composable unit of per-instance state. Unlike a component
339
+ * or action, a hook's body runs *inline inside the calling component's hook
340
+ * scope* — it does NOT open its own instance scope — so the `$state(...)` /
341
+ * `$memo(...)` calls inside it allocate slots on the component that invoked
342
+ * the hook (exactly how a React custom hook shares its caller's hook slots).
343
+ *
344
+ * `name` is stored WITHOUT the leading `$` (e.g. `function $useCounter()`
345
+ * becomes `{ name: "useCounter" }`); the hook is invoked as `$useCounter()`.
346
+ *
347
+ * Like React, hooks must be called unconditionally and in a stable order at
348
+ * the top level of a component / hook body — slots are matched by call
349
+ * order across renders.
350
+ */
351
+ export interface HookDeclaration {
352
+ kind: "HookDeclaration";
353
+ /** Hook name WITHOUT the leading `$` (e.g. `"useCounter"`). */
354
+ name: string;
355
+ params: ReadonlyArray<DeclParam>;
356
+ body: BlockExpr;
357
+ /** True when prefixed with `export` (multi-file modules; build-time only). */
358
+ exported?: boolean;
313
359
  loc?: SourceLocation;
314
360
  }
315
- /** `await expr` statement / expression — only valid inside `action`/`effect`. */
361
+ /** `await expr` statement / expression — only valid inside `function`/`effect`. */
316
362
  export interface AwaitStatement {
317
363
  kind: "Await";
318
364
  argument: Expression;
319
365
  loc?: SourceLocation;
320
366
  }
321
- /** `return [expr]` statement — only valid inside `action`/`effect`/`component`. */
367
+ /** `return [expr]` statement — only valid inside `function`/`effect`. */
322
368
  export interface ReturnStatement {
323
369
  kind: "Return";
324
370
  argument?: Expression;
@@ -330,15 +376,132 @@ export interface ExpressionStatement {
330
376
  expression: Expression;
331
377
  loc?: SourceLocation;
332
378
  }
333
- export type Statement = AssignmentStatement | ComponentDeclaration | EffectDeclaration | ActionDeclaration | EmitStatement | CleanupStatement | AwaitStatement | ReturnStatement | ExpressionStatement;
379
+ /** `if (cond) { … } else { … }` — JS if/else statement (body grammar). */
380
+ export interface IfStatement {
381
+ kind: "IfStatement";
382
+ test: Expression;
383
+ consequent: BlockExpr;
384
+ alternate?: IfStatement | BlockExpr;
385
+ loc?: SourceLocation;
386
+ }
387
+ /** `switch (value) { case X: …; break; default: … }` statement. */
388
+ export interface SwitchStatement {
389
+ kind: "SwitchStatement";
390
+ discriminant: Expression;
391
+ cases: ReadonlyArray<SwitchCase>;
392
+ loc?: SourceLocation;
393
+ }
394
+ /**
395
+ * `for (let x of arr) { body }` statement — iterates without producing a
396
+ * value. Use `arr.map(x => …)` to collect the bodies into an array.
397
+ */
398
+ export interface ForOfStatement {
399
+ kind: "ForOfStatement";
400
+ /** Item binding name. */
401
+ item: string;
402
+ /** Optional index binding via `for (let [item, i] of ...)`. */
403
+ index?: string;
404
+ /** Optional `{a, b, c}` destructuring — binds each named field of the row. */
405
+ destructure?: ReadonlyArray<string>;
406
+ iterable: Expression;
407
+ body: BlockExpr;
408
+ loc?: SourceLocation;
409
+ }
410
+ /**
411
+ * `for (init; test; update) { body }` — classic C-style for loop.
412
+ * `init` is an Assignment statement (`let i = 0`) or null; `test` and
413
+ * `update` are expressions (`i < 10`, `i++`).
414
+ */
415
+ export interface ForClassicStatement {
416
+ kind: "ForClassicStatement";
417
+ init?: AssignmentStatement | ExpressionStatement;
418
+ test?: Expression;
419
+ update?: Expression;
420
+ body: BlockExpr;
421
+ loc?: SourceLocation;
422
+ }
423
+ /**
424
+ * `for (let key in obj) { body }` — iterates over the enumerable string
425
+ * keys of `obj`. Use this for plain-object dictionaries; prefer the
426
+ * `for…of` form for arrays.
427
+ */
428
+ export interface ForInStatement {
429
+ kind: "ForInStatement";
430
+ item: string;
431
+ iterable: Expression;
432
+ body: BlockExpr;
433
+ loc?: SourceLocation;
434
+ }
435
+ /** `while (cond) { body }` statement. */
436
+ export interface WhileStatement {
437
+ kind: "WhileStatement";
438
+ test: Expression;
439
+ body: BlockExpr;
440
+ loc?: SourceLocation;
441
+ }
442
+ /** `do { body } while (cond)` — body always runs at least once. */
443
+ export interface DoWhileStatement {
444
+ kind: "DoWhileStatement";
445
+ test: Expression;
446
+ body: BlockExpr;
447
+ loc?: SourceLocation;
448
+ }
449
+ /** `break` — exits the nearest enclosing loop or switch case. */
450
+ export interface BreakStatement {
451
+ kind: "BreakStatement";
452
+ loc?: SourceLocation;
453
+ }
454
+ /** `continue` — skips to the next loop iteration. */
455
+ export interface ContinueStatement {
456
+ kind: "ContinueStatement";
457
+ loc?: SourceLocation;
458
+ }
459
+ /** `throw expr` — throws the given value. */
460
+ export interface ThrowStatement {
461
+ kind: "ThrowStatement";
462
+ argument: Expression;
463
+ loc?: SourceLocation;
464
+ }
465
+ /**
466
+ * Single binding produced by an `Array` / `Object` destructuring pattern.
467
+ * Nested patterns are intentionally not modelled — authors with more
468
+ * complex needs can destructure in two steps. `defaultValue` is JS's
469
+ * `let {a = 1} = obj` / `let [a = 1] = arr` fallback.
470
+ */
471
+ export interface DestructuringBinding {
472
+ /** Variable name introduced by this slot. */
473
+ name: string;
474
+ /** Optional renamed source key (object pattern only): `let {a: b} = …`. */
475
+ sourceKey?: string;
476
+ /** `let [a, ...rest] = …` / `let {a, ...rest} = …`. */
477
+ rest?: boolean;
478
+ defaultValue?: Expression;
479
+ }
480
+ /** `let [a, b, ...rest] = …` / `let {x, y: alias, z = 0, ...rest} = …`. */
481
+ export interface DestructureStatement {
482
+ kind: "DestructureStatement";
483
+ /** `"array"` for positional, `"object"` for keyed destructuring. */
484
+ patternKind: "array" | "object";
485
+ bindings: DestructuringBinding[];
486
+ expression: Expression;
487
+ loc?: SourceLocation;
488
+ }
489
+ /** `try { … } catch (e) { … } finally { … }` statement. */
490
+ export interface TryStatement {
491
+ kind: "TryStatement";
492
+ block: BlockExpr;
493
+ catchParam?: string;
494
+ catchBlock?: BlockExpr;
495
+ finallyBlock?: BlockExpr;
496
+ loc?: SourceLocation;
497
+ }
498
+ export type Statement = AssignmentStatement | ImportStatement | ComponentDeclaration | EffectDeclaration | ActionDeclaration | HookDeclaration | AwaitStatement | ReturnStatement | ExpressionStatement | IfStatement | SwitchStatement | ForOfStatement | ForClassicStatement | ForInStatement | WhileStatement | DoWhileStatement | DestructureStatement | BreakStatement | ContinueStatement | ThrowStatement | TryStatement;
334
499
  export interface Program {
335
500
  statements: Statement[];
336
501
  errors: ParseError[];
337
502
  /**
338
- * Non-fatal diagnostics surfaced by schema validation (§15). The
339
- * program still runs — these are advisory hints for authors who chose
340
- * a token outside the closed enum, supplied an unknown named arg, or
341
- * tripped some other "this will not look right" lint.
503
+ * Non-fatal diagnostics surfaced by schema validation. The program
504
+ * still runs — these are advisory hints.
342
505
  */
343
506
  warnings?: ParseError[];
344
507
  }
@@ -0,0 +1,10 @@
1
+ /**
2
+ * `aktion-runtime/vite` — the Vite/Rollup plugin entry.
3
+ *
4
+ * Default export is the plugin factory, so consumers can write either:
5
+ *
6
+ * import aktion from "aktion-runtime/vite";
7
+ * import { aktionPlugin } from "aktion-runtime/vite";
8
+ */
9
+ export { aktionPlugin, aktionPlugin as default } from './vite.js';
10
+ export type { AktionPluginOptions } from './vite.js';
@@ -0,0 +1,21 @@
1
+ import { Plugin } from 'vite';
2
+ import { ComponentLibrary } from '../library/types.js';
3
+ export interface AktionPluginOptions {
4
+ /** Library to validate against at build time. Default: the default library. */
5
+ library?: ComponentLibrary;
6
+ /** Treat schema violations as fatal build errors vs. warnings. Default: true. */
7
+ schemaErrorsFatal?: boolean;
8
+ /** Warn when a program has no `aktion = …` entry binding. Default: true. */
9
+ requireEntry?: boolean;
10
+ /** Specifier the emitted module imports the runtime helper from. Default: `"aktion-runtime"`. */
11
+ runtimeModuleId?: string;
12
+ }
13
+ /**
14
+ * The Aktion Vite/Rollup plugin. Add it to `plugins` in `vite.config.ts`:
15
+ *
16
+ * import aktion from "aktion-runtime/vite";
17
+ * export default { plugins: [aktion()] };
18
+ */
19
+ export declare function aktionPlugin(options?: AktionPluginOptions): Plugin;
20
+ /** True for `*.aktion` ids (query/hash stripped). */
21
+ export declare function isAktionId(id: string): boolean;
@@ -2,31 +2,20 @@ import { ComponentLibrary, ComponentSpec } from '../library/types.js';
2
2
  export interface ToolSpec {
3
3
  name: string;
4
4
  description: string;
5
- /** Example argument shape the LLM should call with. */
6
5
  argsExample?: Record<string, unknown>;
7
- /** Whether this endpoint is read-only or mutating. Influences method hint. */
8
6
  kind?: "Query" | "Mutation";
9
7
  }
10
8
  export type PromptMode = "full" | "chat";
11
9
  export interface PromptOptions {
12
10
  mode?: PromptMode;
13
- /** Replace the default opening sentence describing the assistant's role. */
14
11
  preamble?: string;
15
- /** Bullets appended under an `## Additional rules` section near the end. */
16
12
  additionalRules?: ReadonlyArray<string>;
17
- /** Worked-example snippets shown under `## Examples`. Defaults to a curated set. */
18
13
  examples?: ReadonlyArray<string>;
19
- /** Host-provided endpoint catalogue. Surfaced under `## Available endpoints`. */
20
14
  tools?: ReadonlyArray<ToolSpec>;
21
- /** Endpoint usage examples. Surfaced under `## Endpoint examples`. */
22
15
  toolExamples?: ReadonlyArray<string>;
23
- /** Force-include the HTTP/tool-calling teaching sections in `full` mode. */
24
16
  toolCalls?: boolean;
25
- /** Force-include the reactive-state + builtins sections in `full` mode. */
26
17
  bindings?: boolean;
27
- /** Permit fenced ```aktion blocks inside markdown prose (full mode). */
28
18
  inlineMode?: boolean;
29
- /** Tell the LLM to emit only changed statements (full mode). */
30
19
  editMode?: boolean;
31
20
  }
32
21
  export declare function generatePrompt(library: ComponentLibrary, options?: PromptOptions): string;