aktion-runtime 0.5.0

package/dist/types/parser/types.d.ts

@@ -0,0 +1,349 @@
+/**
+ * AST types for Aktion.
+ *
+ * The grammar is line-oriented:
+ *   identifier = Expression
+ *   $stateVariable = LiteralDefault
+ *   name = Query(...) | Mutation(...)
+ *
+ * Expressions form a tree of literals, references, calls, and operators.
+ */
+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;
+/** `if cond { ... } else { ... }` expression — see §8.1. */
+export interface IfExpr {
+    kind: "If";
+    test: Expression;
+    consequent: BlockExpr;
+    alternate?: IfExpr | BlockExpr;
+    loc?: SourceLocation;
+}
+/** `match value { pat -> expr, _ -> expr }` expression — see §8.2. */
+export interface MatchExpr {
+    kind: "Match";
+    discriminant: Expression;
+    arms: ReadonlyArray<MatchArm>;
+    loc?: SourceLocation;
+}
+export interface MatchArm {
+    /** Literal pattern (string / number / boolean / null / identifier) or `_`. */
+    pattern: Expression | "_";
+    body: Expression;
+}
+/** `for x in arr { body }` expression — see §8.3. */
+export interface ForExpr {
+    kind: "For";
+    /** Item binding name. */
+    item: string;
+    /** Optional `(item, idx)` destructuring index name. */
+    index?: string;
+    /** Optional `{a, b, c}` destructuring — binds each named field of the row. */
+    destructure?: ReadonlyArray<string>;
+    iterable: Expression;
+    body: BlockExpr;
+    loc?: SourceLocation;
+}
+/** `(args) => body` lambda. The body is a single expression OR a `js{}` block. */
+export interface LambdaExpr {
+    kind: "Lambda";
+    params: ReadonlyArray<LambdaParam>;
+    body: Expression | JsBlockExpr;
+    loc?: SourceLocation;
+}
+export interface LambdaParam {
+    name: string;
+    defaultValue?: Expression;
+}
+/** `js{ ... raw js ... }` opaque block. Runs verbatim under an `effect` or `action` body. */
+export interface JsBlockExpr {
+    kind: "JsBlock";
+    body: string;
+    loc?: SourceLocation;
+}
+/**
+ * `bind:prop: stateRef` argument. Desugars at runtime to
+ * `prop: stateRef, on<Prop>Change: (v) => stateRef = v`.
+ */
+export interface BindExpr {
+    kind: "Bind";
+    prop: string;
+    target: Expression;
+    loc?: SourceLocation;
+}
+/**
+ * Statement block delimited by `{ ... }`. Used as the body of `component`,
+ * `effect`, `action`, `if`, `match`, `for`, and lambdas with multiple
+ * statements. The last expression in the block (if any) is its value.
+ */
+export interface BlockExpr {
+    kind: "Block";
+    body: ReadonlyArray<Statement>;
+    loc?: SourceLocation;
+}
+/**
+ * Named component argument inside a call list: `GridItem(child, span: "1/4")`.
+ * Only valid in `(...)` argument lists, not inside `[...]` arrays.
+ */
+export interface NamedArgExpr {
+    kind: "NamedArg";
+    name: string;
+    value: Expression;
+    loc?: SourceLocation;
+}
+export interface SourceLocation {
+    line: number;
+    column: number;
+}
+export interface LiteralExpr {
+    kind: "Literal";
+    value: string | number | boolean | null;
+    loc?: SourceLocation;
+}
+export interface IdentifierExpr {
+    kind: "Identifier";
+    name: string;
+    loc?: SourceLocation;
+}
+export interface StateRefExpr {
+    kind: "StateRef";
+    name: string;
+    loc?: SourceLocation;
+}
+export interface ArrayExpr {
+    kind: "Array";
+    elements: Expression[];
+    loc?: SourceLocation;
+}
+export interface ObjectProperty {
+    key: string;
+    value: Expression;
+    /** True for `{...source}` shorthand — `key` is ignored when set. */
+    spread?: boolean;
+}
+export interface ObjectExpr {
+    kind: "Object";
+    properties: ObjectProperty[];
+    loc?: SourceLocation;
+}
+export interface MemberExpr {
+    kind: "Member";
+    object: Expression;
+    /** Dot-access property name (`obj.field`). */
+    property?: string;
+    /** Bracket-access key (`arr[i]`, `obj[$key]`). */
+    computed?: Expression;
+    /** True for `obj?.prop` / `obj?.[key]` — short-circuits when `obj` is null/undefined. */
+    optional?: boolean;
+    loc?: SourceLocation;
+}
+/**
+ * Spread element used inside array literals (`[...a, b]`). Object spread is
+ * modelled as an `ObjectProperty` with `spread: true` because the parser
+ * already enumerates props.
+ */
+export interface SpreadExpr {
+    kind: "Spread";
+    argument: Expression;
+    loc?: SourceLocation;
+}
+/**
+ * Template literal: `` `Hello ${$user.name}, you have ${$count} messages` ``.
+ *
+ * Encoded as alternating raw string chunks (`quasis`) and embedded
+ * expressions. `quasis.length === expressions.length + 1` — there is always
+ * one more chunk than expression, even when the template starts or ends
+ * with an interpolation (the boundary chunk is empty in that case). This
+ * mirrors how the JavaScript AST represents template literals.
+ */
+export interface TemplateLiteralExpr {
+    kind: "Template";
+    quasis: string[];
+    expressions: Expression[];
+    loc?: SourceLocation;
+}
+export interface UnaryExpr {
+    kind: "Unary";
+    operator: "!" | "-";
+    argument: Expression;
+    loc?: SourceLocation;
+}
+export type BinaryOperator = "+" | "-" | "*" | "/" | "%" | "==" | "!=" | ">" | "<" | ">=" | "<=" | "&&" | "||"
+/**
+ * Nullish coalescing — returns `left` unless it is `null` or `undefined`.
+ * Distinct from `||`, which also short-circuits on `0`, `""`, and `false`.
+ */
+ | "??";
+export interface BinaryExpr {
+    kind: "Binary";
+    operator: BinaryOperator;
+    left: Expression;
+    right: Expression;
+    loc?: SourceLocation;
+}
+export interface TernaryExpr {
+    kind: "Ternary";
+    test: Expression;
+    consequent: Expression;
+    alternate: Expression;
+    loc?: SourceLocation;
+}
+export interface CallExpr {
+    kind: "Call";
+    callee: string;
+    arguments: Expression[];
+    loc?: SourceLocation;
+}
+/**
+ * `object.method(args...)` invocation. Used for namespaced globals like
+ * `storage.set(...)`, `console.log(...)`, and chained member calls on
+ * runtime values (`$res.refetch()`). Named args inside the argument list
+ * are collected into a single trailing options object — so
+ * `storage.cookies.set("k", "v", expires: 1, path: "/")` resolves to
+ * `set("k", "v", { expires: 1, path: "/" })`.
+ */
+export interface MethodCallExpr {
+    kind: "MethodCall";
+    object: Expression;
+    method: string;
+    arguments: Expression[];
+    /** True for `obj?.method(...)` — short-circuits to `undefined` when `obj` is null. */
+    optional?: boolean;
+    loc?: SourceLocation;
+}
+export interface BuiltinCallExpr {
+    kind: "BuiltinCall";
+    name: string;
+    arguments: Expression[];
+    loc?: SourceLocation;
+}
+export interface AssignmentStatement {
+    kind: "Assignment";
+    identifier: string;
+    isState: boolean;
+    expression: Expression;
+    loc?: SourceLocation;
+}
+/**
+ * `component Name(p, q: default, slots: { footer? }) { ... }` declaration.
+ * The body is a `BlockExpr`; the last expression is the rendered output.
+ */
+export interface ComponentDeclaration {
+    kind: "ComponentDeclaration";
+    name: string;
+    params: ReadonlyArray<DeclParam>;
+    /** Names of the declared slots, e.g. `{ footer? }` -> `["footer"]`. */
+    slots: ReadonlyArray<string>;
+    body: BlockExpr;
+    loc?: SourceLocation;
+}
+/**
+ * Parameter on a `component`, `action`, or `effect` declaration. Distinct
+ * from `library/components` `ComponentParam` (the editor-level surface
+ * projection) — kept under a different name to avoid an ambiguous re-export
+ * from the package root.
+ */
+export interface DeclParam {
+    name: string;
+    defaultValue?: Expression;
+    optional?: boolean;
+}
+/**
+ * `effect [ ...dependencies ] { body }` declaration.
+ *
+ * Effects are anonymous — the parser auto-assigns a stable name from the
+ * declaration's source location so the runtime can keep track of them
+ * across re-parses. The optional bracketed dependency list mixes state
+ * triggers (`$name`), lifecycle / interval triggers (`on:mount`,
+ * `on:unmount`, `on:every(N)`), and rate-limit modifiers (`debounce(N)`,
+ * `throttle(N)`) in any order.
+ *
+ * `effect { ... }` (no brackets) and `effect [on:mount] { ... }` are
+ * equivalent — both run the body once on mount.
+ */
+export interface EffectDeclaration {
+    kind: "EffectDeclaration";
+    /** Auto-generated name (`__effect_L{line}_C{column}`) — used as a runtime key. */
+    name: string;
+    triggers: ReadonlyArray<EffectTrigger>;
+    /** Optional rate-limit modifier (`debounce(N)` / `throttle(N)`). */
+    rateLimit?: EffectRateLimit;
+    body: BlockExpr;
+    loc?: SourceLocation;
+}
+/** Trigger literal (`$state`, `on:mount`, `on:unmount`, `on:every(N)`). */
+export type EffectTrigger = {
+    kind: "state";
+    name: string;
+} | {
+    kind: "lifecycle";
+    name: "mount" | "unmount";
+} | {
+    kind: "every";
+    intervalMs: number;
+};
+/** Rate-limit modifier on an `effect` (`debounce(N)` / `throttle(N)`). */
+export interface EffectRateLimit {
+    kind: "debounce" | "throttle";
+    /** Window in milliseconds. */
+    ms: number;
+}
+/**
+ * `action Name(args) [optimistic] { body }` declaration. Actions are
+ * explicit-call effects; their body runs whenever the action is invoked
+ * from an event handler (`onClick: actionName`).
+ */
+export interface ActionDeclaration {
+    kind: "ActionDeclaration";
+    name: string;
+    params: ReadonlyArray<DeclParam>;
+    optimistic: boolean;
+    body: BlockExpr;
+    loc?: SourceLocation;
+}
+/** `emit "name" { detail }` outbound event statement. */
+export interface EmitStatement {
+    kind: "Emit";
+    eventName: string;
+    detail: Expression;
+    loc?: SourceLocation;
+}
+/** `cleanup(fn)` registration call — only valid inside `effect` bodies. */
+export interface CleanupStatement {
+    kind: "Cleanup";
+    callback: Expression;
+    loc?: SourceLocation;
+}
+/** `await expr` statement / expression — only valid inside `action`/`effect`. */
+export interface AwaitStatement {
+    kind: "Await";
+    argument: Expression;
+    loc?: SourceLocation;
+}
+/** `return [expr]` statement — only valid inside `action`/`effect`/`component`. */
+export interface ReturnStatement {
+    kind: "Return";
+    argument?: Expression;
+    loc?: SourceLocation;
+}
+/** Bare expression statement at the top of a block / body. */
+export interface ExpressionStatement {
+    kind: "ExpressionStatement";
+    expression: Expression;
+    loc?: SourceLocation;
+}
+export type Statement = AssignmentStatement | ComponentDeclaration | EffectDeclaration | ActionDeclaration | EmitStatement | CleanupStatement | AwaitStatement | ReturnStatement | ExpressionStatement;
+export interface Program {
+    statements: Statement[];
+    errors: ParseError[];
+    /**
+     * Non-fatal diagnostics surfaced by schema validation (§15). The
+     * program still runs — these are advisory hints for authors who chose
+     * a token outside the closed enum, supplied an unknown named arg, or
+     * tripped some other "this will not look right" lint.
+     */
+    warnings?: ParseError[];
+}
+export interface ParseError {
+    message: string;
+    line: number;
+    column: number;
+}

