Third-party widgets & interop.

Why these exist

Aktion components render declaratively: you describe the tree, the runtime reconciles the DOM, and it reuses + patches nodes on every re-render to preserve focus, scroll, and form state. That is exactly wrong for a widget that builds its own DOM — a chart canvas, a map’s tile layers, an editor’s document. If the reconciler touched those nodes it would corrupt or destroy the widget mid-session.

The interop primitives solve this in one move: the host element they create is marked data-rui-preserve, which tells the reconciler “this subtree is owned by imperative code — never reconcile its children or reset its form state.” Aktion keeps flowing its own attributes (a reactive sx / class) but otherwise leaves the live node alone. You get reactive data binding around a widget that fully owns the DOM inside.

Mount — managed imperative widgets

Mount({ setup, update?, cleanup?, props?, tag?, deps?, onError? }) is the managed host for any imperative widget. Aktion creates the host element; you fill it and react to prop changes through a clean three-phase lifecycle. setup is the only required prop.

chart = Mount({
  tag: "div",                          // host element (default "div")
  sx: { h: "320px" },                  // layout the host like any component
  setup: (node, props) => {            // runs ONCE after the host attaches
    return new Chart(node, props.config)  //   → return the instance handle
  },
  update: (instance, props) => {       // runs when `props` change (compared structurally)
    instance.data = props.data
    instance.update()
  },
  cleanup: (instance) => instance.destroy(),  // runs on unmount
  onError: (err, stage) => $failed = true,    // stage is "setup" or "update"
  props: { config: $cfg, data: $series }      // reactive bag handed to setup/update
})

Everything after setup is optional, but a widget that allocates anything — a canvas context, a websocket, a global listener — needs cleanup or it outlives the component.

The lifecycle contract

All three hooks run on a microtask, never inside the reconcile pass, so your widget code always sees an attached DOM node and can safely trigger state changes of its own.

• props is the reactive boundary. Bind $state into props and update fires whenever any value changes — that is how the outside world drives the widget. Reading state inside setup / update is fine too.
• The host is never rebuilt. Because the host is preserved, re-renders never re-run setup or recreate the element — the widget instance lives for the whole session.
• setup waits for a connected host. If a commit hands the reconciler a host it discards in favour of an incumbent element, setup simply retries on the next commit rather than initialising your widget inside a detached node. Each host carries a stable data-rui-key so the live element stays findable.
• A throwing hook does not take the app down. The error is logged and handed to onError(err, stage) if you supplied one — render a fallback from state there rather than letting a failed map or payment element leave an empty box.

When update runs

The DSL rebuilds every object and array literal on each evaluation, so comparing the props bag by reference would fire update on every unrelated keystroke in the app. Aktion compares it structurally, four levels deep instead: plain objects and arrays are walked, and anything else — a widget handle, a class instance, a DOM node — is compared by identity.

$series = [12, 19, 7, 15]
$clicks = 0

function SalesChart() {
  return Mount({
    sx: { h: "240px" },
    // `config` is a brand-new literal on every render. A reference compare
    // would re-run `update` whenever $clicks changed; the structural compare
    // sees identical contents and skips it.
    props: { config: { type: "bar", data: { values: $series } } },
    setup: (node, props) => new Chart(node, props.config),
    update: (chart, props) => chart.setOption(props.config),
    cleanup: (chart) => chart.destroy()
  })
}

$app(Column([
  SalesChart(),
  Row([
    // Re-renders the app, but the chart's props are unchanged → no `update`.
    Button(`Unrelated re-render (${$clicks})`, { onClick: () => $clicks = $clicks + 1 }),
    // New numbers inside `data.values` → `update` runs once.
    Button("Shuffle data", { onClick: () => $series = $series.map(() => Math.round(Math.random() * 20)) })
  ], { gap: "sm" })
]))

Two cases defeat the structural compare, and both are what deps is for: data nested deeper than four levels, and a mutation made in place ($series.push(1)) that leaves the structure comparing equal. Pass an explicit list and props stops being consulted for the decision:

chart = Mount({
  setup: (node, props) => new Chart(node, props.config),
  update: (chart, props) => chart.setOption(props.config),
  cleanup: (chart) => chart.destroy(),
  props: { config: $deeplyNestedConfig },
  deps: [$revision]                     // bump $revision to force an update
})

With deps present, update runs exactly when a value in the list changes — props is still handed to the callback, it just no longer decides whether the callback fires.

Live: a self-contained canvas

No external library needed — setup grabs the canvas 2D context and draws. This is the whole pattern in miniature: Aktion owns the <canvas>, your code owns the pixels.

