aktion-runtime 0.5.0

package/dist/types/library/components/router.d.ts

@@ -0,0 +1,2 @@
+import { ComponentSpec } from '../types.js';
+export declare const NavLink: ComponentSpec;

package/dist/types/library/components/theme.d.ts

@@ -0,0 +1,2 @@
+import { ComponentSpec } from '../types.js';
+export declare const Theme: ComponentSpec;

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

@@ -0,0 +1,5 @@
+import { ComponentLibrary } from './types.js';
+export * from './types.js';
+export * from './registry.js';
+export { validateProgramSchema, validateProgram } from './validate.js';
+export declare const defaultLibrary: ComponentLibrary;

package/dist/types/library/registry.d.ts

@@ -0,0 +1,15 @@
+import { ComponentLibrary, ComponentSpec } from './types.js';
+/**
+ * Combines two libraries by name. Components from `extra` win on collision.
+ * Useful when a consumer registers their own components alongside the
+ * built-ins via `<aktion-app>.registerComponents([...])`.
+ */
+export declare function mergeLibraries(base: ComponentLibrary, extra: {
+    components: ReadonlyArray<ComponentSpec>;
+    root?: string;
+}): ComponentLibrary;
+/**
+ * Resolve a component spec by name. O(1) thanks to the lazily-built index
+ * cached against the library's `components` array.
+ */
+export declare function findComponent(library: ComponentLibrary, name: string): ComponentSpec | undefined;

package/dist/types/library/types.d.ts

