aktion-runtime 0.5.0

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

@@ -0,0 +1,151 @@
+import { Expression, Program, ComponentDeclaration, EffectDeclaration, ActionDeclaration } from '../parser/types.js';
+import { StateStore } from './state.js';
+import { HttpRuntime } from './http.js';
+import { I18nRuntime } from './i18n.js';
+import { ActionDeclRunner } from './effects.js';
+import { Router } from './router.js';
+import { ComponentLibrary } from '../library/types.js';
+export interface ArgMeta {
+    /** Name of the `$variable` if this argument is a direct state reference. */
+    stateRef?: string;
+}
+export interface ComponentNode {
+    __kind: "Component";
+    /** Component name as written in Aktion. */
+    name: string;
+    /** Positional arguments after evaluation. */
+    args: unknown[];
+    /** Per-position metadata (state ref binding, etc.). */
+    argMeta: ArgMeta[];
+    /**
+     * Explicit `key:` override for content-addressed identity (§13). When
+     * present, the renderer uses this value as the suffix of the instance
+     * path instead of the source location — so reordering siblings keeps
+     * per-instance state attached to the right node.
+     */
+    explicitKey?: unknown;
+    /** Original AST for debugging/introspection. */
+    source?: {
+        line: number;
+        column: number;
+    };
+}
+export declare const isComponentNode: (value: unknown) => value is ComponentNode;
+/**
+ * Lazy node produced when a user-declared `component Foo(p) { ... }` is
+ * called. The renderer expands these per-instance: each instance gets its
+ * own state-alias scope so two `Counter()` calls hold independent `$state`
+ * atoms (§7 — per-instance reactivity).
+ *
+ * The evaluator captures the call arguments + named slots eagerly; the
+ * body itself is evaluated at render-time once the instance key is known.
+ */
+export interface UserComponentNode {
+    __kind: "UserComponent";
+    decl: ComponentDeclaration;
+    /** Positional argument values (already evaluated). */
+    positional: unknown[];
+    /** Named argument values (already evaluated), keyed by param/slot name. */
+    named: Record<string, unknown>;
+    /** Optional `key:` override the caller passed for stable instance identity. */
+    explicitKey?: unknown;
+    source?: {
+        line: number;
+        column: number;
+    };
+}
+export declare const isUserComponentNode: (value: unknown) => value is UserComponentNode;
+export interface EvaluationContext {
+    state: StateStore;
+    /** Per-program scope for non-state assignments (refs to other lines). */
+    bindings: Map<string, () => unknown>;
+    /** Raw AST expressions for each top-level identifier. */
+    expressions: Map<string, Expression>;
+    /** Set of $variable names accessed during the current evaluation. */
+    trackedState: Set<string>;
+    /**
+     * Inline loop variables for expression `for` / `match`, router param
+     * bindings, lambda parameters, and component declaration parameters.
+     */
+    loopVars: Map<string, unknown>;
+    /**
+     * Per-instance state alias scope (§7). When a user-declared component
+     * body declares `$state n = 0`, the renderer pushes an alias frame so
+     * that the StateRef `n` reads/writes the per-instance key (e.g.
+     * `Counter@1:5#0:n`) rather than a shared global atom. The lookup walks
+     * from the top of the stack down — outer frames are still visible when
+     * not overridden.
+     */
+    stateAliases: Array<Map<string, string>>;
+    /** Optional router — exposed to the runtime for `_route_.path` / `params`. */
+    router?: Router;
+    /** Component library used to resolve trailing named-arg object literals. */
+    library?: ComponentLibrary;
+    /** Component declarations from the program (`component Foo() { ... }`). */
+    componentDecls: Map<string, ComponentDeclaration>;
+    /** Effect declarations (`effect [ ...deps ] { ... }`), keyed by auto-generated name. */
+    effectDecls: Map<string, EffectDeclaration>;
+    /** Action declarations (`action Foo() { ... }`). */
+    actionDecls: Map<string, ActionDeclaration>;
+    /** HTTP runtime (`http({...})` calls + interceptor configuration). */
+    http?: HttpRuntime;
+    /** Aktion 0.5 i18n runtime (`$i18n = i18n({...})` declaration + `t()` builtin). */
+    i18n?: I18nRuntime;
+    /** Aktion 0.5 action runner (`action Foo() optimistic { … }` invocations). */
+    actionRunner?: ActionDeclRunner;
+    /** Notify the host that something changed and a re-render is needed. */
+    notify?: () => void;
+    /**
+     * Optional executor for raw `js{ … }` blocks encountered inside an
+     * inline lambda. When set, evaluating a lambda whose body resolves to
+     * a `JsBlock` payload will invoke this with the captured body so
+     * `Button("Hi", action: () => { js{ alert("Hi") } })` actually runs
+     * the script instead of returning the deferred payload.
+     */
+    jsBlockExecutor?: (body: string, args?: Record<string, unknown>) => unknown;
+}
+/**
+ * Optional injectables for `createContext` — the host element passes its
+ * runtime singletons (HTTP, i18n, action runner) so endpoint use sites and
+ * action calls can resolve against them.
+ */
+export interface CreateContextOptions {
+    router?: Router;
+    library?: ComponentLibrary;
+    http?: HttpRuntime;
+    i18n?: I18nRuntime;
+    actionRunner?: ActionDeclRunner;
+    notify?: () => void;
+    jsBlockExecutor?: (body: string, args?: Record<string, unknown>) => unknown;
+}
+/**
+ * Build a top-level evaluation context for a freshly parsed program.
+ */
+export declare function createContext(state: StateStore, options?: CreateContextOptions): EvaluationContext;
+/**
+ * Resolve a `$name` reference through the active per-instance alias
+ * stack. Returns the topmost binding or `name` itself when no alias is
+ * present. Exported so the action / effect runners can resolve writes
+ * the same way the evaluator resolves reads.
+ */
+export declare function resolveStateAlias(ctx: EvaluationContext, name: string): string;
+/**
+ * Plan a program: declare state variables, register HTTP endpoints, and
+ * build lazy bindings for every assignment so forward references resolve.
+ */
+export declare function planProgram(program: Program, ctx: EvaluationContext): void;
+export declare function evaluate(expr: Expression, ctx: EvaluationContext): unknown;
+/**
+ * Evaluate a user-declared component body in a fresh per-instance scope.
+ * Called by the renderer once the stable instance key is known so
+ * `$state` declarations inside the body land in instance-private slots.
+ *
+ * `instanceKey` should be a deterministic string derived from the
+ * render-tree path (and/or the `key:` override) — it becomes the prefix
+ * for every per-instance state atom and effect / action declaration.
+ *
+ * Returns the body's last-expression value (typically a `ComponentNode`
+ * the renderer can hand to the library, or another `UserComponentNode`
+ * to expand recursively).
+ */
+export declare function evaluateUserComponent(node: UserComponentNode, ctx: EvaluationContext, instanceKey: string): unknown;

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

