streaming-ui-script

A framework-agnostic web component that renders LLM-generated UI from Streaming UI Script — a compact, declarative language designed for chat assistants. Drop one <script> tag and one <streaming-ui-script> tag into any HTML page — React, Vue, Angular, Svelte, plain HTML, or no framework at all — and you have a streaming, interactive renderer for an LLM's response.

• Live docs: https://asfand-dev.github.io/streaming-ui-script/
• Live examples catalog (chat, dashboards, commerce, inbox, CRM, pricing, routing, status, checkout, files, calendar, docs…): https://asfand-dev.github.io/streaming-ui-script/live-examples.html
• CDN bundle (ESM): https://asfand-dev.github.io/streaming-ui-script/dist/streaming-ui-script.js
• System prompt (full): https://asfand-dev.github.io/streaming-ui-script/dist/system_prompt.txt
• System prompt (chat): https://asfand-dev.github.io/streaming-ui-script/dist/system_prompt_chat.txt

The library bundles everything needed at runtime:

• A Streaming UI Script parser (line-oriented, streaming-first, error-tolerant) with single-, double-, and backtick-quoted strings.
• An evaluator with reactive state, queries, mutations, actions, and 20+ built-in functions (@Count, @Filter, @Sort, @Push, @Concat, @Each, @Sum, @Avg, @Min, @Max, @Round, @Floor, @Ceil, @Abs, …) plus array shortcuts (.length, .first, .last, and field pluck like $rows.title).
• A React-like DOM reconciler that diffs each re-render against the live DOM — text-input value, selection, IME state, scroll positions, <details>.open, and stateful primitives like Tabs are all preserved across renders. Components that need to hold UI state get a helpers.useInstanceState(...) slot keyed by their position in the tree.
• A rich component library of 100+ components — layout, content, forms (including Slider, NumberInput, DatePicker, FileUpload, Combobox), tables, charts, feedback & media (Avatar, Progress, Tooltip, HoverCard, Popover, Toast, Toasts, Rating, ProgressRing, ChatBubble, …), navigation (Breadcrumb, Pagination, Navbar, NavbarItem), menus (DropdownMenu, MenuItem, MenuSeparator, MenuLabel), hierarchical data (Tree, TreeNode), chat composites, high-level pattern composites (Hero, Cover, PageHeader, MetricGrid, Toolbar, EmptyState, Timeline, KanbanBoard, Testimonial, PricingTable, MediaCard, …) and app-shell composites (AppShell, Sidebar, SplitView) that render a full SaaS layout in one statement.
• A built-in JavaScript layer — Script(...) (lifecycle-managed, useEffect-style) and @Js(body, args?) (one-shot click handlers with per-item arg capture). Always available.
• A built-in routing layer — Routes(...), Route(path, content), NavLink(label, to), @Navigate("/path"), and reactive $route + params. Hash-based, framework-agnostic, always on.
• Seven built-in themes (light, dark, neon, pastel, glass, brutalist, skyline) plus full custom-token support via CSS custom properties.
• A system prompt generator that emits a clean, ordered prompt teaching the LLM exactly which components, builtins, and tools are available. The build emits two flavours: system_prompt.txt (full — every feature) and system_prompt_chat.txt (compact — only the surfaces a chat reply needs).

Everything lives inside a Shadow DOM, so the renderer's styles never leak into your application — and your application's styles never leak into the renderer.

Why?

LLMs are great at writing structured text, and a small DSL lets them describe a full UI in 60–70% fewer tokens than JSON. This project ships that idea as a single web component, so any framework — or no framework at all — can render generative UI without extra wiring.

Quick start

1. Add the script tag

<script type="module" src="https://asfand-dev.github.io/streaming-ui-script/dist/streaming-ui-script.js"></script>

For non-module setups use the IIFE build:

<script src="https://asfand-dev.github.io/streaming-ui-script/dist/streaming-ui-script.iife.js" defer></script>

The CSS is bundled inside the JS and injected into each instance's shadow root, so you do not need a separate stylesheet.

2. Mount the tag

