Web Runtime

@mdanai/sdk/web is the browser-side MDAN runtime. It does not render your UI.

It reads the initial state written into HTML by the server, sends requests, maintains page and block state, and exposes that state to any rendering layer.

If you want one sentence to remember, use this: web is responsible for how interaction continues. Whether you draw the UI yourself is a separate question.

Basic Usage

import { createHeadlessHost } from "@mdanai/sdk/web";

const host = createHeadlessHost({ root: document, fetchImpl: window.fetch });
host.mount();

host.subscribe((snapshot) => {
  console.log(snapshot.route, snapshot.blocks);
});

This is the recommended browser-side path:

• default UI: createHeadlessHost() + mountMdanElements()
• framework UI: createHeadlessHost() + Vue, React, or Svelte rendering

When a framework owns the UI, the recommended interface is:

• host.getSnapshot()
• host.subscribe(listener)
• host.submit(operation, values)
• host.visit(target)

What It Actually Does

After mounting, the runtime will:

• read the initial state from the current HTML document
• send GET and POST actions with the correct MDAN behavior
• merge returned block fragments into current state
• load new page state when a response points at a new page target
• notify any rendering layer through subscribe(listener)

In other words, it is responsible for the interaction process itself, not the visual presentation.

Runtime State

The runtime exposes a small state API:

host.subscribe((snapshot) => {
  console.log(snapshot.status);
});

Current states are:

• idle
• loading
• error

Relationship to elements

• if you want the official default UI, combine createHeadlessHost() with mountMdanElements()
• if you want Vue, React, or another framework to own the UI, keep only createHeadlessHost()

You can think of it as: web runs the interaction, elements displays it.

Browser Debug Messages

If you want to inspect the raw Markdown traffic that the browser sends and receives, enable debug messages when creating the host:

const host = createHeadlessHost({
  root: document,
  fetchImpl: window.fetch,
  debugMessages: true
});

When enabled, the runtime records a small message envelope for each browser-side interaction:

• send or receive
• GET or POST
• request url
• raw markdown

The messages are exposed at:

• window.__MDAN_DEBUG__.messages

If you also use the default elements renderer, the browser will show a small debug drawer so you can inspect those messages without opening devtools state manually.