@@ -0,0 +1,85 @@
+import { EvaluationContext } from './evaluator.js';
+export type HttpMethod = "GET" | "HEAD" | "OPTIONS" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface HttpRequest {
+    url: string;
+    method: HttpMethod;
+    headers: Record<string, string>;
+    body?: unknown;
+    signal?: AbortSignal;
+}
+export interface HttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+}
+export interface HttpInterceptors {
+    onRequest?: (request: HttpRequest) => HttpRequest | Promise<HttpRequest>;
+    onResponse?: (response: HttpResponse, retry: () => Promise<HttpResponse>) => HttpResponse | Promise<HttpResponse>;
+    onError?: (error: unknown, request: HttpRequest) => void;
+}
+export interface HttpDefaults {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    retry?: {
+        count: number;
+        backoff?: "linear" | "exponential";
+    };
+    credentials?: RequestCredentials;
+}
+/** Reactive lifecycle of an `http({...})` resource. */
+export type ResourceState = "idle" | "loading" | "data" | "error" | "stale";
+/**
+ * Reactive bag returned by `http({...})`. Fields update in place as
+ * the request progresses; the runtime calls `notify()` so the next
+ * render observes the new values.
+ */
+export interface EndpointResource {
+    state: ResourceState;
+    data: unknown;
+    error: unknown;
+    loading: boolean;
+    status?: number;
+    headers?: Record<string, string>;
+    lastUpdated?: number;
+    refetch: () => Promise<void>;
+    cancel: () => void;
+}
+/** Compatibility shim — subscription transports were removed in this version. */
+export interface SubscriptionTransport {
+    open(url: string, opts: {
+        protocol?: string;
+        headers?: Record<string, string>;
+    }): {
+        onMessage(cb: (raw: unknown) => void): void;
+        onError(cb: (err: unknown) => void): void;
+        onClose(cb: () => void): void;
+        onOpen(cb: () => void): void;
+        send(payload: unknown): void;
+        close(): void;
+    };
+}
+export declare class HttpRuntime {
+    private interceptors;
+    private defaults;
+    setDefaults(defaults: HttpDefaults): void;
+    /** Merge new interceptors on top of any previously-registered ones. */
+    registerInterceptors(interceptors: HttpInterceptors): void;
+    /** Resolve a relative URL against the configured `baseUrl`. */
+    resolveUrl(url: string): string;
+    /**
+     * Issue a single HTTP request. Runs through `onRequest`/`onResponse`
+     * interceptors and surfaces a `retry()` one-shot inside `onResponse`.
+     * Honours `defaults.timeoutMs` via `AbortController`.
+     */
+    request(input: HttpRequest): Promise<HttpResponse>;
+}
+/**
+ * Run a single `http({...})` call and return the reactive resource bag.
+ *
+ * The bag mutates in place: `data`, `error`, `status`, `loading`,
+ * `headers`, `lastUpdated` update during the request lifecycle. The
+ * `refetch()` callback re-issues the original request; `cancel()`
+ * aborts the in-flight request (no-op when idle).
+ */
+export declare function createHttpResource(config: unknown, ctx: EvaluationContext): EndpointResource;

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