@@ -0,0 +1,140 @@
+import { ComponentNode } from '../runtime/evaluator.js';
+import { Router } from '../runtime/router.js';
+export type PrimitiveType = "string" | "number" | "boolean" | "any" | "callable" | "Node" | "Node[]";
+export interface PropSpec {
+    name: string;
+    type: PrimitiveType | string;
+    optional?: boolean;
+    /**
+     * Aktion 0.5 §19.1 — at most one prop per spec may be marked
+     * positional. Authors may pass exactly one positional argument at the
+     * call site; it lands in this prop's slot regardless of its position in
+     * the `props` array. Every other prop must be provided as a named
+     * argument (`prop: value`). Specs without any `positional: true` flag
+     * reject every positional argument at evaluation time.
+     */
+    positional?: boolean;
+    /**
+     * Marker only — recorded so the schema-driven prompt generator can render
+     * required props without an `?` suffix. Not enforced by the runtime.
+     */
+    required?: boolean;
+    description?: string;
+    /** Accepted enum values, formatted as a comma-separated list in the prompt. */
+    enum?: readonly string[];
+    /**
+     * Optional alternative names that route to this prop when used as a
+     * `name: value` named argument at the call site. Lets the same prop be
+     * called by its canonical name *and* a synonym so authors writing
+     * `Badge("Live", tone: "success")` and `Badge("Live", variant: "success")`
+     * both land in the same slot. Aliases never change the runtime prop name
+     * — renderers continue to read `props[spec.name]`.
+     */
+    aliases?: readonly string[];
+}
+export interface ComponentSpec {
+    name: string;
+    description: string;
+    props: readonly PropSpec[];
+    render: ComponentRenderFn;
+}
+/**
+ * Aktion 0.5 §19.1 — locate the canonical positional prop
+ * for a spec. A spec opts in by marking exactly one prop with
+ * `positional: true`. Specs that omit the marker fall back to "first prop
+ * is positional", which is the convention every legacy library component
+ * was authored with.
+ *
+ * `findPositionalIndex` is consumed by the evaluator (to route the single
+ * positional argument to the right slot regardless of where in `props`
+ * the positional prop lives — e.g. `Portal(target?, children)` keeps
+ * `children` as the positional but it lives at index 1).
+ *
+ * `findPositionalProp` returns the resolved prop or `undefined` for void
+ * components (zero props).
+ */
+export declare function findPositionalIndex(spec: ComponentSpec): number;
+export declare function findPositionalProp(spec: ComponentSpec): PropSpec | undefined;
+/**
+ * Asserts that every spec in the library declares at most one positional
+ * prop. Surfaces inconsistencies as a `SyntaxError` at module load so the
+ * library never ships a contradictory spec.
+ */
+export declare function assertOnePositionalMax(specs: ReadonlyArray<ComponentSpec>): void;
+/**
+ * Stable, component-local state slot. Returned by
+ * `RenderHelpers.useInstanceState`. Keep the reference for the lifetime of
+ * a single render — the renderer wires it to a long-lived storage cell so
+ * subsequent renders read the value the previous click handler wrote.
+ */
+export interface InstanceStateSlot<T> {
+    get(): T;
+    set(value: T): void;
+}
+export interface RenderHelpers {
+    /** Render a child node tree (a ComponentNode or array of nodes). */
+    renderNode: (node: unknown) => Node;
+    /**
+     * Invoke a user-supplied callable (e.g. a lambda passed as an `onClick`
+     * prop, or a bare `action` declaration reference). Safe to call with
+     * `undefined` / `null` — silently no-ops. Returned values are ignored.
+     *
+     * This is the single dispatch path for user-authored event handlers in
+     * Aktion 0.5. The legacy `Action([@Set, @Run, ...])` payload
+     * is no longer accepted.
+     */
+    invoke: (callable: unknown, ...args: unknown[]) => void;
+    /** Set a state value. Used by library primitives for their own internal state writes. */
+    setState: (name: string, value: unknown) => void;
+    /** Reset state values back to their initial declared value. */
+    resetState: (...names: string[]) => void;
+    /** Dispatch an `assistant-message` CustomEvent on the host element. */
+    sendToAssistant: (message: string) => void;
+    /** Open a URL (sanitised against `javascript:` payloads). */
+    openUrl: (url: string) => void;
+    /** Bind a `$variable` to an HTML form element. */
+    bindState: (element: HTMLElement, name: string, options?: {
+        event?: string;
+        getValue?: (el: HTMLElement) => unknown;
+    }) => void;
+    /**
+     * Persist component-local state across re-renders. The slot is keyed by
+     * the component's position in the tree (its source location plus its
+     * path through sibling iterations), so independent instances never share
+     * a value. Used by stateful primitives like `Tabs` so user-driven UI
+     * state (active tab, expanded row, …) survives a re-render triggered by
+     * unrelated state changes.
+     */
+    useInstanceState: <T>(key: string, initialValue: T) => InstanceStateSlot<T>;
+    /**
+     * Register a cleanup callback tied to this component instance. The renderer
+     * invokes the callback once the instance disappears from the tree (e.g. a
+     * Toast finishes auto-dismissing or the parent re-renders without it).
+     * Use for `setTimeout` / `setInterval` handles and external resources so we
+     * never accumulate work for components the user can no longer see.
+     *
+     * Calling this multiple times during a single render replaces any previous
+     * disposer for the same `key` (cancelling the prior cleanup runs immediately
+     * via that callback's caller). If `key` is omitted, each call registers an
+     * independent disposer.
+     */
+    registerDisposer: (cleanup: () => void, key?: string) => void;
+    /**
+     * Hash-based router instance, always provided. Components such as `NavLink`
+     * call `router.navigate(path)` directly to change the active route.
+     */
+    router: Router;
+}
+export type ComponentRenderFn = (node: ComponentNode, props: Record<string, unknown>, helpers: RenderHelpers) => Node;
+export interface ComponentGroup {
+    name: string;
+    components: readonly string[];
+    notes?: readonly string[];
+}
+export interface ComponentLibrary {
+    root: string;
+    components: ReadonlyArray<ComponentSpec>;
+    componentGroups?: ReadonlyArray<ComponentGroup>;
+}
+/** Resolve positional args from Aktion into named props. */
+export declare function mapPositionalArgs(spec: ComponentSpec, args: ReadonlyArray<unknown>): Record<string, unknown>;

package/dist/types/library/utils.d.ts

