Frameworks.

Vue 3

Tell the Vue compiler that aktion-app is a custom element so it stops trying to resolve it as a Vue component — set app.config.compilerOptions.isCustomElement (or the equivalent option in your build tool's Vue plugin). Then bind the program with :response, or grab a ref and call setResponse.

// main.ts
import { createApp } from "vue";
import App from "./App.vue";
import "aktion-runtime"; // registers <aktion-app> once
import { setGlobalAccessPolicy } from "aktion-runtime";

// Once, before `app.mount(...)`. Process-global: one call covers every
// <aktion-app> in the app. Omit it to keep the default "all" policy.
setGlobalAccessPolicy("safe");

const app = createApp(App);
// Treat any <aktion-app> tag as a native custom element.
app.config.compilerOptions.isCustomElement = (tag) => tag === "aktion-app";
app.mount("#app");

isCustomElement is a compiler option, so it only applies to templates your build compiles. If a template is compiled at runtime, set the same option on the runtime compiler, or Vue logs a “failed to resolve component” warning and renders nothing.

<!-- App.vue -->
<script setup lang="ts">
import { ref, onMounted, watch } from "vue";
import type { AktionElement } from "aktion-runtime";

const program = ref(`$app(Card([CardHeader("Hello from Vue")]))`);

// Simplest case: bind it directly.
// <aktion-app :response="program" theme="light" />

// Or use a ref for the imperative API + events:
const el = ref<AktionElement | null>(null);
onMounted(() => {
  el.value?.setResponse(program.value);
  el.value?.addEventListener("route-change", (e) =>
    console.log((e as CustomEvent).detail),
  );
});
watch(program, (next) => el.value?.setResponse(next));
</script>

<template>
  <aktion-app ref="el" theme="light" />
</template>

:response works either way Vue chooses to write it: the element exposes response as an accessor whose setter forwards to setResponse(), and it also observes the response attribute. Reach for the ref when you need the rest of the API — appendChunk(), setTheme(), or the events.

Svelte

Svelte supports custom elements natively, so there is no configuration step — just import the bundle and use the tag. Pass the program with the response attribute and subscribe to events with Svelte's on: directive (it maps straight to addEventListener, which is what you want for hyphenated custom event names).

Set the access policy in the client entry, not in a component. A component module runs the first time that component is imported, which is not reliably before the first <aktion-app> mounts; the policy is process‑global, so one call in the entry is both sufficient and correctly ordered.

// src/main.ts — or +layout.ts / hooks.client.ts in SvelteKit
import { setGlobalAccessPolicy } from "aktion-runtime";

// Once, before any component mounts. Omit to keep the default "all".
setGlobalAccessPolicy("safe");

<!-- AktionView.svelte -->
<script lang="ts">
  import "aktion-runtime"; // registers <aktion-app> once

  export let program: string = `$app(Card([CardHeader("Hello from Svelte")]))`;

  function onAssistantMessage(e: CustomEvent) {
    console.log("follow-up:", e.detail.message);
  }
</script>

<aktion-app
  response={program}
  theme="light"
  on:assistant-message={onAssistantMessage}
  on:route-change={(e) => console.log(e.detail)}
/>

Because the tag is a plain custom element, response={program} re‑renders whenever program changes — no watcher needed. For server‑rendered routes (SvelteKit), guard the import so it only runs in the browser, e.g. if (browser) await import("aktion-runtime");, since defining a custom element requires customElements.

Angular

Add CUSTOM_ELEMENTS_SCHEMA to the component (or module) so Angular's template compiler accepts the unknown tag, import the bundle once, and bind the program with the [attr.response] attribute binding.

Call setGlobalAccessPolicy in main.ts, above bootstrapApplication. It is process‑global rather than per‑<aktion-app>, so it does not belong in a provider or a component constructor — there is nothing per‑instance to configure, and a constructor runs too late for the first mount.

// main.ts
import "aktion-runtime"; // registers <aktion-app> once
import { setGlobalAccessPolicy } from "aktion-runtime";
import { bootstrapApplication } from "@angular/platform-browser";
import { AppComponent } from "./app/app.component";

// Once, before bootstrap. Omit to keep the default "all" policy.
setGlobalAccessPolicy("safe");

bootstrapApplication(AppComponent);

// app.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";

@Component({
  standalone: true,
  selector: "app-root",
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <aktion-app
      [attr.response]="program"
      theme="light"
      (assistant-message)="onMessage($event)"
      (route-change)="onRoute($event)"
      (error)="onError($event)">
    </aktion-app>
  `,
})
export class AppComponent {
  program = `$app(Card([CardHeader("Hello, Angular")]))`;

  onMessage(event: Event) {
    console.log("follow-up:", (event as CustomEvent).detail.message);
  }
  onRoute(event: Event) {
    console.log("route:", (event as CustomEvent).detail);
  }
  onError(event: Event) {
    console.warn("aktion errors:", (event as CustomEvent).detail.errors);
  }
}

Angular's () syntax binds by event name, so the hyphenated assistant-message and route-change names work unchanged — do not camel‑case them. Note that (error) also fires for a failed src fetch or link, not only for parse errors, and that a static theme="light" needs no binding at all.

Vanilla HTML

No build step required. A single module‑type script tag imports the bundle (registering the element); then place the <aktion-app> tag and call setResponse.

<!doctype html>
<html>
  <body>
    <aktion-app theme="light"></aktion-app>

    <script type="module">
      import { setGlobalAccessPolicy } from "https://asfand-dev.github.io/aktion/dist/aktion.js";

      // Once, before the first setResponse. Omit to keep the default "all".
      setGlobalAccessPolicy("safe");

      const el = document.querySelector("aktion-app");
      el.setResponse(`$app(Card([CardHeader("Hello, world")]))`);

      el.addEventListener("assistant-message", (e) => {
        console.log("follow-up:", e.detail.message);
      });
    </script>
  </body>
</html>

Importing any named export from the bundle registers the element as a side effect, so there is no separate import "…" line to remember. The policy call goes above setResponse() — it is process‑global and only affects programs that run after it.

You can also set the program declaratively with the response attribute — <aktion-app response="$app(Text(&quot;Hi&quot;))"></aktion-app> — though the imperative setResponse is easier for anything longer than a line.

For anything larger, keep the program in its own file and load it with the src attribute — <aktion-app src="./app.aktion"></aktion-app>. The file is resolved relative to the page and linked through the in‑browser project linker, so an entry that imports other modules fetches its whole graph on connect.