@@ -0,0 +1,40 @@
+/**
+ * Aktion 0.5 i18n runtime — `$i18n` declaration + `t()` global builtin (§23).
+ *
+ * The runtime is intentionally tiny:
+ *   - Holds the active locale, fallback locale, and message map.
+ *   - `t(key, vars?)` looks up `key` (dot-paths supported, e.g. `"orders.title"`),
+ *     falls back to the fallback locale's bundle, then to the bare key.
+ *   - `vars?` are interpolated using `${name}` placeholders.
+ *
+ * Locale-aware formatting (`Money`, `Date`, `Number`, `Percent`,
+ * `RelativeTime`) is wired through `getLocale()` so library components
+ * can read the live value without each declaring it as a prop.
+ */
+export interface I18nConfig {
+    locale: string;
+    messages: Record<string, unknown>;
+    fallback?: string;
+    /** Optional secondary message map for the fallback locale. */
+    fallbackMessages?: Record<string, unknown>;
+}
+export declare class I18nRuntime {
+    private locale;
+    private fallback;
+    private messages;
+    private fallbackMessages;
+    configure(config: I18nConfig): void;
+    /** Current active locale tag (e.g. `"en-US"`, `"de"`). */
+    getLocale(): string;
+    /** Snapshot of the configured fallback locale. */
+    getFallback(): string;
+    /**
+     * Translate a dot-pathed key, optionally interpolating `${name}` vars.
+     *
+     * Resolution order:
+     *   1. The active locale's message map.
+     *   2. The fallback locale's message map (if provided separately).
+     *   3. The bare key as a literal string.
+     */
+    t(key: string, vars?: Record<string, unknown>): string;
+}

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

@@ -0,0 +1,9 @@
+export * from './builtins.js';
+export * from './state.js';
+export * from './evaluator.js';
+export * from './router.js';
+export * from './http.js';
+export * from './i18n.js';
+export { storage, type CookieOptions, type StorageNamespace, type StorageRoot } from './storage.js';
+export { consoleNs, type ConsoleNamespace } from './console.js';
+export { EffectRunner, ActionDeclRunner, type EffectRunnerOptions, type ActionRunnerOptions, } from './effects.js';

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

