aktion-runtime 0.5.0

package/dist/types/tooling/codemod.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Aktion 0.5 §27 — automatic v1 → 0.5 source codemod.
+ *
+ * The migration helper accepts a *v1* source string and returns a
+ * best-effort *0.5* equivalent, plus a list of advisory notes describing
+ * each transformation. The codemod targets the legacy surfaces enumerated
+ * in `language-update-final.md` Appendix A; surfaces that have no clean
+ * textual rewrite (e.g. `Action([@Set, …])`'s open-ended payload DSL)
+ * surface a note pointing the author at the manual migration path.
+ *
+ * Why a text codemod rather than an AST-to-AST one? The v1 grammar is
+ * accepted as a hard parse error by the current parser (the legacy
+ * `name=value`, `$$x` sigil, `Name(args) = expr` macros, etc. all raise
+ * definitive errors). Re-introducing v1 syntax just to round-trip
+ * through the parser would defeat the purpose of removing it — and a
+ * focused set of regexes handles the line-oriented transforms cleanly
+ * because the v1 grammar is itself line-oriented.
+ *
+ * The codemod is idempotent: feeding its output back through `migrateV1`
+ * is a no-op.
+ */
+export interface MigrateV1Result {
+    /** Best-effort 0.5 source. */
+    source: string;
+    /** Human-readable record of every transform that fired, in source order. */
+    notes: string[];
+    /** Hand-migration hints for surfaces that have no clean text rewrite. */
+    manualMigrations: string[];
+}
+/**
+ * Run the v1 → 0.5 codemod on `source`. The transform is best-effort:
+ * unmigratable surfaces produce a `manualMigrations` note instead of an
+ * automatic rewrite, so the caller knows which lines still need a human
+ * touch.
+ */
+export declare function migrateV1(source: string): MigrateV1Result;

package/dist/types/tooling/delta.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Aktion 0.5 §14 — Delta Protocol.
+ *
+ * In v1 every LLM turn replaced the entire program. SUIS/2 ships a
+ * structured delta surface so a "tweak the UI" turn can stay tiny:
+ * a handful of typed operations applied to the previous program's
+ * Committed AST. The runtime mounts the patched program with the
+ * user's `$state` preserved across the diff.
+ *
+ * The spec's original pragma signalling (`#sus/2 delta`) was retired
+ * along with every other pragma in 0.5 (`#…` lines are comments). The
+ * delta is therefore expressed as **structured operations** — hosts
+ * call `el.applyDelta(ops)` directly, no in-language pragma required.
+ *
+ * Operations
+ * ----------
+ *
+ *   { kind: "patch", target: "stateName", value: 50 }
+ *     Update a `$state` atom in place. Does not touch the program
+ *     text. Use for "set the slider to 50", "expand the panel", etc.
+ *
+ *   { kind: "replace", binding: "header", source: "PageHeader(\"Sales\")" }
+ *     Replace a top-level binding's RHS. Equivalent to deleting and
+ *     re-emitting the line(s).
+ *
+ *   { kind: "append", binding: "items", item: "{ label: \"Reports\" }" }
+ *     Append an item to a top-level array binding. `binding`'s RHS
+ *     must be a literal array expression.
+ *
+ *   { kind: "new", source: "component ReportCard(r) { Card([Text(r.title)]) }" }
+ *     Append a new top-level statement to the program.
+ *
+ *   { kind: "delete", binding: "legacyWidget" }
+ *     Remove a top-level binding (or component / action / effect /
+ *     endpoint declaration) by name.
+ *
+ * Op application is best-effort: each op that does not match its
+ * target surfaces an advisory warning and is skipped. The runtime
+ * still mounts the rest of the patched program — partial deltas
+ * never strand the user with no UI.
+ *
+ * The function is pure: feed in `(source, ops)`, get back
+ * `(programText, stateUpdates, warnings)`. State application is the
+ * caller's responsibility (the host element wires it up — see
+ * `AktionElement.applyDelta`).
+ */
+export type DeltaOp = {
+    kind: "patch";
+    target: string;
+    value: unknown;
+} | {
+    kind: "replace";
+    binding: string;
+    source: string;
+} | {
+    kind: "append";
+    binding: string;
+    item: string;
+} | {
+    kind: "new";
+    source: string;
+} | {
+    kind: "delete";
+    binding: string;
+};
+export interface DeltaResult {
+    /** Source text after every structural op (replace/append/new/delete) lands. */
+    programText: string;
+    /** `patch` ops collected as a name→value map; the caller applies these to its state store. */
+    stateUpdates: Record<string, unknown>;
+    /** Advisory diagnostics for ops that became no-ops. */
+    warnings: string[];
+}
+export declare function applyDelta(source: string, ops: readonly DeltaOp[]): DeltaResult;