<streaming-ui-script id="reply" theme="light"></streaming-ui-script>

3. Render a response

There are three equivalent ways to set the program text:

<!-- as an attribute -->
<streaming-ui-script response='root = Card([CardHeader("Hi")])'></streaming-ui-script>

<!-- as inner text -->
<streaming-ui-script>
  root = Card([CardHeader("Hi")])
</streaming-ui-script>

<!-- as a property / method -->
<script>
  const el = document.querySelector("streaming-ui-script");
  el.setResponse(`root = Stack([greeting])
greeting = Card([CardHeader("Hello", "Generative UI in plain HTML")])`);
</script>

4. Stream from your LLM

const response = await fetch("/api/chat", {
  method: "POST",
  body: JSON.stringify({ system: systemPrompt, messages }),
});
const reader = response.body.getReader();
const decoder = new TextDecoder();
el.streaming = true;
el.clear();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  el.appendChunk(decoder.decode(value, { stream: true }));
}
el.streaming = false;

5. Send the system prompt to your LLM

Either fetch the auto-generated system_prompt.txt from the CDN:

const systemPrompt = await fetch(
  "https://asfand-dev.github.io/streaming-ui-script/dist/system_prompt.txt",
).then((r) => r.text());

…or build a richer prompt programmatically (with custom rules, tool descriptions, examples, etc.):

const prompt = el.getSystemPrompt({
  preamble: "You are an analytics assistant.",
  additionalRules: ["Always end with a FollowUpBlock of 2 prompts."],
  tools: [{ name: "list_orders", description: "Return recent orders.", argsExample: { limit: 10 } }],
});

6. (Optional) Provide tools

el.setTools({
  list_orders: async ({ limit }) => fetch(`/api/orders?limit=${limit}`).then(r => r.json()),
  update_order: async ({ id, status }) => fetch(`/api/orders/${id}`, { method: "PATCH", body: JSON.stringify({ status }) }).then(r => r.json()),
});

7. (Optional) Listen for assistant messages

el.addEventListener("assistant-message", (event) => {
  appendUserMessageToChat(event.detail.message);
});

Public API

All members live on the <streaming-ui-script> element.

Attributes

Script(...) / @Js(...) and hash-based routing (Routes, Route, NavLink, @Navigate) are always on. To skip them in the generated prompt, build the chat-flavoured prompt via getSystemPrompt({ mode: "chat" }).

Properties

Methods

Events

The error event always fires regardless of showerrors, so host apps can log or report errors even when the in-page banner is suppressed.

Themes

Seven themes are built in. Pick one with theme="..." or pass a custom token map.

Custom token maps:

el.setTheme({
  colorPrimary: "#16a34a",
  colorPrimaryHover: "#15803d",
  colorBg: "#f0fdf4",
  radiusMd: "14px",
});

You can also style the host element from outside:

streaming-ui-script {
  --rui-color-primary: #16a34a;
  --rui-radius-md: 14px;
}

A full list of tokens lives in docs/themes.html and src/theme/index.ts.

Icons (Font Awesome)

The runtime auto-loads Font Awesome 6.7.2 from the public CDN — once into document.head and once into each instance's shadow root. Host apps do not need to add a stylesheet.

• Icon strings are Font Awesome names without the fa- prefix: "house", "chart-line", "star", "cart-shopping", "circle-check", "triangle-exclamation", "sack-dollar".
• Optional variant prefix: "regular:star", "brands:github". The default variant is solid.
• Use the dedicated Icon(name, variant?, size?) component to render a standalone glyph (size ∈ xs, sm, md, lg, xl).
• Every component prop named icon — NavLink, SidebarItem, Banner, Notification, FeatureItem, Tag, StatCard, ListItem, TimelineItem, DescriptionItem, Tile, EmptyState, … — now expects a Font Awesome name (or a variant:name string).
• ProgressRing(value, max?, label?, …) renders label as an icon when it resolves to a Font Awesome name (e.g. "circle-check"), and as plain text otherwise — perfect for completion rings.
• Invisible Unicode glyph modifiers (variation selectors, ZWJ) are stripped silently so "triangle-exclamation\uFE0F" (a legacy emoji leftover) still resolves to the proper icon instead of falling back to inline text.

