TypeScript guide.

Install & tsconfig

Install the runtime and the declarations come with it — there is no separate @types package to add, and no build step to run:

npm install aktion-runtime
# types ship in the package; there is no @types/aktion-runtime

That one dependency carries the custom element, the 282-component library, the SSR helpers, and every type on this page. What it will not do is resolve under a legacy module-resolution mode, because the package publishes its subpaths through an exports map:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",           // or "NodeNext", with "module": "NodeNext"
    "lib": ["ES2022", "DOM", "DOM.Iterable"], // DOM is required — see the table
    "strict": true
  }
}

Those are the settings this package’s own build uses, and they are the smallest set that makes every entry point type-check. Only three of them actually matter:

Typed .aktion imports

The Vite plugin lets you import a .aktion file directly. Add one reference line to any .d.ts and those imports stop being any:

/// <reference types="aktion-runtime/aktion-modules" />

With that in place, import app from "./app.aktion" is typed as the CompiledProgram the plugin emits — exactly what element.mountCompiled(app) expects. The /aktion-modules entry is declarations only; there is nothing to import from it at runtime.

Package entry points

The package exposes typed subpath entries. Import from the one that matches your task — splitting them is what keeps a CI lint step from pulling in the DOM:

Only aktion-runtime and aktion-runtime/vite ship a CommonJS build; the rest are ESM‑only.

The public types

These are the declarations a host integration actually names. Everything else in the bundle is reachable, but this table is the surface worth importing deliberately:

GlobalAccessPolicy is the one worth reaching for early. If the program text can come from somewhere you do not fully trust, narrow the global surface before the first render:

import { setGlobalAccessPolicy } from "aktion-runtime";
import type { GlobalAccessPolicy } from "aktion-runtime";

const policy: GlobalAccessPolicy = "safe"; // "all" is the default — full globalThis
setGlobalAccessPolicy(policy);             // data + formatting + encoding only

"safe" drops code execution, DOM, network, and storage from the passthrough; an explicit array grants exactly the names you list and nothing else. Security owns the full trust model.

Typing the host element

<aktion-app> is a custom element, and the package augments HTMLElementTagNameMap for it. That means you do not need a cast — both querySelector and createElement already return AktionElement:

import "aktion-runtime"; // side-effect import: defines the element

const app = document.querySelector("aktion-app"); // AktionElement | null — no cast
app?.setResponse(source);      // replace the whole program
app?.appendChunk(tokenDelta);  // append a streaming tail
app?.setTheme("mui-dark");     // a built-in name, or a Partial<ThemeTokens> map

Import the package for its side effect before you query, or the element is still an HTMLUnknownElement at runtime. The methods and accessors you are most likely to reach for:

const warnings = app.applyDelta([
  { kind: "replace", binding: "count", source: "$count = 5" },
]); // string[] — advisory notes for ops that became no-ops

The other op kinds are patch ({ target, value }), append ({ binding, item }), new ({ source }), and delete ({ binding }). A partial delta always mounts the rest of the patched program rather than throwing.

Host event payloads

The element dispatches three built-in CustomEvents, plus whatever a program raises with $emit. All of them are bubbles: true and composed: true, so a listener on an ancestor sees them:

The package does not ship an event map, because the fourth row is open‑ended. Declare one for the events your host cares about and hang a small generic helper off it — that is the single place a cast is needed, and you write it once:

interface AktionEventMap {
  "assistant-message": { message: string };
  "route-change": {
    path: string;
    previousPath: string | null;
    source: "init" | "hashchange" | "navigate" | "external";
  };
  "error": { errors: { line: number; column: number; message: string }[] };
  // add your own $emit names here
}

function onAktion<K extends keyof AktionEventMap>(
  el: EventTarget,
  type: K,
  handler: (detail: AktionEventMap[K]) => void,
): () => void {
  const listener = (e: Event) => handler((e as CustomEvent<AktionEventMap[K]>).detail);
  el.addEventListener(type, listener);
  return () => el.removeEventListener(type, listener); // call to unsubscribe
}

Every call site now gets autocompletion on the event name and a correctly-typed detail, with the returned function as the unsubscribe:

const off = onAktion(app, "assistant-message", (detail) => sendToModel(detail.message));
onAktion(app, "route-change", (detail) => analytics.page(detail.path, detail.source));
onAktion(app, "error", (detail) => detail.errors.forEach(reportError));

off(); // detach the assistant-message listener

Typing custom components

A custom built‑in is a ComponentSpec. Its render is (node, props, helpers) => Node: props arrives as Record<string, unknown> because the DSL is untyped, so narrow each value as you read it.

import "aktion-runtime";
import type { ComponentSpec } from "aktion-runtime";

const SVG_NS = "http://www.w3.org/2000/svg";

export const Sparkline: ComponentSpec = {
  name: "Sparkline",
  description: "Inline trend line for a series of numbers.",
  props: [
    { name: "values", type: "number[]", positional: true, required: true, description: "The series to plot" },
    { name: "stroke", type: "string", optional: true, description: "Line colour (default: the theme primary token)" },
  ],
  render: (_node, props) => {
    const values = (props.values as number[] | undefined) ?? [];
    const stroke = (props.stroke as string | undefined) ?? "var(--rui-color-primary)";
    // createElement("svg") builds an HTMLUnknownElement that never paints — SVG needs the namespace.
    const svg = document.createElementNS(SVG_NS, "svg");
    svg.setAttribute("viewBox", "0 0 100 24");
    svg.setAttribute("role", "img");
    const max = Math.max(1, ...values);
    const step = 100 / Math.max(1, values.length - 1);
    const line = document.createElementNS(SVG_NS, "polyline");
    line.setAttribute("fill", "none");
    line.setAttribute("stroke", stroke);
    line.setAttribute("stroke-width", "2");
    line.setAttribute("points", values.map((v, i) => `${i * step},${24 - (v / max) * 24}`).join(" "));
    svg.append(line);
    return svg;
  },
};