package/dist/types/prompt/generator.d.ts

@@ -0,0 +1,33 @@
+import { ComponentLibrary, ComponentSpec } from '../library/types.js';
+export interface ToolSpec {
+    name: string;
+    description: string;
+    /** Example argument shape the LLM should call with. */
+    argsExample?: Record<string, unknown>;
+    /** Whether this endpoint is read-only or mutating. Influences method hint. */
+    kind?: "Query" | "Mutation";
+}
+export type PromptMode = "full" | "chat";
+export interface PromptOptions {
+    mode?: PromptMode;
+    /** Replace the default opening sentence describing the assistant's role. */
+    preamble?: string;
+    /** Bullets appended under an `## Additional rules` section near the end. */
+    additionalRules?: ReadonlyArray<string>;
+    /** Worked-example snippets shown under `## Examples`. Defaults to a curated set. */
+    examples?: ReadonlyArray<string>;
+    /** Host-provided endpoint catalogue. Surfaced under `## Available endpoints`. */
+    tools?: ReadonlyArray<ToolSpec>;
+    /** Endpoint usage examples. Surfaced under `## Endpoint examples`. */
+    toolExamples?: ReadonlyArray<string>;
+    /** Force-include the HTTP/tool-calling teaching sections in `full` mode. */
+    toolCalls?: boolean;
+    /** Force-include the reactive-state + builtins sections in `full` mode. */
+    bindings?: boolean;
+    /** Permit fenced ```aktion blocks inside markdown prose (full mode). */
+    inlineMode?: boolean;
+    /** Tell the LLM to emit only changed statements (full mode). */
+    editMode?: boolean;
+}
+export declare function generatePrompt(library: ComponentLibrary, options?: PromptOptions): string;
+export declare function describeComponentSpec(spec: ComponentSpec): string;