brandIcon  = Icon("rocket", "solid", "lg")
homeIcon   = Icon("house")
profileTab = NavLink("Profile", "/profile", "ghost", false, "user")
kpis       = MetricGrid([
  StatCard("Revenue", "$48k", "up",   "+12%", "sack-dollar"),
  StatCard("Orders",  "1,284","up",   "+8%",  "cart-shopping"),
  StatCard("Refunds", "12",   "down", "-3",   "rotate-left")
])

The CDN URL and a tiny ensureFontAwesomeLoaded(shadow) helper live in src/icons/index.ts and are re-exported as FONT_AWESOME_CDN_URL. The custom element calls the helper from its connectedCallback (idempotent — safe to mount multiple instances).

Streaming UI Script in 60 seconds

$days = "7"
data = Query("get_metrics", {days: $days}, {events: 0, daily: []})
filter = FormControl("Range", Select("days", [SelectItem("7","7d"), SelectItem("30","30d")], null, null, $days))
kpi = StatCard("Events", "" + data.events, "up")
chart = LineChart(data.daily.day, [Series("Events", data.daily.events)])
root = Stack([CardHeader("Analytics"), filter, kpi, chart])

Highlights:

• One statement per line: name = Expression.
• $variables are reactive — passing one to an Input or Select two-way-binds.
• Strings come in three flavours: "double", 'single', and `backtick` (multi-line, no escaping required — perfect for JS bodies).
• Comments are stripped silently: // line, # line (shell-style), and /* block */.
• Query("tool", {args}, {defaults}, refreshSec?) runs immediately and re-runs when its $variable args change.
• Mutation("tool", {...}) only runs from @Run(name) inside an Action([...]).
• @Each(arr, "row", template) iterates inline. The loop variable is scoped strictly to template.
• @Filter, @Sort, @Count, @Sum, @Avg, @Round, @Push, @Concat and more are available.
• Array shortcuts: $rows.length, $rows.first, $rows.last, plus pluck ($rows.title → [title1, title2, …]).
• Forward references are allowed — list root = Stack([...]) first and let the children stream in beneath it.

Build a todo app declaratively (no JS required for add/delete)

$todos = [{id: 1, text: "Welcome — try editing", done: false}]
$draft = ""

addBtn = Button("Add", Action([
  @Set($todos, @Push($todos, {id: $todos.length + 1, text: $draft, done: false})),
  @Reset($draft)
]), "primary")

row = Card([Stack([
  TextContent(t.text),
  Button("Delete", Action([@Set($todos, @Filter($todos, "id", "!=", t.id))]), "ghost")
])])

list = @Each($todos, "t", row)
root = Stack([Input("draft-input", "What needs doing?", "text", null, $draft), addBtn, list])

The full reference is on the docs site (docs/language.html).

JavaScript interactions

Script(...) and @Js(...) ship with every renderer — no attribute to flip. The LLM can author two surfaces whenever the full prompt is in use:

• Script("id", body, deps?) — behaviour-only node that runs on mount and re-runs whenever any listed $variable changes. Lifecycle matches useEffect: cleanup before re-run, disposal on unmount, AbortSignal exposed as ctx.signal.
• @Js(body, args?) — action step you drop inside Action([...]). The optional args object is evaluated at render time and exposed inside the body as ctx.args. This is the canonical way to feed per-row data from an @Each loop into a click handler.

<streaming-ui-script></streaming-ui-script>

list = @Each($todos, "t", row)
row = Card([Stack([
  TextContent(t.text),
  Button("Toggle", Action([
    @Js(`
      const todos = ctx.state.get('todos') || [];
      ctx.state.set('todos', todos.map(x => x.id === ctx.args.id ? Object.assign({}, x, {done: !x.done}) : x));
    `, {id: t.id})
  ]))
])])

