aktion-runtime 0.5.2 → 0.5.3

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 (35) hide show
  1. package/README.md +654 -376
  2. package/dist/aktion.iife.js +798 -790
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +10046 -8011
  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/system_prompt.txt +595 -829
  9. package/dist/system_prompt_chat.txt +98 -263
  10. package/dist/types/element.d.ts +46 -26
  11. package/dist/types/language/grammar.d.ts +25 -9
  12. package/dist/types/language/index.d.ts +8 -6
  13. package/dist/types/library/components/content.d.ts +0 -1
  14. package/dist/types/library/components/escape-hatch.d.ts +3 -0
  15. package/dist/types/library/components/layout.d.ts +3 -0
  16. package/dist/types/library/components/wrappers.d.ts +12 -0
  17. package/dist/types/library/utils.d.ts +42 -0
  18. package/dist/types/parser/frontier.d.ts +3 -3
  19. package/dist/types/parser/lexer.d.ts +7 -17
  20. package/dist/types/parser/types.d.ts +239 -113
  21. package/dist/types/prompt/generator.d.ts +0 -11
  22. package/dist/types/renderer/renderer.d.ts +53 -4
  23. package/dist/types/runtime/builtins.d.ts +10 -6
  24. package/dist/types/runtime/effects.d.ts +3 -28
  25. package/dist/types/runtime/evaluator.d.ts +333 -24
  26. package/dist/types/runtime/http.d.ts +35 -30
  27. package/dist/types/runtime/i18n.d.ts +23 -32
  28. package/dist/types/runtime/router.d.ts +5 -6
  29. package/dist/types/runtime/state.d.ts +77 -33
  30. package/dist/types/runtime/util.d.ts +88 -0
  31. package/dist/types/theme/styles.d.ts +1 -1
  32. package/dist/types/tooling/delta.d.ts +1 -1
  33. package/dist/types/tooling/inspector.d.ts +1 -1
  34. package/package.json +2 -2
  35. 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,12 +169,33 @@ 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;
@@ -223,53 +204,69 @@ export interface AssignmentStatement {
223
204
  loc?: SourceLocation;
224
205
  }
225
206
  /**
226
- * `component Name(p, q: default, slots: { footer? }) { ... }` declaration.
227
- * The body is a `BlockExpr`; the last expression is the rendered output.
207
+ * `function Name(p, q) { ... }` declaration. PascalCase names are treated
208
+ * as component declarations; camelCase/snake_case as action declarations.
209
+ * Components MUST have an explicit `return` statement.
228
210
  */
229
211
  export interface ComponentDeclaration {
230
212
  kind: "ComponentDeclaration";
231
213
  name: string;
232
214
  params: ReadonlyArray<DeclParam>;
233
- /** Names of the declared slots, e.g. `{ footer? }` -> `["footer"]`. */
215
+ /** Names of the declared slots (from props object convention). */
234
216
  slots: ReadonlyArray<string>;
235
217
  body: BlockExpr;
236
218
  loc?: SourceLocation;
237
219
  }
238
220
  /**
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.
221
+ * Parameter on a `function` declaration. Distinct from `library/components`
222
+ * `ComponentParam` (the editor-level surface projection).
243
223
  */
244
224
  export interface DeclParam {
245
225
  name: string;
246
226
  defaultValue?: Expression;
247
227
  optional?: boolean;
228
+ /** True for `...rest` parameters — must be the final param. */
229
+ rest?: boolean;
230
+ /**
231
+ * Destructuring pattern parameter — `function Foo({ name }) { … }` /
232
+ * `function Foo([a, b]) { … }`. When set, `name` is empty and the
233
+ * argument value is fanned out into the pattern's bindings.
234
+ */
235
+ pattern?: DestructuringPattern;
248
236
  }
