aktion-runtime 0.5.1 → 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 -373
  2. package/dist/aktion.iife.js +798 -790
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +10059 -7997
  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 +60 -7
  23. package/dist/types/runtime/builtins.d.ts +10 -6
  24. package/dist/types/runtime/effects.d.ts +5 -30
  25. package/dist/types/runtime/evaluator.d.ts +356 -25
  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
@@ -11,16 +11,8 @@ export declare class AktionElement extends HTMLElement {
11
11
  private readonly router;
12
12
  private library;
13
13
  private readonly http;
14
- private readonly i18n;
15
14
  private readonly effectRunner;
16
15
  private readonly actionDeclRunner;
17
- /**
18
- * Host-registered async tools, exposed to `js{}` blocks (effects + action
19
- * bodies) as `ctx.tools.<name>(args)`. The runtime never inspects the
20
- * registry — it just forwards calls — so each handler is responsible for
21
- * its own validation, auth, and error handling.
22
- */
23
- private readonly tools;
24
16
  private renderer;
25
17
  private context;
26
18
  private root;
@@ -30,6 +22,29 @@ export declare class AktionElement extends HTMLElement {
30
22
  private renderScheduled;
31
23
  /** True when the program text changed and the runtime needs a re-plan. */
32
24
  private programDirty;
25
+ /**
26
+ * Set of state paths the most recent render actually read (e.g. `"user.name"`,
27
+ * `"cart"`). The state subscription uses it to gate re-renders: a reactive
28
+ * write only re-renders when its changed path overlaps something the UI
29
+ * read (fine-grained reactivity). `null` means "no baseline yet" — the next
30
+ * change always renders (first paint, post-replan). Explicit `notify()`
31
+ * signals (async/HTTP/timers/effects/hooks) bypass this gate entirely.
32
+ */
33
+ private lastRenderDeps;
34
+ /**
35
+ * Reactive paths changed since the last render, accumulated across flushes
36
+ * (and across gated renders). Drives per-component memoization: the renderer
37
+ * skips a component whose args are unchanged and whose read-paths don't
38
+ * overlap this set.
39
+ */
40
+ private pendingChangedPaths;
41
+ /**
42
+ * Set when a re-render was requested via `notify()` (async resolution,
43
+ * timer, HTTP, hook, effect) rather than a tracked `$state` write. The
44
+ * change set isn't fully known in that case, so the next render disables
45
+ * memoization and re-renders everything.
46
+ */
47
+ private forceFullRender;
33
48
  private parseErrors;
34
49
  /**
35
50
  * Token keys most recently applied by an in-script `Theme({...})`
@@ -112,12 +127,6 @@ export declare class AktionElement extends HTMLElement {
112
127
  getSystemPrompt(options?: PromptOptions): string;
113
128
  /** Programmatic navigation API. */
114
129
  navigate(path: string): void;
115
- /**
116
- * Register host-supplied async tools exposed to `js{}` blocks as
117
- * `ctx.tools.<name>(args)`. Replaces any previously-registered tools
118
- * with the same name.
119
- */
120
- setTools(tools: Record<string, (...args: unknown[]) => unknown>): void;
121
130
  /** Current route path (`/`, `/about`, …). */
122
131
  get route(): string;
123
132
  clear(): void;
@@ -127,31 +136,24 @@ export declare class AktionElement extends HTMLElement {
127
136
  set streaming(value: boolean);
128
137
  get showErrors(): boolean;
129
138
  set showErrors(value: boolean);
139
+ /** Dispatch a custom event from `emit()` calls in effect/action bodies. */
140
+ private emitCustomEvent;
130
141
  private buildInlineStyle;
131
142
  /**
132
- * Start the router so the hash listener is attached and `_route_` is
143
+ * Start the router so the hash listener is attached and `route` is
133
144
  * seeded with the current URL. Idempotent — safe to call from
134
145
  * `connectedCallback`.
135
146
  */
136
147
  private startRouter;
137
148
  /**
138
- * Write `_route_` only when its content actually changed. Avoids
149
+ * Write `route` only when its content actually changed. Avoids
139
150
  * triggering a redundant render-after-replan cascade — see
140
151
  * `routesEqual` for the structural comparison.
141
152
  */
142
153
  private writeRouteState;
143
- /**
144
- * Wire `$$variable` declarations to a `localStorage`-backed adapter.
145
- * Persistence is namespaced by the element's `id` (falling back to the
146
- * tag name when no id is set) so two `<aktion-app>` elements on
147
- * the same page don't collide. SSR / sandboxed contexts without storage
148
- * silently degrade to in-memory only — `$$variable` still works, just
149
- * without survival across reloads.
150
- */
151
- private attachPersistenceAdapter;
152
154
  /**
153
155
  * React to any path change: write the new value into the route slot (so
154
- * `_route_` reads re-evaluate), schedule a re-render, and bubble a
156
+ * `route` reads re-evaluate), schedule a re-render, and bubble a
155
157
  * `route-change` event so host pages can sync analytics or sidebars.
156
158
  */
157
159
  private handleRouteChange;
@@ -166,7 +168,25 @@ export declare class AktionElement extends HTMLElement {
166
168
  */
167
169
  private applyScriptThemeOverrides;
168
170
  private scheduleRender;
171
+ /**
172
+ * Request a full (non-memoized) re-render. Used for changes the path
173
+ * tracker can't see — async / HTTP resolutions, timers, hook setters,
174
+ * effect bodies, custom events. The whole tree re-evaluates next tick.
175
+ */
176
+ private requestFullRender;
169
177
  private renderNow;
178
+ /** Whether the "state write during render" warning has already fired. */
179
+ private warnedStateWriteDuringRender;
180
+ private warnStateWriteDuringRender;
181
+ /**
182
+ * Surface a runtime-budget abort the same way parse errors are
183
+ * surfaced: append it to `parseErrors`, refresh the error banner,
184
+ * and bubble an `error` event so the host page (or playground) can
185
+ * react. The rendered DOM is intentionally left untouched — the
186
+ * partially-rendered output from a previous tick is more useful to
187
+ * the user than a flash of blank UI.
188
+ */
189
+ private handleRuntimeBudgetError;
170
190
  private captureFocus;
171
191
  private restoreFocus;
172
192
  private replan;
@@ -11,11 +11,13 @@
11
11
  * Token kinds are reported as semantic strings. Consumers map them to their
12
12
  * own highlight tags (CodeMirror's `tags`, Monaco's `TokenType`, etc.).
13
13
  */
14
- export type GrammarTokenKind = "comment" | "string" | "number" | "atom" | "builtin" | "state" | "component" | "identifier" | "operator" | "punctuation" | "loopvar" | "property";
14
+ export type GrammarTokenKind = "comment" | "string" | "number" | "atom" | "keyword" | "state" | "component" | "identifier" | "operator" | "punctuation" | "loopvar" | "property";
15
15
  export interface GrammarSpec {
16
16
  name: "aktion";
17
- /** No keywords reserved beyond literal atoms. */
17
+ /** Literal atoms (true / false / null). */
18
18
  atoms: readonly string[];
19
+ /** Reserved keywords that drive control flow and declarations. */
20
+ keywords: readonly string[];
19
21
  /** Operators (longest-match first when tokenising). */
20
22
  operators: readonly string[];
21
23
  /** Two-character operators that must be matched before single chars. */
@@ -28,12 +30,6 @@ export interface GrammarSpec {
28
30
  comments: {
29
31
  /** Primary line-comment introducer (used by editors for Ctrl+/ toggle). */
30
32
  line: string;
31
- /**
32
- * Additional line-comment introducers. Tokenizers strip these the same
33
- * way as `line`; editors that expose a single comment-toggle keystroke
34
- * should still use `line` as the canonical form.
35
- */
36
- extraLine: readonly string[];
37
33
  blockStart: string;
38
34
  blockEnd: string;
39
35
  };
@@ -49,11 +45,31 @@ export interface GrammarSpec {
49
45
  };
50
46
  /** Sigils that mark non-identifier categories. */
51
47
  sigils: {
52
- builtin: string;
53
48
  state: string;
54
49
  };
55
50
  }
56
51
  export declare const grammarSpec: GrammarSpec;
52
+ /**
53
+ * Documentation for a reserved keyword — surfaced by the language
54
+ * service hover provider and the playground keyword-popup. Each entry
55
+ * has a one-line `summary`, a `syntax` skeleton, and a runnable
56
+ * `example` snippet.
57
+ */
58
+ export interface KeywordDoc {
59
+ /** One-line description of what the keyword does. */
60
+ summary: string;
61
+ /** Syntax skeleton, e.g. `if (condition) { … } else { … }`. */
62
+ syntax: string;
63
+ /** Short usage example. */
64
+ example: string;
65
+ }
66
+ /**
67
+ * Canonical explanations for every reserved word / top-level handle in
68
+ * `grammarSpec.keywords`. Single source of truth shared by the language
69
+ * service (`getHoverInfo`) and the playground keyword popups so the two
70
+ * never drift. Keep this in sync with `grammarSpec.keywords`.
71
+ */
72
+ export declare const keywordDocs: Record<string, KeywordDoc>;
57
73
  /**
58
74
  * Mutable state carried by the stream tokenizer between calls. We track the
59
75
  * unclosed multi-line constructs (backtick strings, block comments).
@@ -1,10 +1,9 @@
1
1
  import { ComponentLibrary } from '../library/types.js';
2
- import { grammarSpec, createStreamTokenizer, defaultTagMap, GrammarSpec, GrammarTokenKind, StreamTokenizer } from './grammar.js';
2
+ import { grammarSpec, createStreamTokenizer, defaultTagMap, keywordDocs, GrammarSpec, GrammarTokenKind, StreamTokenizer, KeywordDoc } from './grammar.js';
3
3
  import { getComponentCatalog, indexCatalog, ComponentEntry, ComponentParam } from './components.js';
4
- import { getBuiltinCatalog, indexBuiltins, BuiltinEntry, BuiltinParam } from './builtins.js';
5
4
  import { getSnippets, SnippetEntry } from './snippets.js';
6
- export type { GrammarSpec, GrammarTokenKind, StreamTokenizer, ComponentEntry, ComponentParam, BuiltinEntry, BuiltinParam, SnippetEntry, };
7
- export { grammarSpec, createStreamTokenizer, defaultTagMap, getComponentCatalog, indexCatalog, getBuiltinCatalog, indexBuiltins, getSnippets, };
5
+ export type { GrammarSpec, GrammarTokenKind, StreamTokenizer, KeywordDoc, ComponentEntry, ComponentParam, SnippetEntry, };
6
+ export { grammarSpec, createStreamTokenizer, defaultTagMap, keywordDocs, getComponentCatalog, indexCatalog, getSnippets, };
8
7
  /**
9
8
  * Diagnostic severity buckets that map to common editor lint levels.
10
9
  * Editors typically map: `error` → red squiggle, `warning` → yellow,
@@ -19,9 +18,12 @@ export interface LanguageSpec {
19
18
  tagMap: Record<GrammarTokenKind, string | null>;
20
19
  components: ComponentEntry[];
21
20
  componentsByName: Record<string, ComponentEntry>;
22
- builtins: BuiltinEntry[];
23
- builtinsByName: Record<string, BuiltinEntry>;
24
21
  snippets: readonly SnippetEntry[];
22
+ /**
23
+ * Reserved-keyword documentation (definition + syntax + example),
24
+ * keyed by keyword. Powers keyword highlight-popups and hover help.
25
+ */
26
+ keywordDocs: Record<string, KeywordDoc>;
25
27
  /** Built-in theme names; useful for theme-picker autocomplete. */
26
28
  themeNames: readonly string[];
27
29
  /** Default severity for the parser's ParseError stream. */
@@ -15,7 +15,6 @@ export declare const Text: ComponentSpec;
15
15
  */
16
16
  export declare const TextContent: ComponentSpec;
17
17
  export declare const Image: ComponentSpec;
18
- export declare const Link: ComponentSpec;
19
18
  export declare const Badge: ComponentSpec;
20
19
  /**
21
20
  * `BadgeList` renders an array of string labels as a row of Badge pills.
@@ -0,0 +1,3 @@
1
+ import { ComponentSpec } from '../types.js';
2
+ export declare const HTMLTag: ComponentSpec;
3
+ export declare const Styles: ComponentSpec;
@@ -1,6 +1,9 @@
1
1
  import { ComponentSpec } from '../types.js';
2
2
  export declare const StackItem: ComponentSpec;
3
+ export declare const Row: ComponentSpec;
4
+ export declare const Column: ComponentSpec;
3
5
  export declare const Stack: ComponentSpec;
6
+ export declare const Center: ComponentSpec;
4
7
  export declare const Card: ComponentSpec;
5
8
  export declare const CardHeader: ComponentSpec;
6
9
  export declare const CardFooter: ComponentSpec;
@@ -0,0 +1,12 @@
1
+ import { ComponentSpec, RenderHelpers } from '../types.js';
2
+ export declare const OnClick: ComponentSpec;
3
+ export declare const OnMouse: ComponentSpec;
4
+ export declare const OnKeyboard: ComponentSpec;
5
+ export declare const OnFocus: ComponentSpec;
6
+ export declare const OnIntersect: ComponentSpec;
7
+ export declare const Link: ComponentSpec;
8
+ export declare const Css: ComponentSpec;
9
+ export declare function attachOnChange(element: HTMLElement, callback: unknown, helpers: RenderHelpers, options: {
10
+ event?: string;
11
+ getValue: (el: HTMLElement) => unknown;
12
+ }): void;
@@ -34,6 +34,7 @@ export type ResponsiveProp<T> = {
34
34
  export declare function readResponsiveProp<T>(value: unknown): ResponsiveProp<T>;
35
35
  export declare function sanitiseCssUrl(raw: string): string;
36
36
  export declare function sanitiseCssLength(raw: unknown, fallback: string): string;
37
+ export declare function sanitiseCssColor(raw: unknown): string;
37
38
  /**
38
39
  * Sanitise an LLM-supplied `href` value before it lands on an anchor.
39
40
  *
@@ -60,6 +61,46 @@ export declare function sanitiseHref(raw: unknown, fallback?: string): string;
60
61
  * callers can render their own placeholder.
61
62
  */
62
63
  export declare function sanitiseImageSrc(raw: unknown): string;
64
+ /** `true` when a value is a renderable component node produced by the runtime. */
65
+ export declare function isComponentNode(value: unknown): boolean;
66
+ /** Subset of `RenderHelpers` the table cell builder needs. */
67
+ export interface CellRenderHelpers {
68
+ renderNode: (node: unknown) => Node;
69
+ invoke: (callable: unknown, ...args: unknown[]) => void;
70
+ }
71
+ /** A column's cell-rendering configuration, shared by Table and DataGrid. */
72
+ export interface TableCellCol {
73
+ /** Cell value formatting hint (`text|number|currency|date`). */
74
+ format?: string;
75
+ /**
76
+ * Optional `(value, rowIndex) => Component | string | (Component|string)[]`
77
+ * mapper. Lets a column render arbitrary components — action buttons,
78
+ * badges, avatars, links — instead of plain text. When omitted, a cell
79
+ * value that is itself a component node still renders directly.
80
+ */
81
+ render?: unknown;
82
+ /**
83
+ * Optional `(value, rowIndex) => void` fired when the cell is clicked or
84
+ * activated via keyboard. Clicks originating on an interactive child
85
+ * (a rendered Button / link / input) are ignored so nested actions keep
86
+ * their own handlers.
87
+ */
88
+ onClick?: unknown;
89
+ }
90
+ /**
91
+ * Populate a `<td>` for one Table / DataGrid cell. Content resolution order:
92
+ *
93
+ * 1. `col.render(value, rowIndex)` — when provided, its result (a
94
+ * component, string, or array of either) is rendered. This is the
95
+ * idiomatic way to put buttons / badges / links in a column.
96
+ * 2. a component-node `value` — rendered directly (so authors can also
97
+ * pass a pre-built array of component cells as the column `values`).
98
+ * 3. otherwise the value is formatted as text via `formatValue`.
99
+ *
100
+ * When `col.onClick` is a callable the whole cell becomes an accessible
101
+ * button (pointer + Enter/Space), firing `onClick(value, rowIndex)`.
102
+ */
103
+ export declare function fillTableCell(td: HTMLElement, col: TableCellCol, value: unknown, rowIndex: number, helpers: CellRenderHelpers, formatValue: (value: unknown, format: string) => string): void;
63
104
  /**
64
105
  * Render an icon-typed prop into an `<i class="rui-icon fa-...">` element.
65
106
  *
@@ -70,4 +111,5 @@ export declare function sanitiseImageSrc(raw: unknown): string;
70
111
  export declare function renderIcon(value: unknown, options?: {
71
112
  className?: string;
72
113
  size?: IconSize | string;
114
+ color?: string;
73
115
  }): HTMLElement | null;
@@ -20,7 +20,7 @@ export interface FrontierResult {
20
20
  *
21
21
  * - Identifiers on the left of an assignment (`foo = …`).
22
22
  * - State assignments (`$x = …`).
23
- * - Component / effect / action / router declarations.
23
+ * - Function / effect declarations.
24
24
  *
25
25
  * Names that only appear as call expressions (`Button(…)`) inside the
26
26
  * drafting tail are not listed — those are dependencies, not bindings.
@@ -44,12 +44,12 @@ export interface FrontierResult {
44
44
  *
45
45
  * const f = computeFrontier(
46
46
  * "$state count = 0\n" +
47
- * "component Counter() {\n" +
47
+ * "function Counter() {\n" +
48
48
  * " Stack(Te" // mid-stream: half-written `Text`
49
49
  * );
50
50
  * // f.committedBindings = ["count"]
51
51
  * // f.uncommittedBindings = ["Counter"]
52
- * // f.committedSource ends just before "component Counter() {…"
52
+ * // f.committedSource ends just before "function Counter() {…"
53
53
  */
54
54
  export declare function computeFrontier(source: string): FrontierResult;
55
55
  /**
@@ -1,29 +1,19 @@
1
1
  /**
2
2
  * Tokenizer for Aktion.
3
3
  *
4
- * The language is line-oriented. We tokenize into a flat stream of tokens
5
- * including NEWLINE markers so that the parser can recover at line boundaries.
4
+ * The surface syntax is a strict subset of JavaScript. We tokenize into a
5
+ * flat stream of tokens including NEWLINE markers so that the parser can
6
+ * recover at line boundaries.
6
7
  */
7
- export type TokenType = "Identifier" | "Keyword" | "StateIdentifier" | "BuiltinIdentifier" | "Number" | "String"
8
+ export type TokenType = "Identifier" | "Keyword" | "StateIdentifier" | "Number" | "String"
8
9
  /**
9
10
  * Backtick-quoted template literal — carries alternating raw chunks and
10
11
  * embedded expression source strings via `parts`.
11
- * `parts[0]` is always a string chunk; positions then alternate between
12
- * `{kind:"expr", source}` and `{kind:"str", text}`.
13
12
  */
14
- | "TemplateString"
13
+ | "TemplateString" | "Boolean" | "Null" | "Punctuation" | "Operator" | "Newline" | "Semicolon" | "EOF";
15
14
  /**
16
- * `js{ … }` opaque block. The body is captured verbatim (with balanced
17
- * brace tracking) so it can be passed through to the runtime without
18
- * re-parsing.
19
- */
20
- | "JsBlock" | "Boolean" | "Null" | "Punctuation" | "Operator" | "Newline" | "EOF";
21
- /**
22
- * Keywords reserved by Aktion. The lexer recognises them so the
23
- * parser can dispatch on `Keyword` tokens directly instead of second-guessing
24
- * every identifier. `$name` is lexed as a `StateIdentifier` token whose
25
- * `value` is the bare name; there is only one reactive atom kind so no
26
- * additional disambiguation is needed.
15
+ * Keywords reserved by Aktion. The lexer recognises them so the parser can
16
+ * dispatch on `Keyword` tokens directly.
27
17
  */
28
18
  export declare const KEYWORDS_AKTION: Set<string>;
29
19
  export type TemplatePart = {