const app = document.querySelector("aktion-app")!;
app.registerComponents([Sparkline]); // the next getSystemPrompt() advertises it

Reading a theme token through var(--rui-color-primary) rather than a literal colour is what keeps a custom component in step with whichever theme the host applied.

The props array is a PropSpec[]. Every field is consumed by three different systems — the evaluator (argument binding), the validator (unknown-prop errors), and the prompt generator — so filling them in is not documentation, it is behaviour:

The helpers argument is fully typed too — renderNode, invoke, setState, resetState, useInstanceState, registerDisposer, and router all carry signatures, so authoring a spec stays type-safe end to end.

Typing HTTP interceptors

Register host‑wide HTTP hooks with registerHttpInterceptors(interceptors). They fire around every $http / $query / $mutation request the program makes, which makes them the right place for auth headers and centralised logging:

import type { HttpInterceptors } from "aktion-runtime";

const interceptors: HttpInterceptors = {
  onRequest: (req) => ({
    ...req,
    headers: { ...req.headers, Authorization: `Bearer ${getToken()}` },
  }),
  onResponse: async (res, retry) => (res.status === 401 ? retry() : res),
  onError: (err, req) => console.error("[http]", req.url, err),
};

app.registerHttpInterceptors(interceptors); // merges with anything already registered

Merging is incremental, so a later call passing only onRequest never clears an existing onResponse. HttpRequest is { url, method, headers, body?, signal?, init? } and HttpResponse is { status, headers, body } — init is the passthrough for any extra fetch option. See HTTP for the program-side view.

The language & tooling surface

aktion-runtime/language is DOM‑free: it parses, validates, formats, and answers editor questions about program text without touching the renderer. Use it for a CI lint step, a Monaco/LSP integration, or a pre-commit formatter.

import { getDiagnostics, formatProgram, defaultLibrary } from "aktion-runtime/language";
import type { Diagnostic, FormatResult } from "aktion-runtime/language";

const diagnostics: Diagnostic[] = getDiagnostics(source, defaultLibrary);
const blocking = diagnostics.filter((d) => d.severity === "error");

const result: FormatResult = formatProgram(source);
if (result.errors.length === 0) writeFileSync(path, result.formatted);

Note the second argument: getDiagnostics, getCompletions, and getHoverInfo all take a ComponentLibrary, because what counts as an unknown component depends on which one is active. Pass defaultLibrary, or the result of mergeLibraries when the host registers custom specs. Formatting is a no‑op when errors is non-empty, so guard on it before overwriting a file.

SSR, importer & DX exports

The main entry also carries server‑rendering and authoring‑tool helpers, all fully typed:

renderToString returns four fields, not two. Dropping head and headAttrs is what silently loses your <title>, meta tags, and Open Graph cards from the served page:

import { renderToString } from "aktion-runtime";

const { html, state, head, headAttrs } = renderToString(source, { path: "/" });

const attrs = Object.entries(headAttrs).map(([k, v]) => `${k}="${v}"`).join(" ");
const page = `<!doctype html>
<html ${attrs}>
  <head>${head}</head>
  <body>
    ${html}
    <script type="application/json" id="aktion-state">${JSON.stringify(state)}</script>
  </body>
</html>`;

Ship state to the browser and hand it to element.loadSnapshot({ programText, state }) so hydration starts from the server’s values. Head owns the head / headAttrs fields; Deployment covers the serving side.

The testing entry (aktion-runtime/test) additionally exports within(node) for scoped queries and axe(node) for an accessibility audit — both typed (see Testing and Accessibility).

A typed host wrapper

A small wrapper centralises element creation, streaming, and listener cleanup for any framework host. Because createElement is already typed, the whole thing stays cast‑free except for the one detail read:

import "aktion-runtime";
import type { AktionElement } from "aktion-runtime";

export interface AktionHost {
  el: AktionElement;
  stream(delta: string): void;
  reset(full: string): void;
  dispose(): void;
}

export function mountAktion(parent: HTMLElement): AktionHost {
  const el = document.createElement("aktion-app"); // AktionElement — no cast
  parent.append(el);
  const onError = (e: Event) => {
    const { errors } = (e as CustomEvent<{ errors: { message: string }[] }>).detail;
    errors.forEach((x) => console.error("[aktion]", x.message));
  };
  el.addEventListener("error", onError);
  return {
    el,
    stream: (delta) => el.appendChunk(delta),
    reset: (full) => el.setResponse(full),
    dispose: () => { el.removeEventListener("error", onError); el.remove(); },
  };
}

Returning dispose matters more than it looks: a framework that remounts — React strict mode, an HMR boundary, a route change — will call it, and an un-removed error listener is the usual source of duplicate console noise.

Rules of thumb

• Set moduleResolution to bundler or nodenext first — every other import problem on this page is downstream of that one setting.
• Do not cast querySelector("aktion-app"). The tag‑name map is augmented for you; a cast only hides the moment the import goes missing.
• Declare one AktionEventMap per host and never cast e.detail at a call site again.
• Narrow props inside a render with as T | undefined plus a default. The DSL cannot guarantee a type, so the spec is a hint, not a contract.
• Destructure all four fields from renderToString. Ignoring head is a silent SEO regression, not a type error.
• Reach for aktion-runtime/language in CI. It needs no DOM, so a lint step costs no happy‑dom setup.

Next