249
237
  /**
250
- * `effect [ ...dependencies ] { body }` declaration.
238
+ * A destructuring pattern shared by `let`-declarations and
239
+ * function / lambda parameters. `kind` selects positional (array) vs.
240
+ * keyed (object) destructuring.
241
+ */
242
+ export interface DestructuringPattern {
243
+ kind: "array" | "object";
244
+ bindings: DestructuringBinding[];
245
+ }
246
+ /**
247
+ * `effect(() => { body }, [deps])` declaration.
251
248
  *
252
249
  * Effects are anonymous — the parser auto-assigns a stable name from the
253
250
  * 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.
251
+ * across re-parses. The dependency array mixes state triggers (`$name`),
252
+ * lifecycle tokens (`"mount"`, `"unmount"`), interval tokens
253
+ * (`"every(N)"`), and rate-limit modifiers (`"debounce(N)"`,
254
+ * `"throttle(N)"`) in any order.
258
255
  *
259
- * `effect { ... }` (no brackets) and `effect [on:mount] { ... }` are
260
- * equivalent — both run the body once on mount.
256
+ * `effect(() => { ... })` (no deps) and `effect(() => { ... }, ["mount"])`
257
+ * are equivalent — both run the body once on mount.
261
258
  */
262
259
  export interface EffectDeclaration {
263
260
  kind: "EffectDeclaration";
264
261
  /** Auto-generated name (`__effect_L{line}_C{column}`) — used as a runtime key. */
265
262
  name: string;
266
263
  triggers: ReadonlyArray<EffectTrigger>;
267
- /** Optional rate-limit modifier (`debounce(N)` / `throttle(N)`). */
264
+ /** Optional rate-limit modifier (`"debounce(N)"` / `"throttle(N)"`). */
268
265
  rateLimit?: EffectRateLimit;
269
266
  body: BlockExpr;
270
267
  loc?: SourceLocation;
271
268
  }
