Liveframe

Runtime-composable UI for apps: people and AI agents install TSX widgets at runtime and the app's UI changes, with no deployment.

An app ships a small set of trusted primitive components and a design system. Widgets are ordinary TSX written against those primitives. Widget code runs on the app's backend; the browser only draws a validated tree with the app's own components, so the UI looks native and no widget code runs in the page.

Four rules, none of them optional:

1. Widget code never runs in the browser. Only the app's compiled primitives run there.
2. The UI tree is data, and it is validated before the renderer reads it.
3. Widget code never sets colours or raw CSS. Look comes from the design system; layout comes from token-constrained style props.
4. A widget never holds authority. Data is resolved and actions are run by the app, as the viewer.

Specification · How a surface is built · Security model · Compatibility · Changelog

Install

bun add @arnilo/liveframe

Each peer is optional and only the subpaths that need it use it:

The backend subpaths (/store/fs, /preview/worker, the in-process package loader and the CLI) need Bun ≥ 1.4.2. The host-API-free subpaths need ES2022 plus only the globals listed below. The browser subpaths (/css, /react, /preview/react, /conformance/react) need any ESM bundler. The package ships compiled ES2022 JavaScript with .d.ts declarations and the published JSON Schemas; spec §13 has the runtime matrix and package contents.

Paths are relative to @arnilo/liveframe; . is the root export. The sdk row includes /sdk/gen and both JSX runtimes; /runner-kit.bundle.js and /validator.bundle.js also need no non-ECMAScript globals. Entries include bundled dependencies: Acorn guards its unused console warning, and the packer's source-map codec optionally uses TextDecoder with a pure JavaScript fallback. Preview timers bound module loading; capture needs the Encoding and URL APIs. Authoring reaches capture. Source, compiled output and browser bundles are checked against this table in CI.

Quickstart

A catalog, its React implementations and a validator are all a surface needs. compileValidator takes the validated catalog, capabilities and manifest for one widget; createRenderer returns the <Surface> that draws a tree it has validated.

import { type Catalog, compileValidator, defineComponent, obj, str, type UiTree } from "@arnilo/liveframe";
import { createRenderer, implement } from "@arnilo/liveframe/react";

const text = defineComponent({
  kind: "text",
  description: "One line of text.",
  props: obj({ value: str({ maxLength: 200 }) }),
  children: "none",
  variants: ["default"],
  defaultVariant: "default",
  slots: ["root"],
  events: {},
  styleProps: [],
  a11y: { role: "paragraph" },
});

const catalog = {
  format: "liveframe-catalog/1",
  catalogId: "acme.ui@1",
  description: "The app's primitives.",
  vocabulary: {
    colourRoles: ["text.primary", "surface.base", "accent.primary"],
    surfaceRoles: ["surface.base"],
    fillableRoles: ["accent.primary"],
    typographyRoles: ["body"],
    space: ["space.1"],
    radius: ["radius.control"],
    size: ["size.glyph"],
    breakpoints: ["bp.sm"],
    tones: { default: "text.primary" },
    surfaceTypography: "body",
  },
  definitions: [text],
} as const satisfies Catalog;

const capabilities = { format: "liveframe-capabilities/1", sources: {}, actions: {} };
const manifest = {
  format: "liveframe-manifest/1",
  id: "hello",
  version: "1.0.0",
  catalogId: catalog.catalogId,
  params: obj({}),
  state: obj({}),
  context: obj({}),
  initialState: {},
  sources: {},
  actions: [],
};

const Text = implement(text, ({ props, slot, style }) => (
  <p className={slot("root")} style={style}>
    {props.value}
  </p>
));
const { Surface } = createRenderer({ catalog, implementations: [Text] });
const validator = compileValidator({ catalog, capabilities, manifest });
const identity = { id: "acme", version: "1.0.0" };

/** Draw a validated tree that the app's backend rendered. */
export function Hello({
  tree,
  onIntent,
}: {
  tree: unknown;
  onIntent: (intent: { type: "setState" | "action" }) => void;
}) {
  return (
    <Surface
      tree={tree}
      validator={validator}
      theme={identity}
      designSystem={identity}
      onIntent={onIntent}
      fallback={null}
    />
  );
}

export const tree: UiTree = {
  format: "liveframe/1",
  catalogId: catalog.catalogId,
  surfaceId: "hello",
  revision: 1,
  root: { id: "root", kind: "text", props: { value: "Hello from Liveframe" } },
};

Widgets are authored separately with the SDK, which exports render() and the JSX runtime and emits the tree Hello receives. The preview guide shows the backend runners that execute widget code, and the package guide shows how a rendered widget becomes an immutable package a host stores and places.

For streaming updates, diffTrees(prev, next) emits an optional liveframe/tree-patch/1 patch on the backend, and the browser host applies it with applyPatch(base, patch) and passes the patched tree to <Surface> (which validates the whole tree on arrival):

import { applyPatch, diffTrees } from "@arnilo/liveframe";

const next = {
  ...tree,
  revision: 2,
  root: { id: "root", kind: "text", props: { value: "Hello again" } },
};
const patch = diffTrees(tree, next);
if (patch.ok) {
  const updated = applyPatch(tree, patch.value);
  if (updated.ok) Hello({ tree: updated.value, onIntent: () => {} });
}

What is in the package

The spec defines each subpath's contract.

Use it with a coding agent

liveframe mcp is an MCP server over stdio that lets a coding agent read your catalog, write a draft widget and look at its renders. It is authoring only: no tool installs, places or approves a widget, or runs an action.

1. Install the optional peers: bun add -d @modelcontextprotocol/server, and bunx playwright install chromium if the agent should capture screenshots.
2. Write a config module that default-exports an AuthoringConfig (your catalog, capabilities, runner and, for captures, a preview(binding) that starts your <Preview> page). examples/demo-host/mcp.config.ts is a working one.
3. Register it with the agent. For Claude Code, put this in .mcp.json in your app; Claude Desktop and other clients use the same mcpServers shape in their own config file:

{ "mcpServers": { "liveframe": { "command": "bunx", "args": ["liveframe", "mcp", "./mcp.config.ts"] } } }

The client starts the server itself. The MCP guide covers the eight tools, captures and errors.

Guides

• The model — what runs where, and who owns each step
• Formats and validation — catalogs, themes, design systems, capabilities, manifests, trees
• Writing widgets — the TSX SDK, intent helpers and liveframe gen
• The renderer — primitives, implementations, <Surface> and intent handling
• Styling — recipes, the three sheets and scoped CSS
• Packages, stores and runners — pack(), fileStore, inProcessRunner, workerRunner
• Preview and capture — preview sessions, <Preview> and liveframe preview capture
• Conformance — the test kit for an app's catalog, styling, renderer and store
• Agent authoring over MCP — liveframe mcp and its eight tools
• Agent walkthrough for the demo — author, capture, install and place a draft
• Security model — what is validated where, and what is not a sandbox
• Compatibility — what a version bump may change

Status

Pre-1.0 (0.2.2 is the current release). The public API, the formats and the on-disk fileStore layout are described by the compatibility policy; the release notes list the known limitations of this release.

Development

bun install
bun run check   # build, generated output, typecheck, lint, format, tests

Repository layout, roadmap and plans: roadmap.md, plans/. Contributing with agents: AGENTS.md. Security reports: SECURITY.md.

License

MIT — see LICENSE.