$app(Column([
  Text("Drawn by an imperative Mount:", { sx: { weight: "600" } }),
  Mount({
    tag: "canvas",
    sx: { w: "100%", h: "140px", radius: "md" },
    setup: (node) => {
      node.width = 600; node.height = 280
      ctx = node.getContext("2d")
      ctx.fillStyle = "#6366f1"
      ctx.fillRect(20, 20, 200, 90)
      ctx.fillStyle = "#22c55e"
      ctx.beginPath()
      ctx.arc(360, 120, 70, 0, Math.PI * 2)
      ctx.fill()
      return ctx
    }
  })
]))

Full example: Chart.js with reactive data

Load the library with $script, gate the Mount on it being ready, then push reactive series in through props:

$chartjs = $script({ src: "https://cdn.jsdelivr.net/npm/chart.js", global: "Chart" })
$series  = [12, 19, 7, 15]

function SalesChart() {
  if (!$chartjs.ready) {
    return Skeleton({ sx: { h: "320px" } })   // graceful loading state
  }
  return Mount({
    sx: { h: "320px" },
    setup: (node, props) => new $chartjs.value(node, {
      type: "bar",
      data: { labels: ["Q1","Q2","Q3","Q4"], datasets: [{ data: props.series }] }
    }),
    update: (chart, props) => {
      chart.data.datasets[0].data = props.series
      chart.update()
    },
    cleanup: (chart) => chart.destroy(),
    props: { series: $series }
  })
}

$app(Column([
  SalesChart(),
  Button("Shuffle", { onClick: () => $series = $series.map(() => Math.round(Math.random() * 20)) })
]))

WebComponent — native custom elements

Many third-party widgets already ship as custom elements (<stripe-pricing-table>, <model-viewer>, a design-system element). WebComponent(tag, { attributes?, properties?, on?, children? }) renders and hydrates one with reactive attributes, rich JS properties, and event hooks.

widget = WebComponent("stripe-pricing-table", {
  attributes: {                         // reactive — re-applied on $state change
    "pricing-table-id": $id,
    "publishable-key":  $pk
  },
  on: {                                 // listeners stay current across renders
    "checkout": e => route.navigate("/thanks")
  }
})

Use attributes for simple string-ish values and properties when the element exposes a rich property API:

viewer = WebComponent("model-viewer", {
  attributes: { src: $modelUrl, "camera-controls": true, ar: true },
  properties: { cameraOrbit: $orbit },   // a rich, non-string property
  on: { "load": () => $loaded = true }
})

What is filtered

attributes and properties both land on a real DOM node, so both are filtered before they are applied. Your element’s own attributes and properties pass through untouched — only names the platform already owns are affected.

The practical consequence: set a URL through attributes: { src: $url }, where it is sanitised, not through properties, where it is refused. Style the element with sx rather than a style property, and slot markup with children rather than an innerHTML property — WebComponent("x", { properties: { innerHTML: … } }) would otherwise be a direct script-execution sink. The reasoning behind each list is on Security & the trust model.

$script — load an external SDK once

$script({ src, global? }) loads an external UMD/ESM script (or stylesheet) exactly once per src across the whole app, and returns a reactive bag you gate your UI on.

$stripe = $script({ src: "https://js.stripe.com/v3/", global: "Stripe" })
// → { ready, loading, error, value }   (value = window.Stripe once loaded)

The canonical pattern is “don’t render the widget until its SDK exists”, with an explicit branch for the failure case:

$maps = $script({ src: "https://maps.example.com/sdk.js", global: "MapSDK" })

function MapView() {
  if ($maps.error)  return Alert("Map failed to load", { variant: "danger" })
  if (!$maps.ready) return Spinner()
  return Mount({
    sx: { h: "400px" },
    setup: (node) => new $maps.value.Map(node, { center: [0, 0], zoom: 2 }),
    cleanup: (map) => map.remove()
  })
}

Branch on .error first, then .ready: every way a load can fail — a network error, a rejected URL, a disabled $script — sets .error and leaves .ready false, so a program written this way degrades instead of rendering nothing.

On the server (renderToString) there is no DOM to inject into, so the bag stays { ready: false, error: null } and your UI falls back to the loading branch — exactly what you want for an SSR placeholder that hydrates on the client.

Which URLs are accepted

$script exists to load a real external file, so src must be an http: / https: URL or a same-origin path. Control characters are stripped before the check.

A rejected src does not throw. The bag comes back with ready: false and error set to:

[aktion] $script requires a `src` that is an http(s) or same-origin URL.