body is a regular string. Use double quotes for one-liners (escape inner " as \" and newlines as \n) or backticks for multi-line code (real newlines and unescaped " are fine). The default (full) system prompt teaches the LLM about these features; for chat-style replies where you want to keep the LLM purely declarative, build the prompt via getSystemPrompt({ mode: "chat" }) — the chat flavour omits the JS section.

See the JavaScript interactions guide or the deeper coding-gen-skill.md for a full end-to-end app walkthrough.

Routing

Hash-based routing is built into the runtime. The LLM may emit routes that stay in sync with the URL (#/dashboard, #/users/42). Browser back/forward, bookmarks, and deep links all work — and the host page never reloads.

<streaming-ui-script></streaming-ui-script>

root = Stack([nav, main])

nav = Stack([
  NavLink("Home",     "/",          "ghost", true),
  NavLink("Dashboard","/dashboard", "ghost"),
  NavLink("Users",    "/users",     "ghost")
], "row", "s")

main = Routes([
  Route("/",           homePage),
  Route("/dashboard",  dashboardPage),
  Route("/users/:id",  userPage),
  Route("*",           notFoundPage)
], "/")

homePage      = Card([CardHeader("Welcome")])
dashboardPage = Card([CardHeader("Dashboard")])
userPage      = Card([CardHeader("User " + params.id)])
notFoundPage  = Callout("warning", "Not found", "We couldn't find " + $route + ".")

• Routes(items, default?) picks the matching Route based on the current hash path. First match wins; default is the fallback when nothing else matches.
• Route(path, content) supports literal segments ("/about"), parameter segments ("/users/:id" → params.id), and trailing wildcards ("/docs/*" → params._).
• NavLink(label, to, variant?, exact?, icon?) is a router-aware anchor that intercepts clicks and reflects data-active="true" for the current path.
• @Navigate("/path") is an action step you can drop into any Action([...]) for programmatic navigation. From JS, call el.navigate("/path").
• The current path is exposed reactively as $route. Inside a matched route's content, the captured params land in the params loop variable.

The default (full) system prompt teaches the LLM about routing. To skip the routing section (e.g. for chat-style replies where you don't want the model inventing URLs), build the prompt via getSystemPrompt({ mode: "chat" }).

See the routing guide and the live routing demo for a full end-to-end walkthrough.

Built-in components

Rich pattern composites

The Patterns group is the secret sauce for getting beautiful, dense UI out of an LLM with minimal tokens. Each composite packs an entire idiom (hero, page header, KPI strip, empty state, timeline, kanban, …) into one positional call. Reach for these before composing the equivalent layout from Card + Stack:

root = Stack([dashHeader, kpis, board, follow])
dashHeader = PageHeader("Engineering Q3", "12 active · 4 at risk", ["Workspace", "Engineering"], dashActions, Badge("On track", "success"))
dashActions = [Button("Export", Action([@Run(export_q3)]), "secondary"), Button("New project", Action([@Run(new_project)]), "primary")]
kpis = MetricGrid([StatCard("Active", "12", "flat"), StatCard("At risk", "4", "up", "+2"), StatCard("Shipped", "8", "up", "+3"), StatCard("On-time", "87%", "down", "-3%")])
board = KanbanBoard([
  KanbanColumn("To do",      [KanbanCard("Migrate auth", "Roll out new SDK.", ["auth"], "Asha")]),
  KanbanColumn("Doing",      [KanbanCard("Streaming UI v2", "20 new components.", ["frontend"], "Alex", "primary")]),
  KanbanColumn("Review",     [KanbanCard("Mobile onboarding", "Awaiting design.", ["mobile"], "Wren", "warning")]),
  KanbanColumn("Done",       [KanbanCard("Activity timeline", "Shipped to 100%.", ["shipped"], "Mira", "success")])
])
follow = FollowUpBlock(["Show at-risk projects", "Compare to Q2", "Who needs help?"])

The generated system prompt teaches the LLM about every component, and the ## Design principles + ## Composition recipes sections steer the model toward dashboard / landing / detail-page layouts that look like a shadcn site out of the box.

Add your own with registerComponents:

const ProductCard = {
  name: "ProductCard",
  description: "Product tile with title and price.",
  props: [
    { name: "title", type: "string" },
    { name: "price", type: "number" },
  ],
  render: (_node, props) => {
    const div = document.createElement("div");
    div.textContent = `${props.title} — $${props.price}`;
    return div;
  },
};

el.registerComponents([ProductCard]);

The next call to getSystemPrompt() automatically includes the new component.

LLM integration helper

If you're driving the renderer from an agentic LLM (Cursor, Claude Code, etc.) one companion document is kept in sync with the bundle:

• coding-gen-skill.md — an extensive knowledge base for building complete applications in Streaming UI Script: mental model, every component group, state management, queries/mutations, actions, loops, JavaScript interactions, routing, app patterns (todo list, dashboard, wizard, chat, settings, real-time, status page, checkout flow, file manager, calendar, docs portal), and anti-patterns. Treat it as the "deep dive" the model can read once and then author full apps unaided. It also opens with a short "When to reach for this library" section so agents can decide quickly whether <streaming-ui-script> is the right tool for the job.

Documentation site

The docs/ folder is the source for the live documentation site published at https://asfand-dev.github.io/streaming-ui-script/. Every page is a static HTML file that loads the same bundle the rest of the world consumes from the CDN.

Live examples

Every standalone demo is a single HTML page that you can open directly. They double as integration recipes — view source on any of them to see how a real host page wires setResponse, appendChunk, setTools, and setTheme.

The full catalog with tag filters lives at docs/live-examples.html.

Project layout

.
├── src/                       # Library source
│   ├── parser/                # Lexer, parser, AST types
│   ├── runtime/               # Evaluator, reactive state, queries, actions,
│   │   ├── builtins.ts        #   builtin @-functions and action-step markers
│   │   ├── evaluator.ts       #   program planner + binding resolver
│   │   ├── state.ts           #   reactive store (subscribers, two-way binds)
│   │   ├── queries.ts         #   Query / Mutation registry + auto-refresh
│   │   ├── actions.ts         #   ActionRunner (@Run, @Set, @Reset, …)
│   │   ├── scripts.ts         #   ScriptRunner — useEffect-style Script(...)
│   │   └── router.ts          #   Hash-based router for Routes / NavLink
│   ├── library/               # Component specs and registry
│   │   └── components/        #   layout / content / forms / data / charts /
│   │                          #   chat / feedback / navigation / menu /
│   │                          #   patterns / scripts / router
│   ├── renderer/              # Tree → DOM
│   │   ├── renderer.ts        #   walks the tree, calls component renderers,
│   │   │                      #   tracks per-instance state by tree path
│   │   └── morph.ts           #   React-like DOM reconciler — keeps focus,
│   │                          #   selection, scroll, and <details>.open
│   ├── theme/                 # Token system + injected stylesheet
│   │   ├── index.ts           #   Seven built-in themes + custom token merge
│   │   └── styles.ts          #   Shadow-DOM stylesheet (theme-aware)
│   ├── prompt/                # System prompt generator
│   ├── language/              # Reusable language-support module
│   │   ├── grammar.ts         #   Pure-data tokens + CodeMirror StreamParser
│   │   ├── components.ts      #   Component catalog (derived from library)
│   │   ├── builtins.ts        #   @-builtin catalog (sourced from runtime)
│   │   ├── snippets.ts        #   Ready-to-insert templates for composites
│   │   └── index.ts           #   `getLanguageSpec()` barrel for editors
│   ├── element.ts             # The custom element
│   └── index.ts               # Public entry point
├── docs/                      # Static documentation site (HTML + CSS + JS)
├── _docs/                     # Internal design notes and inspirations (not shipped)
├── scripts/
│   ├── emit-prompt.mjs        # Writes dist/system_prompt*.txt from the bundle
│   └── build-docs.mjs         # Assembles ./site/ from docs/ + dist/
├── tests/                     # Vitest unit + element regression tests
├── dist/                      # Built artifacts (created by `npm run build`)
├── site/                      # Deployable static docs (created by `npm run build:docs`)
├── .github/workflows/         # GitHub Pages deploy pipeline
├── README.md                  # This file
└── coding-gen-skill.md        # Deep knowledge base for building full apps

Run it locally

Requirements: Node ≥ 18 and npm ≥ 9 (or pnpm/yarn — examples use npm).

Install

git clone https://github.com/asfand-dev/streaming-ui-script.git
cd streaming-ui-script
npm install

Build the library and system prompt

npm run build

Produces:

dist/streaming-ui-script.js          # ESM bundle
dist/streaming-ui-script.umd.cjs     # UMD bundle for older bundlers
dist/streaming-ui-script.iife.js     # IIFE for non-module <script> tags
dist/system_prompt.txt               # Full prompt — every component, JS, routing
dist/system_prompt_chat.txt          # Compact chat-focused prompt (lighter, OpenUI-Lang style)

The two prompt variants exist so host apps can pick the right flavour up front: system_prompt.txt (or getSystemPrompt() with no options) for rich generative UI surfaces that need JS and routing, and system_prompt_chat.txt (or getSystemPrompt({ mode: "chat" })) for chat assistants whose replies should stay purely declarative. Both are kept in lock-step with the library by the build script.

Run the test suite

npm test

Includes:

• Parser / lexer correctness (tests/parser.test.ts).
• Runtime evaluator + reactive state (tests/runtime.test.ts).
• Built-in function semantics (covered across runtime + library tests).
• JavaScript interactions: Script(...) lifecycle + @Js(...) (tests/javascript-integration.test.ts).
• Hash-based router and Routes / Route / NavLink (tests/router.test.ts).
• Theme resolution and token application (tests/theme.test.ts).
• Component library smoke tests (tests/library.test.ts).
• Element-level integration tests — Custom Elements + Shadow DOM via happy-dom (tests/element.test.ts).
• System prompt generator output (tests/prompt.test.ts).
• End-to-end demo programs from the docs (tests/demos.test.ts).
• Language support spec for editor / tooling integrations (tests/language.test.ts).

Build the documentation site

npm run build:docs

Assembles ./site/ from ./docs/ + ./dist/. Serve it with anything static:

npx http-server site -p 4321
# or
npx serve site

Then open http://localhost:4321/index.html.

Security

The library treats every LLM-supplied attribute as untrusted and runs it through a small set of sanitisers before it lands on the DOM:

External links rendered by Link, NavbarItem, and the Markdown renderer get rel="noopener noreferrer" so the destination cannot read the opener's document.referrer.

If you embed <streaming-ui-script> behind a CSP, the bundle does not use eval. Script(...) bodies are evaluated with new (Async)Function(...) which requires 'unsafe-eval' if you want scripting to work; omit the attribute (and @Js action steps) if you cannot relax CSP.

CDN deployment

This repository ships its own copy of the bundle on GitHub Pages, so most users do not need to host anything themselves:

<script type="module" src="https://asfand-dev.github.io/streaming-ui-script/dist/streaming-ui-script.js"></script>
<streaming-ui-script theme="dark"></streaming-ui-script>

…and a fetch of system_prompt.txt server-side to build LLM messages:

curl https://asfand-dev.github.io/streaming-ui-script/dist/system_prompt.txt

To ship your own copy, run npm run build and serve the dist/ folder from any static host — every artifact in dist/ is self-contained.

GitHub Pages deployment for this repo is automated via .github/workflows/deploy-pages.yml. Push to main and the workflow will build, test, assemble site/, and publish.

Contributing

Contributions are very welcome. The fastest path is:

1. Fork and clone the repo.
2. npm install && npm test — make sure the suite is green on main first.
3. Make your change in a focused branch (e.g. feat/inline-charts).
4. Add or update tests in tests/. Aim for good edge-case coverage.
5. Run npm run build to confirm the bundle and the system prompt still build.
6. Open a pull request describing the motivation and any user-visible changes.

Issues, design discussions, and bug reports are tracked at https://github.com/asfand-dev/streaming-ui-script/issues.

By contributing you agree that your work will be released under the project's MIT license.

License

MIT — see LICENSE.