272
- /** Trigger literal (`$state`, `on:mount`, `on:unmount`, `on:every(N)`). */
269
+ /** Trigger literal (`$state`, `"mount"`, `"unmount"`, `"every(N)"`). */
273
270
  export type EffectTrigger = {
274
271
  kind: "state";
275
272
  name: string;
@@ -280,16 +277,16 @@ export type EffectTrigger = {
280
277
  kind: "every";
281
278
  intervalMs: number;
282
279
  };
283
- /** Rate-limit modifier on an `effect` (`debounce(N)` / `throttle(N)`). */
280
+ /** Rate-limit modifier on an `effect` (`"debounce(N)"` / `"throttle(N)"`). */
284
281
  export interface EffectRateLimit {
285
282
  kind: "debounce" | "throttle";
286
283
  /** Window in milliseconds. */
287
284
  ms: number;
288
285
  }
289
286
  /**
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`).
287
+ * `function Name(args) { body }` for actions (camelCase names).
288
+ * Actions are explicit-call effects; their body runs whenever the action
289
+ * is invoked from an event handler (`onClick: actionName`).
293
290
  */
294
291
  export interface ActionDeclaration {
295
292
  kind: "ActionDeclaration";
@@ -299,26 +296,38 @@ export interface ActionDeclaration {
299
296
  body: BlockExpr;
300
297
  loc?: SourceLocation;
301
298
  }
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;
299
+ /**
300
+ * `function $name(args) { body }` — a **hook** declaration (the `$` sigil
301
+ * on the function name is the marker, mirroring React's `use*` convention).
302
+ *
303
+ * Hooks are the composable unit of per-instance state. Unlike a component
304
+ * or action, a hook's body runs *inline inside the calling component's hook
305
+ * scope* — it does NOT open its own instance scope — so the `$state(...)` /
306
+ * `$memo(...)` calls inside it allocate slots on the component that invoked
307
+ * the hook (exactly how a React custom hook shares its caller's hook slots).
308
+ *
309
+ * `name` is stored WITHOUT the leading `$` (e.g. `function $useCounter()`
310
+ * becomes `{ name: "useCounter" }`); the hook is invoked as `$useCounter()`.
311
+ *
312
+ * Like React, hooks must be called unconditionally and in a stable order at
313
+ * the top level of a component / hook body — slots are matched by call
314
+ * order across renders.
315
+ */
316
+ export interface HookDeclaration {
317
+ kind: "HookDeclaration";
318
+ /** Hook name WITHOUT the leading `$` (e.g. `"useCounter"`). */
319
+ name: string;
320
+ params: ReadonlyArray<DeclParam>;
321
+ body: BlockExpr;
313
322
  loc?: SourceLocation;
314
323
  }
315
- /** `await expr` statement / expression — only valid inside `action`/`effect`. */
324
+ /** `await expr` statement / expression — only valid inside `function`/`effect`. */
316
325
  export interface AwaitStatement {
317
326
  kind: "Await";
318
327
  argument: Expression;
319
328
  loc?: SourceLocation;
320
329
  }
321
- /** `return [expr]` statement — only valid inside `action`/`effect`/`component`. */
330
+ /** `return [expr]` statement — only valid inside `function`/`effect`. */
322
331
  export interface ReturnStatement {
323
332
  kind: "Return";
324
333
  argument?: Expression;
@@ -330,15 +339,132 @@ export interface ExpressionStatement {
330
339
  expression: Expression;
331
340
  loc?: SourceLocation;
332
341
  }
333
- export type Statement = AssignmentStatement | ComponentDeclaration | EffectDeclaration | ActionDeclaration | EmitStatement | CleanupStatement | AwaitStatement | ReturnStatement | ExpressionStatement;
342
+ /** `if (cond) { … } else { … }` — JS if/else statement (body grammar). */
343
+ export interface IfStatement {
344
+ kind: "IfStatement";
345
+ test: Expression;
346
+ consequent: BlockExpr;
347
+ alternate?: IfStatement | BlockExpr;
348
+ loc?: SourceLocation;
349
+ }
350
+ /** `switch (value) { case X: …; break; default: … }` statement. */
351
+ export interface SwitchStatement {
352
+ kind: "SwitchStatement";
353
+ discriminant: Expression;
354
+ cases: ReadonlyArray<SwitchCase>;
355
+ loc?: SourceLocation;
356
+ }
357
+ /**
358
+ * `for (let x of arr) { body }` statement — iterates without producing a
359
+ * value. Use `arr.map(x => …)` to collect the bodies into an array.
360
+ */
361
+ export interface ForOfStatement {
362
+ kind: "ForOfStatement";
363
+ /** Item binding name. */
364
+ item: string;
365
+ /** Optional index binding via `for (let [item, i] of ...)`. */
366
+ index?: string;
367
+ /** Optional `{a, b, c}` destructuring — binds each named field of the row. */
368
+ destructure?: ReadonlyArray<string>;
369
+ iterable: Expression;
370
+ body: BlockExpr;
371
+ loc?: SourceLocation;
372
+ }
373
+ /**
374
+ * `for (init; test; update) { body }` — classic C-style for loop.
375
+ * `init` is an Assignment statement (`let i = 0`) or null; `test` and
376
+ * `update` are expressions (`i < 10`, `i++`).
377
+ */
378
+ export interface ForClassicStatement {
379
+ kind: "ForClassicStatement";
380
+ init?: AssignmentStatement | ExpressionStatement;
381
+ test?: Expression;
382
+ update?: Expression;
383
+ body: BlockExpr;
384
+ loc?: SourceLocation;
385
+ }
386
+ /**
387
+ * `for (let key in obj) { body }` — iterates over the enumerable string
388
+ * keys of `obj`. Use this for plain-object dictionaries; prefer the
389
+ * `for…of` form for arrays.
390
+ */
391
+ export interface ForInStatement {
392
+ kind: "ForInStatement";
393
+ item: string;
394
+ iterable: Expression;
395
+ body: BlockExpr;
396
+ loc?: SourceLocation;
397
+ }
398
+ /** `while (cond) { body }` statement. */
399
+ export interface WhileStatement {
400
+ kind: "WhileStatement";
401
+ test: Expression;
402
+ body: BlockExpr;
403
+ loc?: SourceLocation;
404
+ }
405
+ /** `do { body } while (cond)` — body always runs at least once. */
406
+ export interface DoWhileStatement {
407
+ kind: "DoWhileStatement";
408
+ test: Expression;
409
+ body: BlockExpr;
410
+ loc?: SourceLocation;
411
+ }
412
+ /** `break` — exits the nearest enclosing loop or switch case. */
413
+ export interface BreakStatement {
414
+ kind: "BreakStatement";
415
+ loc?: SourceLocation;
416
+ }
417
+ /** `continue` — skips to the next loop iteration. */
418
+ export interface ContinueStatement {
419
+ kind: "ContinueStatement";
420
+ loc?: SourceLocation;
421
+ }
422
+ /** `throw expr` — throws the given value. */
423
+ export interface ThrowStatement {
424
+ kind: "ThrowStatement";
425
+ argument: Expression;
426
+ loc?: SourceLocation;
427
+ }
428
+ /**
429
+ * Single binding produced by an `Array` / `Object` destructuring pattern.
430
+ * Nested patterns are intentionally not modelled — authors with more
431
+ * complex needs can destructure in two steps. `defaultValue` is JS's
432
+ * `let {a = 1} = obj` / `let [a = 1] = arr` fallback.
433
+ */
434
+ export interface DestructuringBinding {
435
+ /** Variable name introduced by this slot. */
436
+ name: string;
437
+ /** Optional renamed source key (object pattern only): `let {a: b} = …`. */
438
+ sourceKey?: string;
439
+ /** `let [a, ...rest] = …` / `let {a, ...rest} = …`. */
440
+ rest?: boolean;
441
+ defaultValue?: Expression;
442
+ }
443
+ /** `let [a, b, ...rest] = …` / `let {x, y: alias, z = 0, ...rest} = …`. */
444
+ export interface DestructureStatement {
445
+ kind: "DestructureStatement";
446
+ /** `"array"` for positional, `"object"` for keyed destructuring. */
447
+ patternKind: "array" | "object";
448
+ bindings: DestructuringBinding[];
449
+ expression: Expression;
450
+ loc?: SourceLocation;
451
+ }
452
+ /** `try { … } catch (e) { … } finally { … }` statement. */
453
+ export interface TryStatement {
454
+ kind: "TryStatement";
455
+ block: BlockExpr;
456
+ catchParam?: string;
457
+ catchBlock?: BlockExpr;
458
+ finallyBlock?: BlockExpr;
459
+ loc?: SourceLocation;
460
+ }
461
+ export type Statement = AssignmentStatement | ComponentDeclaration | EffectDeclaration | ActionDeclaration | HookDeclaration | AwaitStatement | ReturnStatement | ExpressionStatement | IfStatement | SwitchStatement | ForOfStatement | ForClassicStatement | ForInStatement | WhileStatement | DoWhileStatement | DestructureStatement | BreakStatement | ContinueStatement | ThrowStatement | TryStatement;
334
462
  export interface Program {
335
463
  statements: Statement[];
336
464
  errors: ParseError[];
337
465
  /**
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.
466
+ * Non-fatal diagnostics surfaced by schema validation. The program
467
+ * still runs — these are advisory hints.
342
468
  */
343
469
  warnings?: ParseError[];
344
470
  }
@@ -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;
@@ -19,7 +19,7 @@ export interface RenderOptions {
19
19
  */
20
20
  evaluationContext?: () => EvaluationContext;
21
21
  /**
22
- * Mount `effect [ ...deps ] { … }` declarations discovered inside a
22
+ * Mount `effect(() => { … }, [deps])` declarations discovered inside a
23
23
  * `component { … }` body. Called by the renderer after every render of
24
24
  * the instance; the implementation is expected to be idempotent so
25
25
  * re-renders are no-ops once the effects are mounted. The host wires
@@ -37,6 +37,14 @@ export interface RenderOptions {
37
37
  * (between two `beginRender`/`endRender` passes).
38
38
  */
39
39
  unmountInstanceEffects?: (instanceKey: string) => void;
40
+ /**
41
+ * Drop the per-instance hook cells (`$state` / `$memo`) held under
42
+ * `instanceKey`. Invoked when a component that used hooks disappears from
43
+ * the render tree, giving React-like reset-on-unmount: a future remount
44
+ * starts its `$state` from the initial value again. The host wires this to
45
+ * `clearInstanceHooks(ctx, key)`.
46
+ */
47
+ unmountInstanceHooks?: (instanceKey: string) => void;
40
48
  }
41
49
  export declare class Renderer {
42
50
  private options;
@@ -62,6 +70,30 @@ export declare class Renderer {
62
70
  * GC even when an instance never registered `useInstanceState`.
63
71
  */
64
72
  private readonly instancesWithEffects;
73
+ /**
74
+ * User-declared component instances that currently hold per-instance hook
75
+ * cells (`$state` / `$memo`). Tracked so the renderer can fire
76
+ * `unmountInstanceHooks` when the instance leaves the tree.
77
+ */
78
+ private readonly instancesWithHooks;
79
+ /**
80
+ * Per-instance render memo (React.memo / Solid-style granularity). Keyed by
81
+ * instance path; holds the args + the `$state` paths the body read + the
82
+ * body's last return value. On a re-render where the change paths are fully
83
+ * known, an instance whose args are unchanged AND whose read-paths don't
84
+ * overlap the change set reuses its cached value — its body (and its
85
+ * `console.log`s / work) is skipped. Reusing the *value* (not the DOM) means
86
+ * children are still visited and re-checked against their own memo, so a
87
+ * descendant that reads a changed path still re-renders. GC'd in `endRender`.
88
+ */
89
+ private readonly memoCache;
90
+ /**
91
+ * Paths changed since the last render (set by the host before `render`).
92
+ * Drives memoization. `null`/empty + `memoEnabled=false` ⇒ full re-render.
93
+ */
94
+ private changedPaths;
95
+ /** Whether memoization may apply this render (false on mount / replan / notify). */
96
+ private memoEnabled;
65
97
  constructor(options: RenderOptions);
66
98
  /**
67
99
  * Swap the component library backing this renderer. Used when the host
@@ -75,18 +107,35 @@ export declare class Renderer {
75
107
  * is `clear()`ed so a fresh program starts with a clean slate.
76
108
  */
77
109
  reset(): void;
78
- /** Begin a fresh render pass; tracks which instances are still alive. */
79
- beginRender(): void;
110
+ /**
111
+ * Begin a fresh render pass; tracks which instances are still alive.
112
+ *
113
+ * `changedPaths` is the set of `$state` paths that changed since the last
114
+ * render and `memoize` says whether per-component memoization may apply
115
+ * (false on first paint, replan, or a `notify()`-driven render where the
116
+ * change set isn't fully known — those re-render everything).
117
+ */
118
+ beginRender(opts?: {
119
+ changedPaths?: ReadonlySet<string>;
120
+ memoize?: boolean;
121
+ }): void;
80
122
  /**
81
123
  * End the current render pass. Drops instance state for components that
82
124
  * disappeared from the tree so the map doesn't grow unbounded.
83
125
  */
84
126
  endRender(): void;
85
127
  private safeDispose;
128
+ /**
129
+ * Apply a state write addressed by either a plain atom name
130
+ * (`$count` → `"count"`) or a dotted path (`$form.email` →
131
+ * `"form.email"`). Dotted writes go through `state.setPath` so the
132
+ * root object is reconstructed immutably and subscribers wake up.
133
+ */
134
+ private writeState;
86
135
  render(value: unknown): Node;
87
136
  private renderAt;
88
137
  /**
89
- * Expand a user-declared `component Foo(p) { ... }` invocation. Each
138
+ * Expand a user-declared `function Foo(p) { return ... }` invocation. Each
90
139
  * instance gets a stable instance key derived from its render path (or
91
140
  * the caller's explicit `key:` override); the evaluator then evaluates
92
141
  * the component's body with a fresh per-instance state-alias scope so
@@ -1,13 +1,17 @@
1
1
  /**
2
- * Built-in `@Name(...)` functions for Aktion.
2
+ * Theme marker for the runtime.
3
3
  *
4
- * These are pure data transformations. The legacy action-step builtins
5
- * (`@Run`, `@Set`, `@Reset`, `@ToAssistant`, `@OpenUrl`, `@Navigate`,
6
- * `@Js`) and the `@Const` memo helper were removed. Use `action <Name>() {
7
- * … }` declarations + lambda handlers (`onClick: save`) instead, and just
8
- * `$name = expression` for plain reactive bindings.
4
+ * The former `@`-builtin catalog (`@Count`, `@Filter`, `@Format`, …)
5
+ * has been removed. Programs now reach for equivalent native
6
+ * JavaScript or the `Util` namespace (see `./util.ts`).
9
7
  */
10
8
  export type BuiltinFn = (args: unknown[]) => unknown;
9
+ /**
10
+ * Empty registry kept as a structural placeholder so the parser's
11
+ * synthetic `BuiltinCall` nodes (`__rui_assign__`, `__rui_postfix__`,
12
+ * `__rui_prefix__`, `__rui_await__`) flow through the evaluator without
13
+ * a surprise lookup.
14
+ */
11
15
  export declare const dataBuiltins: Record<string, BuiltinFn>;
12
16
  /**
13
17
  * Marker emitted by the `Theme({...})` construct. Carries an arbitrary token