@@ -0,0 +1,73 @@
+import { IconSize } from '../icons/index.js';
+export declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Record<string, string | number | boolean | null | undefined>, children?: ReadonlyArray<Node | string | null | undefined>): HTMLElementTagNameMap[K];
+export declare function text(value: unknown): string;
+export declare function classNames(...parts: Array<string | false | null | undefined>): string;
+export declare function asArray<T>(value: unknown): T[];
+export declare function asString(value: unknown, fallback?: string): string;
+export declare function asBoolean(value: unknown, fallback?: boolean): boolean;
+export declare function asNumber(value: unknown, fallback?: number): number;
+/**
+ * Breakpoint keys honoured by responsive prop maps (Grid columns, Stack
+ * direction, etc.). Ordered from narrow → wide so CSS only needs to chain
+ * one `min-width` per breakpoint and naturally cascades.
+ */
+export declare const RESPONSIVE_BREAKPOINTS: readonly ["base", "sm", "md", "lg", "xl"];
+export type Breakpoint = typeof RESPONSIVE_BREAKPOINTS[number];
+/**
+ * Normalise a prop value that may be a single value or a responsive map
+ * like `{sm: 1, md: 2, lg: 4}`. Returns either:
+ *   - `{kind: "single", value}` — caller should use the value directly
+ *   - `{kind: "responsive", values}` — caller should emit CSS variables /
+ *     data attributes for each breakpoint
+ *
+ * A bare key without a breakpoint prefix (e.g. `{value: 2}`) collapses to
+ * a single-value result. Unknown breakpoint keys are ignored so typos
+ * don't crash the page.
+ */
+export type ResponsiveProp<T> = {
+    kind: "single";
+    value: T | null;
+} | {
+    kind: "responsive";
+    values: Partial<Record<Breakpoint, T>>;
+};
+export declare function readResponsiveProp<T>(value: unknown): ResponsiveProp<T>;
+export declare function sanitiseCssUrl(raw: string): string;
+export declare function sanitiseCssLength(raw: unknown, fallback: string): string;
+/**
+ * Sanitise an LLM-supplied `href` value before it lands on an anchor.
+ *
+ * - Fragments (`#anchor`), root-relative paths (`/about`), and pure query
+ *   strings (`?q=foo`) are kept verbatim.
+ * - Absolute URLs with an allow-listed scheme (`http`, `https`, `mailto`,
+ *   `tel`) are kept verbatim.
+ * - Anything else — `javascript:`, `vbscript:`, `data:text/html`,
+ *   `file:`, protocol-relative `//host/path`, control characters — collapses
+ *   to `fallback` (default `"#"`) so the click never navigates anywhere
+ *   dangerous.
+ *
+ * This is the single chokepoint every component should call before assigning
+ * `href`. The Markdown renderer has its own (stricter, HTML-escaping)
+ * sibling, but the validation rules match so behaviour stays consistent.
+ */
+export declare function sanitiseHref(raw: unknown, fallback?: string): string;
+/**
+ * Sanitise an LLM-supplied image `src` before it lands on an `<img>`.
+ *
+ * Relative paths and same-origin shapes are kept as-is. Absolute URLs with
+ * an allow-listed scheme (`http`, `https`, `data`, `blob`) are kept. Anything
+ * else (`javascript:`, `vbscript:`, `file:`, …) returns the empty string so
+ * callers can render their own placeholder.
+ */
+export declare function sanitiseImageSrc(raw: unknown): string;
+/**
+ * Render an icon-typed prop into an `<i class="rui-icon fa-...">` element.
+ *
+ * Falls back to a `<span>` containing the raw string when the value is not
+ * a Font Awesome name (legacy emoji input). Returns `null` when the value
+ * is empty / nullish so callers can short-circuit.
+ */
+export declare function renderIcon(value: unknown, options?: {
+    className?: string;
+    size?: IconSize | string;
+}): HTMLElement | null;

package/dist/types/library/validate.d.ts

@@ -0,0 +1,27 @@
+import { ParseError, Program } from '../parser/types.js';
+import { ComponentLibrary } from './types.js';
+/**
+ * Combined entry point for hosts: parse the source and merge any
+ * schema-level violations into `program.errors`. The element calls
+ * this so the on-screen error banner surfaces *every* Aktion 0.5
+ * violation, not just the syntactic ones. Returning the
+ * parsed program lets the caller render the committed prefix when
+ * the input still parses cleanly.
+ */
+export declare function validateProgram(source: string, library: ComponentLibrary): Program;
+/**
+ * Schema-as-truth validation (§15).
+ *
+ * Walks a parsed `Program` and returns every Aktion 0.5
+ * schema violation as a `ParseError`. In 0.5 these are **fatal** — the
+ * host should merge them into `program.errors` (see
+ * `validateProgram(source, library)` for the combined entry point) and
+ * surface the error banner instead of rendering. There are no longer
+ * any "advisory warnings" — every legacy v1 surface either:
+ *
+ *   - produces a parser-level migration error at parse time, or
+ *   - produces a schema-validator error here when library knowledge is
+ *     required (multi-positional calls, unknown props, enum mismatches,
+ *     legacy Theme tokens, …).
+ */
+export declare function validateProgramSchema(program: Program, library: ComponentLibrary): ParseError[];

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