@@ -0,0 +1,105 @@
+/**
+ * Hash-based router for `<aktion-app>`.
+ *
+ * The router is owned by the host element and exposed to:
+ *   - The evaluator (which special-cases `Routes(...)` to pick the matching
+ *     `Route(path, content)` and inject path params as the loop variable
+ *     `params`).
+ *   - The renderer's helpers (so `NavLink(...)` can wire click handlers).
+ *   - The action runner (`@Navigate("/path")` step).
+ *
+ * The wire format is hash-based — `#/page-name`. The router strips the leading
+ * `#` and any trailing `?…` query string before exposing the path. Navigating
+ * inside the component updates `window.location.hash`, and external hash
+ * changes (browser back/forward, direct URL edits) are picked up by the
+ * `hashchange` listener.
+ *
+ * The router is always started by the host element when it connects so that
+ * navigation works out of the box. In environments without a `window`
+ * (server-side rendering, tests) the router stays in "memory" mode:
+ * `navigate(...)` records the new path internally without touching the URL.
+ */
+export type RouteParams = Record<string, string>;
+export interface RouteMatch {
+    matched: boolean;
+    params: RouteParams;
+    /** True when the matched route is a wildcard (`*`) catch-all. */
+    wildcard?: boolean;
+}
+export interface RouteChangeDetail {
+    path: string;
+    previousPath: string | null;
+    source: "init" | "hashchange" | "navigate" | "external";
+}
+export type RouteListener = (detail: RouteChangeDetail) => void;
+export interface RouterOptions {
+    /** Initial path when no hash is set. Defaults to `/`. */
+    defaultPath?: string;
+}
+/**
+ * Normalise an arbitrary string into a clean route path.
+ *
+ *   readHashPath("")                 → "/"
+ *   readHashPath("#")                → "/"
+ *   readHashPath("#/")               → "/"
+ *   readHashPath("#/about")          → "/about"
+ *   readHashPath("#about")           → "/about"
+ *   readHashPath("/foo/bar?x=1")     → "/foo/bar"
+ *   readHashPath("//foo///bar//")    → "/foo/bar"
+ */
+export declare function normalisePath(raw: string | null | undefined): string;
+/**
+ * Match a route pattern against a concrete path. Patterns support:
+ *   - literal segments: `/about`
+ *   - parameter segments: `/users/:id`
+ *   - wildcard catch-all: `*` (matches any path, params empty unless mixed)
+ *   - mixed wildcard: `/docs/*` (matches everything under `/docs/`)
+ */
+export declare function matchRoute(pattern: string, path: string): RouteMatch;
+/**
+ * Singleton-per-element router. Owns the current path, listens for
+ * `hashchange` events when enabled, and notifies subscribers when the path
+ * changes for any reason.
+ */
+export declare class Router {
+    private currentPath;
+    private currentParams;
+    private currentPattern;
+    private enabled;
+    private hashListener;
+    private listeners;
+    private readonly defaultPath;
+    /** True while we're updating `window.location.hash` ourselves — used to
+     * filter out the resulting `hashchange` echo. */
+    private settingHash;
+    constructor(options?: RouterOptions);
+    /**
+     * Attach the `hashchange` listener and synchronise from the current URL.
+     * Safe to call multiple times — it's idempotent.
+     */
+    start(): void;
+    /**
+     * Detach the `hashchange` listener. The current path stays as the last
+     * observed value so a follow-up `start()` resumes cleanly.
+     */
+    stop(): void;
+    getPath(): string;
+    getParams(): RouteParams;
+    /** Path pattern of the most recently matched `Route` (or null). */
+    getActivePattern(): string | null;
+    /**
+     * Called by `Routes(...)` after each render so we have the canonical
+     * pattern + params for the active page (used by `NavLink` to highlight the
+     * active link). The state store is NOT touched here.
+     */
+    setActiveMatch(pattern: string | null, params: RouteParams): void;
+    /**
+     * Navigate to the given path. When enabled, this updates the URL hash and
+     * relies on `hashchange` to notify listeners (so browser history works).
+     * When disabled, the navigation stays in-memory.
+     */
+    navigate(path: string): void;
+    subscribe(listener: RouteListener): () => void;
+    /** Replace the current path without going through `window.location`. */
+    private setPath;
+}

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

