Runtime

Generate a UI document for an ask with the model you choose, with your Design Direction applied, checked and repaired, streamed, and remembered per intent.

@polyxd/runtime turns an ask into a UI document with the model you choose. It builds the prompt from the spec and your Design Direction, checks the answer, sends any problems back to the model to fix, streams as it goes, and remembers the screen shown for each intent. It uses fetch only and has no model SDK dependencies. It runs in Node, in browsers and in Cloudflare Workers as it is. The spec's schema checks come compiled ahead of time, so nothing turns text into code at run time, which Workers forbid.

It is new in the repository and not on npm yet.

Install#

npm install @polyxd/runtime

A first document#

import { createRuntime, anthropic } from "@polyxd/runtime";

const runtime = createRuntime({
  generator: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
  direction,   // your direction.json
});

const { document, report, attempts, usage } = await runtime.generate({
  ask: "Send £250 to Alex for the rent",
  intent: "money.send",
  capabilities: { "transfer.confirm": registry.capabilities["transfer.confirm"] },
  data: { quote },
});

if (report.valid) {
  // render `document` with @polyxd/react or @polyxd/web, passing the same data
}

capabilities are the ones this surface may trigger, by name, with the same fields as your capability registry. data is what the surface binds to. The document is checked against it.

Choosing a model#

Every model sits behind one small interface: generate({ system, messages, signal, onText }) returns the text and token usage, and calls onText as text streams in. Four adapters come with the package. You pass the key in. The runtime never reads keys from disk or the environment, and never logs them.

import { anthropic, openai, gemini, local } from "@polyxd/runtime";

// Claude, through the Messages API. The model defaults to claude-sonnet-5.
anthropic({ apiKey, model: "claude-sonnet-5", maxTokens: 8192 });

// OpenAI, through Chat Completions (the default) or the Responses API.
openai({ apiKey, model: "your-model-id" });
openai({ apiKey, model: "your-model-id", api: "responses" });

// Google Gemini, through streamGenerateContent. The key goes in a header, not the URL.
gemini({ apiKey, model: "your-model-id" });

// A model on your machine, through an OpenAI-compatible endpoint.
local({ model: "qwen3:8b" });                                          // Ollama, http://localhost:11434/v1
local({ model: "your-model", baseURL: "http://localhost:8080/v1" });   // llama.cpp server
local({ model: "your-model", baseURL: "http://localhost:1234/v1" });   // LM Studio

Every adapter takes baseURL, maxTokens, temperature, headers, and fetch for a proxy or tests. Only anthropic has a default model; the others need model. A refusal or failure throws a GeneratorError with provider and status.

Your own code can be the generator too: anything with a name and a generate method that returns text works.

The prompt#

systemPrompt() is built from the spec when the package is built: the document shape, the rules a generated document follows, every component a surface may use with its props, and the six patterns. The shell components are left out, and one rule says never to use them. The text is the same for every ask, so a provider's prompt cache can hold it. Pass components to createRuntime to offer only the components your product allows; the runtime then checks that too.

userPrompt() holds the ask:

• the ask, the intent, and a pattern if you name one with pattern;
• the capabilities on offer, each with its risk, its inputs (required ones marked) and its undo;
• the data as JSON, and the JSON Pointers it offers, with lists described once by their items' fields;
• the Design Direction (see below);
• the screen shown last time for this intent, when you use memory.

The same input always gives the same text. await runtime.prompt(ask) returns exactly what the first model call would send, for inspection and tests.

The Design Direction at generation#

Pass direction to createRuntime. These parts reach the model:

profile.motion isn't given to the model, since a document holds no motion. patterns.custom files aren't read yet.

The Direction's rules and its compiled voice are also checked on every answer (see below), the same checks directionRules gives the verifier.

Checks and repair#

Each answer is parsed first. A code fence, or a sentence before the JSON, is tolerated. Then it is checked:

• Everywhere: checkDocument runs the verifier's document checks, staticAudit from @polyxd/verifier/static. That is the spec validator (with the Direction's emphasisBudget, and every binding checked against your data), the checks of the pattern the document declares, the capabilities on offer, the Direction's rules and compiled voice, and the verifier's agent-readiness checks: distinct control names, labels that say what happens, no template placeholders, and the rest. They read no files and load no browser, so they run anywhere the runtime does.
• Generated only: the document is never a shell (generated:shell), uses only the allowed components (generated:component), and follows no disallowed pattern (direction:pattern-disallowed).
• Your own: pass audit to use your own checks instead of checkDocument. It gets the same options staticAudit takes. The generated-only checks still run.

const runtime = createRuntime({ generator, direction, audit: (doc, options) => myChecks(doc, options) });

If an answer has errors, the model gets it back with each problem listed and is asked for the whole document again. That happens up to maxRepairs times (default 2). Warnings don't trigger a repair unless you set repairWarnings: true, and even then a document with only warnings is accepted on the last attempt.

The result is { document, report, attempts, usage }. report has valid, errors, warnings and the findings. usage adds up input and output tokens across attempts. When the runtime gives up, report.valid is false and document is the last answer that parsed, so you can show a fallback.

Streaming#

for await (const p of runtime.stream(ask)) {
  if (p.type === "text") appendToPreview(p.text);
  if (p.type === "attempt" && !p.report.valid) showChecking();
  if (p.type === "done") show(p.result.document);
  if (p.type === "error") showFallback(p.reason);
}

Leaving the loop early aborts the model call. runtime.generate(ask, { onProgress }) gives the same items to a callback. Pass signal in the ask to cancel either.

Memory#

Interface memory keeps the screen shown for each intent, on the client, so asking again gives a screen the person recognises.

import { createRuntime, storageStore } from "@polyxd/runtime";

const runtime = createRuntime({ generator, direction, memory: storageStore(localStorage) });

When a document passes, it is stored by its ask's intent, without its data. The next ask with that intent sends it to the model with the instruction to keep its keys, structure, order and labels, and to change only what the new ask needs. memoryStore() keeps screens in memory instead. Any object with get, set and delete can be a store. The runtime makes no network calls for memory. A store that fails to write doesn't fail the document.

Events and privacy#

onEvent is for your own analytics. It receives the same six moments with numbers only:

checks holds check ids such as spec or rule:money-moves-in-confirm, never their messages. No event carries the ask, the data or the document. A hook that throws never breaks generation. The package sends no telemetry anywhere.

In the demos#

The demos have a live path built on this package. When an ask matches nothing in a product's verified library, the site's Worker can run createRuntime with that product's Design Direction, its own low-risk capabilities and its seed data, and stream the result back. A screen that passes shows with a "Generated just now" mark; one that still fails after repair is "not yet". The browser keeps interface memory with storageStore(localStorage), so asking again for the same thing sends last time's screen with it.

The path is off on polyxd.com. It stays off until the site has a model key, so the public demos answer from their library only. apps/demos/README.md says how an operator turns it on.

Everything it exports#

Polyxd is an early preview. Found something unclear? It will get better with your feedback.