package/dist/types/tooling/formatter.d.ts

@@ -0,0 +1,8 @@
+import { ParseError } from '../parser/types.js';
+export interface FormatResult {
+    /** Canonical source. Equal to the input when parse errors occur. */
+    formatted: string;
+    /** Parse errors raised while reading the input — formatting is a no-op when non-empty. */
+    errors: ParseError[];
+}
+export declare function formatProgram(source: string): FormatResult;

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

@@ -0,0 +1,29 @@
+/**
+ * Tooling surface (§27) — host-side helpers projected from the schema.
+ *
+ * The pieces ship as a separate entry so library consumers can opt in
+ * without paying for them at runtime. Each helper is pure: feed in
+ * source / AST / library, get diagnostics, canonical source, or a
+ * structured AST view back.
+ *
+ * Surfaces
+ * --------
+ *
+ *   - `formatProgram(source)` — canonical pretty-printer.
+ *   - `applyDelta(source, ops)` — structured edit protocol (§14).
+ *   - `migrateV1(source)` — best-effort v1 → 0.5 codemod (Appendix A).
+ *   - `inspectAST(source)` — Committed + Drafting AST snapshot.
+ *   - `getDiagnostics(source, library)` — language-service diagnostics.
+ *   - `getCompletions(source, position, library)` — completions.
+ *   - `getHoverInfo(source, position, library)` — hover docs.
+ */
+export { formatProgram } from './formatter.js';
+export type { FormatResult } from './formatter.js';
+export { applyDelta } from './delta.js';
+export type { DeltaOp, DeltaResult } from './delta.js';
+export { migrateV1 } from './codemod.js';
+export type { MigrateV1Result } from './codemod.js';
+export { inspectAST, inspectProgram } from './inspector.js';
+export type { InspectorBinding, InspectorView } from './inspector.js';
+export { getDiagnostics, getCompletions, getHoverInfo, } from './language-service.js';
+export type { Position, Diagnostic, CompletionItem, HoverInfo, } from './language-service.js';

package/dist/types/tooling/inspector.d.ts

@@ -0,0 +1,49 @@
+import { Program } from '../parser/types.js';
+export interface InspectorBinding {
+    /** Top-level name (e.g. `root`, `count`, `Header`). */
+    name: string;
+    /** What kind of declaration introduced this binding. */
+    kind: "assignment" | "component" | "effect" | "action" | "router";
+    /** Source line (1-indexed). */
+    line: number;
+    /** Source column (1-indexed). */
+    column: number;
+    /** Brief textual summary (callee name for assignments, endpoint method, …). */
+    summary?: string;
+}
+export interface InspectorView {
+    /** Committed prefix that has already parsed cleanly. */
+    committed: {
+        source: string;
+        bindings: InspectorBinding[];
+        statementCount: number;
+    };
+    /** Drafting tail past the committed frontier. */
+    drafting: {
+        source: string;
+        bindings: InspectorBinding[];
+        statementCount: number;
+        /** SCC-2 — names declared in the drafting tail but not yet committed. */
+        inFlightNames: string[];
+    };
+    /** Parse errors (if any). Empty when the whole input parses cleanly. */
+    errors: ReadonlyArray<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+    /** Total number of declared bindings across both ASTs. */
+    totalBindings: number;
+}
+/**
+ * Inspect `source` and return a JSON-friendly view of the Committed +
+ * Drafting ASTs. Cheap — runs a single `parse` pass via
+ * `computeFrontier`.
+ */
+export declare function inspectAST(source: string): InspectorView;
+/**
+ * Build a view directly from a parsed `Program`. Useful for hosts that
+ * have already paid the parse cost and just need the structured
+ * projection.
+ */
+export declare function inspectProgram(source: string, program: Program): InspectorView;

