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
@@ -0,0 +1,15 @@
1
+ import { Program } from '../parser/types.js';
2
+ export interface EmitOptions {
3
+ /**
4
+ * Module specifier the emitted code imports `defineCompiledProgram` from.
5
+ * Defaults to `"aktion-runtime"`. Override for monorepos / local examples
6
+ * that resolve the runtime under a different name.
7
+ */
8
+ runtimeModuleId?: string;
9
+ }
10
+ /**
11
+ * Build the ES module source that exports the compiled program. The result is
12
+ * deterministic for a given `(program, source, path)` so repeated builds and
13
+ * resumed/cached transforms produce byte-identical output.
14
+ */
15
+ export declare function emitModule(program: Program, source: string, path: string, options?: EmitOptions): string;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * `aktion-runtime/compiler` — the Node-importable build-time compiler entry.
3
+ *
4
+ * Exposes `compile()` (code generation + source map + diagnostics) plus the
5
+ * browser-safe runtime helpers (`CompiledProgram`, `defineCompiledProgram`,
6
+ * `isCompiledProgram`, `compileLite`). This module pulls in `magic-string`,
7
+ * so it must NOT be re-exported from `src/index.ts` (the browser bundle) —
8
+ * only `./runtime.js` is browser-safe.
9
+ */
10
+ export * from './runtime.js';
11
+ export { compile } from './compile.js';
12
+ export type { CompileOptions, CompileResult, CompileDiagnostic } from './compile.js';
13
+ export { emitModule, type EmitOptions } from './emit.js';
14
+ export { generateSourceMap, type RawSourceMap } from './sourcemap.js';
@@ -0,0 +1,27 @@
1
+ import { Program } from '../parser/types.js';
2
+ import { CompileDiagnostic } from './compile.js';
3
+ /** Injected so the linker can be unit-tested with an in-memory file map. */
4
+ export interface ModuleResolver {
5
+ /** Resolve a specifier relative to the importer; `null` = unresolved. */
6
+ resolve(spec: string, importerPath: string): string | null;
7
+ /** Load module text by resolved (absolute) path. Throws if missing. */
8
+ load(path: string): string;
9
+ }
10
+ export interface LinkResult {
11
+ /** The merged, scope-renamed program (import statements dropped). */
12
+ program: Program;
13
+ /** Linker errors: unresolved import, missing export, duplicate local, dep parse errors. */
14
+ diagnostics: CompileDiagnostic[];
15
+ /** Absolute paths of the imported modules (excludes the entry). */
16
+ dependencies: string[];
17
+ }
18
+ /**
19
+ * Default resolver backed by Node's filesystem: relative specifiers resolve
20
+ * against the importer's directory. (Top-level `node:` imports are externalized
21
+ * in the Node build and this module never enters the browser bundle.)
22
+ */
23
+ export declare function createNodeResolver(): ModuleResolver;
24
+ /**
25
+ * Link the import graph rooted at `entrySource`/`entryPath` into one program.
26
+ */
27
+ export declare function linkProgram(entrySource: string, entryPath: string, resolver: ModuleResolver): LinkResult;
@@ -0,0 +1,63 @@
1
+ import { Program } from '../parser/types.js';
2
+ import { ComponentLibrary } from '../library/types.js';
3
+ /**
4
+ * Schema version of the compiled-program contract. Bumped only on a
5
+ * breaking change to the `CompiledProgram` shape so the runtime can reject
6
+ * an artefact produced by an incompatible compiler version instead of
7
+ * mounting garbage.
8
+ */
9
+ export declare const COMPILED_PROGRAM_VERSION = 1;
10
+ /**
11
+ * The build-time artefact produced by the Aktion compiler and consumed by
12
+ * `<aktion-app>.mountCompiled(...)`. It carries the parsed AST so the runtime
13
+ * skips `parse()`, plus the original source so text-based features
14
+ * (`applyDelta`, `serializeState` round-trips, debugging) keep working.
15
+ */
16
+ export interface CompiledProgram {
17
+ /** Version marker — see {@link COMPILED_PROGRAM_VERSION}. */
18
+ readonly __aktionCompiled: typeof COMPILED_PROGRAM_VERSION;
19
+ /** Already-parsed component-tree AST. Mounted without re-parsing. */
20
+ readonly program: Program;
21
+ /** Original DSL source — retained for `applyDelta`/snapshots/debugging. */
22
+ readonly source: string;
23
+ /** Module id / file path — used for diagnostics, source maps, HMR targeting. */
24
+ readonly path: string;
25
+ }
26
+ /**
27
+ * Narrowing guard for values that cross the `mountCompiled` boundary (or
28
+ * arrive over an HMR channel) so a stray object can't be mistaken for a
29
+ * compiled artefact.
30
+ */
31
+ export declare function isCompiledProgram(value: unknown): value is CompiledProgram;
32
+ /**
33
+ * Identity helper the emitted module wraps its payload with. It gives authors
34
+ * a single, typed construction point —
35
+ * `defineCompiledProgram({...})` returns a value typed as `CompiledProgram`,
36
+ * so a malformed payload is a compile error rather than a runtime surprise.
37
+ */
38
+ export declare function defineCompiledProgram(compiled: CompiledProgram): CompiledProgram;
39
+ /** Options for {@link compileLite}. */
40
+ export interface CompileLiteOptions {
41
+ /** Module id / file path stamped onto the artefact (default `"<inline>"`). */
42
+ path?: string;
43
+ /**
44
+ * Library reserved for future lite-path validation. The browser runtime
45
+ * already re-runs `validateProgramSchema` on mount (see `element.ts`
46
+ * `replan()`), so the lite path intentionally skips validation here to
47
+ * avoid duplicating diagnostics — it only parses and wraps.
48
+ */
49
+ library?: ComponentLibrary;
50
+ }
51
+ /**
52
+ * Parse `source` and wrap it as a {@link CompiledProgram} — the minimal,
53
+ * browser-safe single-file compile path. Useful for mounting a program string
54
+ * via `mountCompiled` without the streamed-string `setResponse` API, and as a
55
+ * lightweight programmatic entry. It deliberately performs no code generation,
56
+ * no source map, no module linking, and no schema validation (the runtime
57
+ * validates on mount), so it adds nothing to the browser bundle beyond the
58
+ * parser that already ships there.
59
+ *
60
+ * For build-time use (code generation + source maps + build diagnostics) the
61
+ * Node-only `compile()` from `aktion-runtime/compiler` is the right entry.
62
+ */
63
+ export declare function compileLite(source: string, options?: CompileLiteOptions): CompiledProgram;
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Source-map generation for the build-time compiler (Node-oriented).
3
+ *
4
+ * Fidelity note — read before "improving" this. The Aktion DSL is compiled to
5
+ * an inert data blob (`JSON.parse(...)`), NOT transpiled line-for-line to JS,
6
+ * and the parser records start-only `loc` (line + column, 1-indexed) with no
7
+ * end position or byte offset (see `src/parser/types.ts`). So a high-precision
8
+ * range map is neither possible nor meaningful here. What IS valuable, and
9
+ * what we produce, is a valid v3 map that:
10
+ *
11
+ * - registers the original `.aktion` file as a source with its full content
12
+ * (`sourcesContent`), so it shows up in browser devtools, and
13
+ * - anchors the generated module back to the original source,
14
+ *
15
+ * which is exactly what lets Vite chain the map and surface the original file.
16
+ * Per-statement range mappings are a future enhancement gated on the parser
17
+ * recording end positions.
18
+ *
19
+ * We use `magic-string` (already a transitive dep, promoted to a direct one)
20
+ * because it is the de-facto standard every Vite/Rollup plugin uses, so the
21
+ * VLQ-encoded output is guaranteed compatible with Vite's source-map pipeline.
22
+ */
23
+ /**
24
+ * Plain v3 source map object (decoupled from magic-string's class instance).
25
+ * Shaped to match Vite/Rollup's `ExistingRawSourceMap` so it flows straight
26
+ * into the bundler's source-map pipeline when returned from `transform`.
27
+ */
28
+ export interface RawSourceMap {
29
+ version: number;
30
+ sources: string[];
31
+ sourcesContent: string[];
32
+ names: string[];
33
+ mappings: string;
34
+ file?: string;
35
+ }
36
+ /**
37
+ * Produce a v3 source map tying `generatedCode` back to `source`. `path` names
38
+ * the original file in `sources`; the map's `file` is `path + ".js"`.
39
+ */
40
+ export declare function generateSourceMap(source: string, generatedCode: string, path: string): RawSourceMap;
@@ -1,3 +1,4 @@
1
+ import { CompiledProgram } from './compiler/runtime.js';
1
2
  import { DeltaOp } from './tooling/index.js';