package/dist/types/prompt/index.d.ts

@@ -0,0 +1 @@
+export * from './generator.js';

package/dist/types/renderer/index.d.ts

@@ -0,0 +1 @@
+export * from './renderer.js';

package/dist/types/renderer/morph.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Minimal DOM reconciler ("morph").
+ *
+ * The renderer used to discard the whole subtree on every state change and
+ * recreate it from scratch (`replaceChildren(newTree)`). That works for static
+ * UIs but destroys any state the browser owns on the live DOM:
+ *
+ *   - text-input value, selection, IME composition
+ *   - scroll position of a long list
+ *   - <details>.open after the user clicked the summary
+ *   - focus on a typed input (email/number/url, where setSelectionRange
+ *     throws and the cursor jumps to the start)
+ *
+ * `morphChildren(container, newRoot)` walks the live DOM in parallel with the
+ * freshly-rendered DOM, keeps as many existing nodes as possible, and only
+ * patches what changed. The result is a React-like reconciliation pass that
+ * keeps form fields stable while still letting the renderer rebuild the
+ * tree every tick.
+ *
+ * Two contracts the rest of the runtime relies on:
+ *
+ *   1. Event handlers are attached as DOM properties (`el.onclick = fn`)
+ *      rather than via `addEventListener`. This lets the morph copy the
+ *      fresh closure (`newEl.onclick`) onto the kept node (`oldEl.onclick`)
+ *      without leaking the previous listener.
+ *   2. Components that own UI state across re-renders (e.g. `Tabs` active
+ *      pane) use `helpers.useInstanceState(...)`. The morph just reuses
+ *      the existing DOM; whatever attribute values land in the fresh tree
+ *      are the ones that get applied.
+ */
+/**
+ * Patch `container` so its children match `newRoot`. `newRoot` can be a
+ * `DocumentFragment` (treated as a sibling list) or a single node (treated
+ * as the sole child).
+ */
+export declare function morphChildren(container: Element, newRoot: Node): void;
+/**
+ * Reconcile a single live node against its freshly-rendered counterpart.
+ * Returns the resulting node (either the patched `oldNode` or a freshly
+ * inserted `newNode`).
+ */
+export declare function morphNode(oldNode: Node, newNode: Node): Node;