@@ -0,0 +1,65 @@
+import { ParseError, Program, Statement } from './types.js';
+export interface FrontierResult {
+    /**
+     * Longest prefix of `source` (line-aligned) where every statement
+     * parsed without errors. Always ends on a newline boundary, or equals
+     * the empty string when no committed prefix exists yet.
+     */
+    committedSource: string;
+    /** Tail of `source` past the committed prefix — the "in-flight" lines. */
+    draftingSource: string;
+    /**
+     * Names declared inside the committed prefix. Top-level identifiers
+     * only — block-local bindings (component params, $state inside a
+     * component body) are not included.
+     */
+    committedBindings: ReadonlyArray<string>;
+    /**
+     * The set `U` (SCC-2): top-level names that appear inside the drafting
+     * tail but have not yet committed. Includes:
+     *
+     *   - Identifiers on the left of an assignment (`foo = …`).
+   *   - State assignments (`$x = …`).
+   *   - Component / effect / action / router declarations.
+     *
+     * Names that only appear as call expressions (`Button(…)`) inside the
+     * drafting tail are not listed — those are dependencies, not bindings.
+     */
+    uncommittedBindings: ReadonlyArray<string>;
+    /**
+     * Statements that parsed cleanly in the committed prefix. Hosts can
+     * walk this list to enumerate the committed surface (components,
+     * effects, actions, endpoints, router declarations) without having to
+     * re-parse.
+     */
+    committedStatements: ReadonlyArray<Statement>;
+    /** Errors reported by the parser. Empty when the whole input parses cleanly. */
+    errors: ReadonlyArray<ParseError>;
+}
+/**
+ * Compute the streaming frontier for `source`. Cheap — runs a single
+ * `parse(source)` pass and walks the resulting statements once.
+ *
+ * Example:
+ *
+ *   const f = computeFrontier(
+ *     "$state count = 0\n" +
+ *     "component Counter() {\n" +
+ *     "  Stack(Te"               // mid-stream: half-written `Text`
+ *   );
+ *   // f.committedBindings = ["count"]
+ *   // f.uncommittedBindings = ["Counter"]
+ *   // f.committedSource ends just before "component Counter() {…"
+ */
+export declare function computeFrontier(source: string): FrontierResult;
+/**
+ * Build a frontier result from an already-parsed program. Exposed so
+ * hosts that already call `parse(...)` once don't have to repeat the
+ * work.
+ */
+export declare function buildFrontier(source: string, program: Program): FrontierResult;
+/**
+ * SCC-3 helper: returns `true` when every name in `deps` lives in the
+ * committed prefix (so a side effect depending on them is safe to fire).
+ */
+export declare function isQuiescent(frontier: FrontierResult, deps: ReadonlyArray<string>): boolean;

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

@@ -0,0 +1,4 @@
+export * from './types.js';
+export { tokenize } from './lexer.js';
+export { parse } from './parser.js';
+export { computeFrontier, buildFrontier, isQuiescent, type FrontierResult, } from './frontier.js';

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

@@ -0,0 +1,46 @@
+/**
+ * Tokenizer for Aktion.
+ *
+ * The language is line-oriented. We tokenize into a flat stream of tokens
+ * including NEWLINE markers so that the parser can recover at line boundaries.
+ */
+export type TokenType = "Identifier" | "Keyword" | "StateIdentifier" | "BuiltinIdentifier" | "Number" | "String"
+/**
+ * Backtick-quoted template literal — carries alternating raw chunks and
+ * embedded expression source strings via `parts`.
+ * `parts[0]` is always a string chunk; positions then alternate between
+ * `{kind:"expr", source}` and `{kind:"str", text}`.
+ */
+ | "TemplateString"
+/**
+ * `js{ … }` opaque block. The body is captured verbatim (with balanced
+ * brace tracking) so it can be passed through to the runtime without
+ * re-parsing.
+ */
+ | "JsBlock" | "Boolean" | "Null" | "Punctuation" | "Operator" | "Newline" | "EOF";
+/**
+ * Keywords reserved by Aktion. The lexer recognises them so the
+ * parser can dispatch on `Keyword` tokens directly instead of second-guessing
+ * every identifier. `$name` is lexed as a `StateIdentifier` token whose
+ * `value` is the bare name; there is only one reactive atom kind so no
+ * additional disambiguation is needed.
+ */
+export declare const KEYWORDS_AKTION: Set<string>;
+export type TemplatePart = {
+    kind: "str";
+    text: string;
+} | {
+    kind: "expr";
+    source: string;
+    line: number;
+    column: number;
+};
+export interface Token {
+    type: TokenType;
+    value: string;
+    line: number;
+    column: number;
+    /** Set on `TemplateString` tokens to carry the alternating parts. */
+    parts?: TemplatePart[];
+}
+export declare function tokenize(source: string): Token[];

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

@@ -0,0 +1,2 @@
+import { Program } from './types.js';
+export declare function parse(source: string): Program;