2
3
  import { ComponentSpec } from './library/types.js';
3
4
  import { PromptOptions } from './prompt/generator.js';
@@ -11,25 +12,55 @@ export declare class AktionElement extends HTMLElement {
11
12
  private readonly router;
12
13
  private library;
13
14
  private readonly http;
14
- private readonly i18n;
15
15
  private readonly effectRunner;
16
16
  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
17
  private renderer;
25
18
  private context;
26
19
  private root;
27
20
  private rootEl;
28
21
  private errorEl;
29
22
  private currentResponse;
23
+ /**
24
+ * Pre-parsed AST injected by `mountCompiled(...)` (the build-time compiler /
25
+ * Vite plugin path). When set, `replan()` consumes it instead of calling
26
+ * `parse(currentResponse)`, then clears it so a later string update
27
+ * (`setResponse` / `appendChunk`) re-parses normally. `null` for the
28
+ * ordinary streamed-string path.
29
+ */
30
+ private pendingCompiled;
31
+ /**
32
+ * Module id of the compiled program currently mounted (from
33
+ * `CompiledProgram.path`), or `null` for the string path. The Vite plugin's
34
+ * HMR runtime reads it (via the `sourceId` getter) to target the right
35
+ * `<aktion-app>` instances when a `.aktion` file changes.
36
+ */
37
+ private compiledSourceId;
30
38
  private renderScheduled;
31
39
  /** True when the program text changed and the runtime needs a re-plan. */
32
40
  private programDirty;
41
+ /**
42
+ * Set of state paths the most recent render actually read (e.g. `"user.name"`,
43
+ * `"cart"`). The state subscription uses it to gate re-renders: a reactive
44
+ * write only re-renders when its changed path overlaps something the UI
45
+ * read (fine-grained reactivity). `null` means "no baseline yet" — the next
46
+ * change always renders (first paint, post-replan). Explicit `notify()`
47
+ * signals (async/HTTP/timers/effects/hooks) bypass this gate entirely.
48
+ */
49
+ private lastRenderDeps;
50
+ /**
51
+ * Reactive paths changed since the last render, accumulated across flushes
52
+ * (and across gated renders). Drives per-component memoization: the renderer
53
+ * skips a component whose args are unchanged and whose read-paths don't
54
+ * overlap this set.
55
+ */
56
+ private pendingChangedPaths;
57
+ /**
58
+ * Set when a re-render was requested via `notify()` (async resolution,
59
+ * timer, HTTP, hook, effect) rather than a tracked `$state` write. The
60
+ * change set isn't fully known in that case, so the next render disables
61
+ * memoization and re-renders everything.
62
+ */
63
+ private forceFullRender;
33
64
  private parseErrors;
34
65
  /**
35
66
  * Token keys most recently applied by an in-script `Theme({...})`
@@ -100,6 +131,26 @@ export declare class AktionElement extends HTMLElement {
100
131
  programText: string;
101
132
  state: Record<string, unknown>;
102
133
  }): void;
134
+ /**
135
+ * Mount a build-time-compiled program — the artefact produced by the
136
+ * Aktion Vite/Rollup plugin or `compile()` from `aktion-runtime/compiler`.
137
+ * The pre-parsed AST is rendered directly, skipping the runtime parser; the
138
+ * runtime still re-validates against the active library on `replan()`, so a
139
+ * host that has called `registerComponents(...)` stays correct even if the
140
+ * program was compiled against the default library.
141
+ *
142
+ * The string path (`setResponse`, `appendChunk`, `response`) is unaffected.
143
+ * Pass `state` to seed reactive values before the first render (used for SSR
144
+ * hydration and for HMR `$state` preservation — see the plugin's HMR
145
+ * runtime, which snapshots via `serializeState()` and replays it here).
146
+ */
147
+ mountCompiled(compiled: CompiledProgram, state?: Record<string, unknown>): void;
148
+ /**
149
+ * Module id of the compiled program currently mounted, or `null` when the
150
+ * element is driven by the streamed-string path. Used by the Vite plugin's
151
+ * HMR runtime to find the instances that host a changed `.aktion` file.
152
+ */
153
+ get sourceId(): string | null;
103
154
  /** Append a streaming chunk and re-render. */
104
155
  appendChunk(chunk: string): void;
105
156
  setTheme(theme: ThemeInput): void;
@@ -112,12 +163,6 @@ export declare class AktionElement extends HTMLElement {
112
163
  getSystemPrompt(options?: PromptOptions): string;
113
164
  /** Programmatic navigation API. */
114
165
  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
166
  /** Current route path (`/`, `/about`, …). */
122
167
  get route(): string;
123
168
  clear(): void;
@@ -127,31 +172,24 @@ export declare class AktionElement extends HTMLElement {
127
172
  set streaming(value: boolean);
128
173
  get showErrors(): boolean;
129
174
  set showErrors(value: boolean);
175
+ /** Dispatch a custom event from `emit()` calls in effect/action bodies. */
176
+ private emitCustomEvent;
130
177
  private buildInlineStyle;
131
178
  /**
132
- * Start the router so the hash listener is attached and `_route_` is
179
+ * Start the router so the hash listener is attached and `route` is
133
180
  * seeded with the current URL. Idempotent — safe to call from
134
181
  * `connectedCallback`.
135
182
  */
136
183
  private startRouter;
137
184
  /**
138
- * Write `_route_` only when its content actually changed. Avoids
185
+ * Write `route` only when its content actually changed. Avoids
139
186
  * triggering a redundant render-after-replan cascade — see
140
187
  * `routesEqual` for the structural comparison.
141
188
  */
142
189
  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
190
  /**
153
191
  * 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
192
+ * `route` reads re-evaluate), schedule a re-render, and bubble a
155
193
  * `route-change` event so host pages can sync analytics or sidebars.
156
194
  */
157
195
  private handleRouteChange;
@@ -166,7 +204,25 @@ export declare class AktionElement extends HTMLElement {
166
204
  */
167
205
  private applyScriptThemeOverrides;
168
206
  private scheduleRender;
207
+ /**
208
+ * Request a full (non-memoized) re-render. Used for changes the path
209
+ * tracker can't see — async / HTTP resolutions, timers, hook setters,
210
+ * effect bodies, custom events. The whole tree re-evaluates next tick.
211
+ */
212
+ private requestFullRender;
169
213
  private renderNow;
214
+ /** Whether the "state write during render" warning has already fired. */
215
+ private warnedStateWriteDuringRender;
216
+ private warnStateWriteDuringRender;
217
+ /**
218
+ * Surface a runtime-budget abort the same way parse errors are
219
+ * surfaced: append it to `parseErrors`, refresh the error banner,
220
+ * and bubble an `error` event so the host page (or playground) can
221
+ * react. The rendered DOM is intentionally left untouched — the
222
+ * partially-rendered output from a previous tick is more useful to
223
+ * the user than a flash of blank UI.
224
+ */
225
+ private handleRuntimeBudgetError;
170
226
  private captureFocus;
171
227
  private restoreFocus;
172
228
  private replan;
@@ -7,6 +7,7 @@ export * from './renderer/index.js';
7
7
  export * from './prompt/index.js';
8
8
  export * from './theme/index.js';
9
9
  export * from './language/index.js';
10
+ export * from './compiler/runtime.js';
10
11
  declare global {
11
12
  interface HTMLElementTagNameMap {
12
13
  "aktion-app": AktionElement;
@@ -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. */
@@ -0,0 +1,15 @@
1
+ /**
2
+ * `aktion-runtime/language` — the DOM-free language + tooling surface.
3
+ *
4
+ * Editors (VS Code, a future LSP), CLIs, and any host that needs
5
+ * diagnostics / completions / hover / snippets / grammar metadata can import
6
+ * this WITHOUT loading the `<aktion-app>` custom element (the main
7
+ * `aktion-runtime` entry calls `defineElement()` on import, which requires a
8
+ * DOM and would crash in a Node extension host). Everything re-exported here
9
+ * is pure and Node-safe — no DOM access at import time.
10
+ */
11
+ export { getDiagnostics, getCompletions, getHoverInfo, type Position, type Diagnostic, type CompletionItem, type HoverInfo, } from './tooling/language-service.js';
12
+ export { getSnippets, type SnippetEntry } from './language/snippets.js';
13
+ export { getLanguageSpec, grammarSpec, keywordDocs, getComponentCatalog, type LanguageSpec, type ComponentEntry, type ComponentParam, type GrammarSpec, } from './language/index.js';
14
+ export { defaultLibrary } from './library/index.js';
15
+ export type { ComponentLibrary } from './library/types.js';
@@ -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 = {