package/dist/types/renderer/renderer.d.ts

@@ -0,0 +1,73 @@
+import { EvaluationContext } from '../runtime/evaluator.js';
+import { StateStore } from '../runtime/state.js';
+import { Router } from '../runtime/router.js';
+import { ComponentLibrary } from '../library/types.js';
+export interface RenderOptions {
+    library: ComponentLibrary;
+    state: StateStore;
+    /** Hash-based router. Required: components read the active path through it. */
+    router: Router;
+    /** Optional callback for `helpers.sendToAssistant(message)` dispatch. */
+    onAssistantMessage?: (message: string) => void;
+    /** Optional override for `helpers.openUrl(url)` (defaults to `window.open`). */
+    onOpenUrl?: (url: string) => void;
+    /**
+     * Evaluation context used to expand user-declared `component` calls
+     * (per-instance state isolation, lazy body evaluation, §7). The host
+     * element passes its program context here; if absent, user components
+     * render as `[unknown component: <Name>]` so the failure is visible.
+     */
+    evaluationContext?: () => EvaluationContext;
+}
+export declare class Renderer {
+    private options;
+    /**
+     * Persistent state cells, keyed by `instancePath::userKey`. Lives as long
+     * as the component instance is rendered. Stale entries are garbage-
+     * collected at the end of each render (see `endRender`).
+     */
+    private readonly instanceStates;
+    /**
+     * Cleanup callbacks per instance path. Each entry holds either a single
+     * disposer (anonymous registration) or a map keyed by user-provided
+     * identifier so callers can register, replace, and (transitively) cancel
+     * prior cleanups for the same logical concern.
+     */
+    private readonly instanceDisposers;
+    /** Instance paths seen during the current render — used to GC stale state. */
+    private aliveInstances;
+    constructor(options: RenderOptions);
+    /**
+     * Swap the component library backing this renderer. Used when the host
+     * element calls `registerComponents(...)` after first paint — preserves
+     * any `useInstanceState` slots so stateful primitives (Tabs, Popover,
+     * DropdownMenu, …) don't snap back to their initial values mid-session.
+     */
+    setLibrary(library: ComponentLibrary): void;
+    /**
+     * Drop all persistent per-instance state. Called when the host element
+     * is `clear()`ed so a fresh program starts with a clean slate.
+     */
+    reset(): void;
+    /** Begin a fresh render pass; tracks which instances are still alive. */
+    beginRender(): void;
+    /**
+     * End the current render pass. Drops instance state for components that
+     * disappeared from the tree so the map doesn't grow unbounded.
+     */
+    endRender(): void;
+    private safeDispose;
+    render(value: unknown): Node;
+    private renderAt;
+    /**
+     * Expand a user-declared `component Foo(p) { ... }` invocation. Each
+     * instance gets a stable instance key derived from its render path (or
+     * the caller's explicit `key:` override); the evaluator then evaluates
+     * the component's body with a fresh per-instance state-alias scope so
+     * two `Counter()` instances hold independent atoms (§7).
+     */
+    private renderUserComponent;
+    private renderComponent;
+    private eventFor;
+    private defaultValueGetter;
+}