@@ -0,0 +1,84 @@
+/**
+ * Lightweight reactive state container.
+ *
+ * Each `$variable` is tracked here. Components and queries subscribe to a
+ * specific set of state names; when any of them changes, their `notify`
+ * callback fires. There are no proxies or Symbols on the user-facing API,
+ * which keeps the surface small and predictable.
+ */
+export type StateValue = unknown;
+export type Subscriber = (changedNames: ReadonlySet<string>) => void;
+/**
+ * Pluggable persistent storage adapter for `$$variable` declarations.
+ *
+ * The default implementation reads/writes JSON-encoded values to the host
+ * page's `localStorage`. Hosts (or tests) can swap it out via
+ * `StateStore.setPersistenceAdapter(...)` — useful for SSR shims or to
+ * scope storage per-element via a custom key prefix.
+ */
+export interface PersistenceAdapter {
+    load(name: string): StateValue | undefined;
+    save(name: string, value: StateValue): void;
+    remove(name: string): void;
+}
+export declare class StateStore {
+    private values;
+    private defaults;
+    /** Persistent variable names — written to the adapter on every change. */
+    private persistent;
+    private persistenceAdapter;
+    private subscribers;
+    private pendingChanges;
+    private flushScheduled;
+    setPersistenceAdapter(adapter: PersistenceAdapter | null): void;
+    declare(name: string, defaultValue: StateValue): void;
+    /**
+     * Declare a persistent `$$variable`. The adapter is queried for an
+     * existing value; if one is found, it replaces the default. Otherwise
+     * the default is written back so the next mount reads the seeded value.
+     */
+    declarePersistent(name: string, defaultValue: StateValue): void;
+    isPersistent(name: string): boolean;
+    has(name: string): boolean;
+    get(name: string): StateValue;
+    set(name: string, value: StateValue): void;
+    /** Iterate over every (name, value) pair. Order is insertion order. */
+    entries(): IterableIterator<[string, StateValue]>;
+    /** Snapshot every (name, value) pair into a plain object. */
+    snapshot(): Record<string, StateValue>;
+    /**
+     * Aktion 0.5 §26 — resumability primitive. Restores
+     * every atom in `snapshot` *without* notifying subscribers, so the
+     * host can seed values before the runtime mounts (SSR hydration,
+     * URL-backed deep links, conversational continuity). Atoms that have
+     * not yet been `declare`d are still written so they show up the
+     * moment the program declares them.
+     *
+     * The persistence adapter is *not* consulted — hydration is
+     * authoritative. If the caller wants persisted reads to win, they
+     * should call `hydrate(snapshot)` before `declare(name, …)`.
+     */
+    hydrate(snapshot: Readonly<Record<string, StateValue>>): void;
+    reset(...names: string[]): void;
+    resetAll(): void;
+    /**
+     * Replace all state entries. Called when a fresh program is loaded.
+     *
+     * Also drops any pending change notifications: their names refer to the
+     * previous program's bindings, which no longer exist, and forwarding them
+     * to subscribers can fire queries / scripts that race against the new
+     * program's planning step.
+     */
+    rebind(declarations: Iterable<[string, StateValue]>): void;
+    subscribe(subscriber: Subscriber): () => void;
+    private scheduleFlush;
+    private flush;
+}
+/**
+ * Build a `PersistenceAdapter` backed by `window.localStorage` (or
+ * `sessionStorage`). The returned adapter namespaces each key by
+ * `keyPrefix` so two elements on the same page don't clobber one
+ * another's `$$variable` values. Returns `null` when no storage is
+ * available (SSR, sandboxed iframes, private mode in some browsers).
+ */
+export declare function createLocalStorageAdapter(keyPrefix: string, storage: Storage | null): PersistenceAdapter | null;

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

@@ -0,0 +1,50 @@
+/**
+ * Browser storage namespace for Aktion.
+ *
+ * Exposes a single `storage` global that wraps three browser storage
+ * mechanisms — `localStorage`, `sessionStorage`, and document cookies —
+ * behind a uniform `set` / `get` / `remove` / `clear` API. Authors can
+ * reach for the default `localStorage` directly (`storage.set("k", "v")`)
+ * or namespace through `storage.local`, `storage.session`, or
+ * `storage.cookies`.
+ *
+ * Values that aren't strings round-trip through `JSON.stringify` /
+ * `JSON.parse`, so authors can persist arrays and objects without manual
+ * serialisation. Failures (quota exceeded, disabled storage, malformed
+ * JSON) are swallowed and reported via the return values rather than
+ * thrown — keeps streaming scripts robust in privacy / SSR contexts
+ * where the underlying APIs may be missing.
+ */
+/** Options accepted by `storage.cookies.set` (mirrors the standard cookie attributes). */
+export interface CookieOptions {
+    /** Days until expiry, or a Date instance for an absolute expiry. */
+    expires?: number | Date | string;
+    /** `Max-Age` in seconds — overrides `expires` when both are set. */
+    maxAge?: number;
+    /** Restrict cookie to the given path (defaults to `/`). */
+    path?: string;
+    /** Restrict cookie to the given domain. */
+    domain?: string;
+    /** Only send over HTTPS. */
+    secure?: boolean;
+    /** `SameSite` policy — `"Strict"`, `"Lax"`, or `"None"`. */
+    sameSite?: "Strict" | "Lax" | "None" | "strict" | "lax" | "none";
+}
+export interface StorageNamespace {
+    set: (key: string, value: unknown, options?: CookieOptions) => boolean;
+    get: (key: string) => unknown;
+    remove: (key: string, options?: CookieOptions) => boolean;
+    clear: () => boolean;
+}
+export interface StorageRoot extends StorageNamespace {
+    local: StorageNamespace;
+    session: StorageNamespace;
+    cookies: StorageNamespace;
+}
+/**
+ * The `storage` global exposed to Aktion programs. Default
+ * methods (`storage.set` / `storage.get` / `storage.remove` /
+ * `storage.clear`) delegate to `localStorage`; nested namespaces select
+ * a specific backend.
+ */
+export declare const storage: StorageRoot;