package/dist/types/tooling/language-service.d.ts

@@ -0,0 +1,57 @@
+import { ComponentLibrary } from '../library/types.js';
+export interface Position {
+    /** 1-indexed line number. */
+    line: number;
+    /** 1-indexed column number. */
+    column: number;
+}
+export interface Diagnostic {
+    line: number;
+    column: number;
+    message: string;
+    /** `error` when the program will not render; `warning` is reserved for the future. */
+    severity: "error" | "warning";
+}
+export interface CompletionItem {
+    /** Insertion text (the user types this to accept). */
+    label: string;
+    /**
+     * What kind of symbol this is. Useful when the host wants to render
+     * different icons per kind (LSP / editor UIs typically display these).
+     */
+    kind: "component" | "prop" | "state" | "builtin" | "keyword";
+    /** Short textual description. */
+    detail?: string;
+    /** Long-form documentation surfaced in a tooltip. */
+    documentation?: string;
+}
+export interface HoverInfo {
+    /** Markdown-friendly text rendered in the hover popup. */
+    contents: string;
+    /** Symbol kind for clients that prefer typed surfaces. */
+    kind: "component" | "prop" | "state" | "builtin" | "unknown";
+}
+/**
+ * Combine parse-level + schema-level diagnostics into one list. Every
+ * entry has a `severity` field so editors can theme errors vs warnings
+ * (in 0.5 every entry is currently `error` — there are no soft
+ * warnings — but the surface stays future-proof).
+ */
+export declare function getDiagnostics(source: string, library: ComponentLibrary): Diagnostic[];
+/**
+ * Completion items for the cursor position `position`. Heuristics are
+ * intentionally simple — the prompt + the closed schema (§16) make
+ * deep static analysis unnecessary:
+ *
+ *   - Inside `(...)` after a known component name → the spec's prop
+ *     names (filtered to unconsumed props).
+ *   - After `$` → state-tier keywords (`$state`, `$persist`, …).
+ *   - At top of line / inside a block → top-level keywords + the
+ *     full library component list.
+ */
+export declare function getCompletions(source: string, position: Position, library: ComponentLibrary): CompletionItem[];
+/**
+ * Hover info for the symbol under the cursor. Returns `null` when the
+ * cursor is not over a recognised symbol.
+ */
+export declare function getHoverInfo(source: string, position: Position, library: ComponentLibrary): HoverInfo | null;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "aktion-runtime",
+  "version": "0.5.0",
+  "description": "Aktion is a single web component that turns a compact, streaming-first DSL into a rich, interactive UI inside its shadow DOM. Works in React, Vue, Angular, Svelte, plain HTML — or no framework at all.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./style.css": "./dist/aktion.css",
+    "./system_prompt.txt": "./dist/system_prompt.txt",
+    "./system_prompt_chat.txt": "./dist/system_prompt_chat.txt"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -p tsconfig.build.json && vite build && node scripts/emit-prompt.mjs && node scripts/emit-entry.mjs",
+    "build:lib": "vite build",
+    "build:prompt": "node scripts/emit-prompt.mjs",
+    "build:entry": "node scripts/emit-entry.mjs",
+    "build:docs": "node scripts/build-docs.mjs",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vite": "^5.4.10",
+    "vite-plugin-dts": "^4.3.0",
+    "vitest": "^2.1.4",
+    "@vitest/web-worker": "^2.1.4",
+    "happy-dom": "^15.7.4"
+  },
+  "keywords": [
+    "llm",
+    "ai",
+    "web-components",
+    "aktion",
+    "generative-ui",
+    "rich-ui",
+    "custom-elements"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asfand-dev/aktion.git"
+  },
+  "homepage": "https://asfand-dev.github.io/aktion/",
+  "bugs": {
+    "url": "https://github.com/asfand-dev/aktion/issues"
+  },
+  "license": "MIT"
+}