package/dist/types/runtime/builtins.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Built-in `@Name(...)` functions for Aktion.
+ *
+ * These are pure data transformations. The legacy action-step builtins
+ * (`@Run`, `@Set`, `@Reset`, `@ToAssistant`, `@OpenUrl`, `@Navigate`,
+ * `@Js`) and the `@Const` memo helper were removed. Use `action <Name>() {
+ * … }` declarations + lambda handlers (`onClick: save`) instead, and just
+ * `$name = expression` for plain reactive bindings.
+ */
+export type BuiltinFn = (args: unknown[]) => unknown;
+export declare const dataBuiltins: Record<string, BuiltinFn>;
+/**
+ * Marker emitted by the `Theme({...})` construct. Carries an arbitrary token
+ * map that the element applies on top of the base theme between render
+ * cycles. Distinct from `ComponentNode` so the renderer can ignore it (it is
+ * a side-effect, not a piece of UI to draw).
+ *
+ * Authors declare a theme like any other top-level binding:
+ *
+ *   theme = Theme({ colors: { primary: "#0969da" }, radius: { button: "6px" } })
+ *   root  = Stack([...])
+ */
+export interface ThemeNode {
+    kind: "Theme";
+    tokens: Record<string, string>;
+}
+export declare const isThemeNode: (value: unknown) => value is ThemeNode;