So the symptom is a widget stuck on its loading branch. When that happens, read the bag’s .error — $maps.error above — before suspecting the network.

$script and the global access policy

$script downloads and executes remote code, which is exactly what a host narrowing the runtime’s global surface is trying to prevent. So it is disabled outright — not merely restricted — whenever the host has called setGlobalAccessPolicy with anything other than the default "all".

// Host bootstrap, before mounting the app:
import { setGlobalAccessPolicy } from "aktion-runtime";
setGlobalAccessPolicy("safe");    // → every $script in every program now fails

No request is made and the bag returns immediately with ready: false and this error:

[aktion] $script is disabled because a restricted global access policy is active (see setGlobalAccessPolicy). It loads and executes remote code.

$dom — managed observers

Migrating resize / intersection / mutation logic usually means hand-rolling an observer plus its teardown in an $effect. The $dom namespace does the bookkeeping: every observer it creates is auto-disposed on re-plan / unmount, and each method returns a disposer so you can stop early.

Each callback also re-renders the app, so writing state from inside one is the normal way to surface a measurement. If the node is not an element — or the browser lacks that observer — you get a no-op disposer instead of an exception, so a defensive guard is unnecessary.

Pair these with a node reference from OnMount or a Mount host:

$w = 0
$app(OnMount(
  Box([ Text(`Container width: ${$w}px`, { sx: { weight: "600" } }) ], { sx: { p: "20px" } }),
  { onMount: (node) => $dom.onResize(node, ({ width }) => $w = Math.round(width)) }
))

$seen = false

// Lazy-load an image / fire analytics when a section scrolls into view:
$app(OnMount(Box([ Text("Reveal me") ]), {
  onMount: (node) => {
    $dom.onIntersect(node, (entry) => {
      if (entry.isIntersecting) $seen = true
    }, { threshold: 0.25 })                  // fires once 25% is visible

    // One-shot measurement, no observer:
    size = $dom.measure(node)                // → { rect, scroll, viewport }
  }
}))

Declaring $seen up front matters: an undeclared identifier reads as null rather than raising, so a typo in an observer callback fails silently. measure is a plain read — call it whenever you need current geometry instead of subscribing.

How preservation works (and SSR)

Every interop host carries data-rui-preserve. On each commit Aktion re-renders the whole tree and reconciles it against the live DOM; a node carrying that flag on either side of the diff takes a reduced path instead of the normal one.

That is what lets a chart keep its canvas while you restyle its wrapper: a reactive sx, class, or data-* still flows in, and nothing flows out.

Because the widget’s DOM is built imperatively on the client, interop hosts render as an empty placeholder during renderToString and come alive on hydration. Combine that with a !ready loading branch and your SSR output is a clean skeleton that fills in client-side — see Production & deployment.

Recipes

Monaco editor with two-way binding

$monaco = $script({ src: "https://cdn.example.com/monaco/loader.js", global: "monaco" })
$code   = "function hi() {}"

function Editor() {
  if (!$monaco.ready) return Skeleton({ sx: { h: "300px" } })
  return Mount({
    sx: { h: "300px", border: true, radius: "md" },
    setup: (node, props) => {
      ed = $monaco.value.editor.create(node, { value: props.value, language: "javascript" })
      ed.onDidChangeModelContent(() => $code = ed.getValue())
      return ed
    },
    update: (ed, props) => { if (props.value !== ed.getValue()) ed.setValue(props.value) },
    cleanup: (ed) => ed.dispose(),
    props: { value: $code }
  })
}

The update guard is the important line: without the props.value !== ed.getValue() check, every keystroke would write the editor’s own value back into it and reset the caret.

Stripe payment element

$stripe = $script({ src: "https://js.stripe.com/v3/", global: "Stripe" })

function Checkout() {
  if (!$stripe.ready) return Spinner()
  return Mount({
    sx: { minH: "60px" },
    setup: (node, props) => {
      stripe = $stripe.value(props.pk)
      elements = stripe.elements({ clientSecret: props.secret })
      card = elements.create("payment")
      card.mount(node)
      return { stripe, elements, card }
    },
    cleanup: (inst) => inst.card.destroy(),
    props: { pk: $publishableKey, secret: $clientSecret }
  })
}

Returning the whole { stripe, elements, card } triple is the pattern to copy when teardown needs more than one handle — cleanup receives exactly what setup returned.

Mount vs. WebComponent vs. OnMount

All three hand you a live DOM node; they differ in how much bookkeeping they do for you. Pick the least powerful one that fits.

Next