package/dist/types/runtime/console.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Console namespace for Aktion.
+ *
+ * Exposes a `console` global that forwards to the browser's built-in
+ * `console` methods (`log`, `error`, `warn`, `info`, `debug`). The
+ * forwarder gracefully no-ops when no global console is available (e.g.
+ * during SSR or inside a worker without a console binding) so authors
+ * can sprinkle `console.log(...)` calls without breaking partial-stream
+ * renders.
+ *
+ * The runtime intentionally does NOT shadow JavaScript's full console
+ * surface — just the five methods that LLM-authored scripts reach for.
+ */
+export interface ConsoleNamespace {
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+}
+export declare const consoleNs: ConsoleNamespace;

package/dist/types/runtime/effects.d.ts

@@ -0,0 +1,69 @@
+import { ActionDeclaration, EffectDeclaration } from '../parser/types.js';
+import { EvaluationContext } from './evaluator.js';
+import { StateStore } from './state.js';
+export interface EffectRunnerOptions {
+    state: StateStore;
+    /** Called whenever an effect mutates state or completes — schedules render. */
+    notify: () => void;
+    /** Called when the action body emits a CustomEvent via `emit`. */
+    onEmit?: (eventName: string, detail: unknown) => void;
+    /** Host element — exposed to `js{}` block bodies as `ctx.host`. */
+    host?: HTMLElement;
+    /**
+     * Optional pluggable async tool registry — exposed to `js{}` blocks as
+     * `ctx.tools.<name>(...)`. Each entry is invoked with whatever args the
+     * JS body passes; the return value is awaited. Hosts can register fetch
+     * shims, persistence helpers, etc.
+     */
+    tools?: Record<string, (...args: unknown[]) => unknown>;
+}
+export declare class EffectRunner {
+    private readonly options;
+    private mounted;
+    private errors;
+    constructor(options: EffectRunnerOptions);
+    /** Get any errors raised at mount-time (denied capabilities, parse issues). */
+    getErrors(): ReadonlyArray<string>;
+    /**
+     * Mount every effect declaration in `decls`. Idempotent: declarations
+     * that are already mounted under the same name are left alone, those
+     * that vanish from the new program are torn down.
+     */
+    syncEffects(decls: ReadonlyArray<EffectDeclaration>, getCtx: () => EvaluationContext): void;
+    reset(): void;
+    private mount;
+    private unmount;
+}
+interface JsBlockExecOptions {
+    state: StateStore;
+    host?: HTMLElement;
+    tools?: Record<string, (...args: unknown[]) => unknown>;
+}
+/**
+ * Build a standalone `js{ … }` runner closure for the renderer / inline
+ * lambdas to invoke. Identical sandbox surface as the effect/action
+ * runners (host, tools, state get/set, optional cleanup hook).
+ */
+export declare function createInlineJsExecutor(options: JsBlockExecOptions): (body: string, args?: Record<string, unknown>) => unknown;
+export interface ActionRunnerOptions {
+    state: StateStore;
+    notify: () => void;
+    onEmit?: (eventName: string, detail: unknown) => void;
+    onAssistantMessage?: (message: string) => void;
+    /** Host element exposed to `js{}` blocks as `ctx.host`. */
+    host?: HTMLElement;
+    /** Pluggable tool registry exposed to `js{}` blocks as `ctx.tools.<name>`. */
+    tools?: Record<string, (...args: unknown[]) => unknown>;
+}
+/**
+ * Run an `action` declaration. When the declaration is `optimistic` we
+ * snapshot every state atom touched before the first `await`; if any
+ * subsequent step throws, the snapshot is restored.
+ */
+export declare class ActionDeclRunner {
+    private readonly options;
+    constructor(options: ActionRunnerOptions);
+    run(decl: ActionDeclaration, callArgs: unknown[], ctx: EvaluationContext): Promise<unknown>;
+    private runStatement;
+}
+export {};