@ripple-ui/svelte

A Svelte 5 runtime that turns a JSON spec into a live, interactive UI.

What this is

Ripple is the rendering layer for AI-generated interfaces. An LLM (or any other source) emits a small JSON document describing what the UI should look like; Ripple mounts it as a real Svelte component tree with state, two-way bindings, expression evaluation, and event handling. The model writes structure; Ripple handles reactivity.

You don't author Svelte components per screen. You hand Ripple a spec and it builds the UI.

{
  "version": "1.0",
  "state": { "name": "" },
  "ui": {
    "type": "flex",
    "props": { "direction": "column", "gap": "12px" },
    "children": [
      { "type": "input", "bind": "name", "props": { "label": "Your name" } },
      { "type": "text", "props": { "text": "Hello, {state.name}!" } }
    ]
  }
}

That spec is a fully working two-way-bound form. No glue code.

What it does

Three things, in order of how often you'll touch them:

1. Renders 150+ typed widgets from JSON. Every node in the tree ({ "type": "...", "props": {...}, "children": [...] }) maps to a Svelte component — flex, card, kanban, chart, comparison-layout, wizard-layout, pricing-table, all of them. The full catalog with prop schemas lives in dist/manifest.json.

2. Wires state and interactivity declaratively. state is a top-level object on the spec. Inputs use "bind": "<state-path>" for two-way binding. Buttons fire on_click action chains (set, push, remove, toggle, validate, branch, confirm, api, navigate, toast, emit). Expressions inside any string — {state.count + 1}, {state.x > 0 ? 'yes' : 'no'}, {item.price} — are resolved at render time against state and loop context.

3. Hands back events. Anything the host needs to handle (HTTP calls, navigation, toasts, custom signals) bubbles out via a single onEvent callback on the <Ripple> component. The spec doesn't reach into your app; it asks the host to do something.

How it works

The pipeline in five steps:

   spec (JSON)
        │
        ▼
  ┌──────────────┐    UISpec → UniversalSpec wrapper
  │  normalizer  │    (or pass-through if already universal)
  └──────┬───────┘
         ▼
  ┌──────────────┐    Svelte 5 $state proxy with dot-notation
  │ StateManager │    `get("user.profile.name") / set("count", 7)`
  └──────┬───────┘
         ▼
  ┌──────────────┐    Resolves `{state.x + 1}`, `{item.field}`,
  │  Expression  │    ternaries, comparisons, method calls.
  │   Resolver   │    Tracks reads inside derived blocks for
  └──────┬───────┘    automatic reactivity.
         ▼
  ┌──────────────┐    Walks the tree, picks the Svelte component
  │ NodeRenderer │    from the registry per `type`, evaluates
  └──────┬───────┘    `show`/`bind`/`on_*`, renders children.
         ▼
  ┌──────────────┐    User clicks → `on_click` chain runs through
  │   Event      │    the dispatcher: state mutations stay local,
  │  Dispatcher  │    side-effecting actions (api/toast/navigate)
  └──────────────┘    fire `onEvent` on the host.

Each piece is independent and Svelte 5 native:

• Normalizer (src/lib/core/normalizer.ts) accepts either spec format and returns a UniversalSpec.
• StateManager (src/lib/core/state-manager.svelte.ts) wraps a Svelte 5 $state proxy. Path-based reads/writes auto-create intermediate objects. Subscribe via stateManager.subscribe(callback).
• ExpressionResolver (src/lib/core/expression-resolver.ts) parses {...} strings — paths, arithmetic, comparisons, ternaries, optional chaining, whitelisted methods (.includes, .length, .toFixed, etc.). Detects UINode-shaped subtrees and leaves them raw so they can resolve later in their own loop context.
• EventDispatcher (src/lib/core/event-dispatcher.ts) executes action chains. State actions (set/push/remove/toggle) write through StateManager; control actions (branch/validate/confirm) gate further actions; effect actions (api/navigate/toast/emit/pin/unpin) emit RippleEvents the host can intercept.
• NodeRenderer (src/lib/components/NodeRenderer.svelte) is the recursive walker. It evaluates show conditions, resolves props, builds loop contexts for each, manages bind two-way wiring, and renders children — including named slots (header, footer, sidebar, topbar, actions).
• Widget registry (src/lib/widgets/index.ts) maps type strings to Svelte components. Aliases are flat entries (e.g. dialog → Modal, comparison-cards → ComparisonLayout). Register your own at runtime with registerWidget(type, component).

Reactivity is end-to-end: every state mutation flows through the proxy, Svelte recomputes any derived that read it, and only the affected widget re-renders. There is no virtual DOM diff phase you have to think about — it's the same system Svelte 5 uses for hand-written components.

Why JSON specs?

Three reasons that compound:

1. LLMs produce structured data better than they produce code. A model emits a spec like the one above with high reliability; the same model writing equivalent Svelte code is several times more error-prone.
2. Specs are inspectable, diffable, persistable. You can save a UI to a database, send it over the wire, replay it from a log, run a regression test against it. JSX-as-rendered output gives you none of that.
3. The contract is small. Every widget's prop schema lives in dist/manifest.json (150 widgets, ~270 KB). A model can fetch it once and have a complete catalog, including runnable examples. New widgets ship by adding to the registry — no SDK update on the agent side.

Features

• JSON-driven rendering — Define UIs as data, not code
• Two spec formats — Low-level UISpec (v1.0) for full control, or high-level UniversalSpec (v2.0) for intent-based UIs
• 150+ built-in widgets across nine categories — layout, display, input, data, overlay, control, composite, research, and enterprise verticals
• Reactive expressions — {state.user.name} syntax with comparisons, ternary, and logical operators
• State management — Svelte 5 rune-based with dot-notation path access
• Event system — Declarative handlers for state updates, API calls, navigation, toasts, and custom events
• Intent system — Auto-layout engine, pattern detection (quiz, charts, results), and multi-step flow chaining
• LLM-ready manifest — dist/manifest.json ships with every release, declaring every widget's prop schema and a runnable example. Agents can fetch it at runtime to learn the API
• Extensible — Register custom widgets at runtime
• Theming — shadcn-svelte tokens with full color/radius/mode overrides

Installation

bun add @ripple-ui/svelte

Requires Svelte 5 (^5.0.0).

Quick Start

<script lang="ts">
  import { Ripple } from '@ripple-ui/svelte';

  const spec = {
    version: '1.0',
    state: { count: 0 },
    ui: {
      type: 'flex',
      props: { direction: 'column', gap: 4 },
      children: [
        { type: 'heading', props: { text: 'Counter', level: 2 } },
        { type: 'text', props: { text: 'Count: {state.count}' } },
        {
          type: 'button',
          props: { label: '+1' },
          on_click: { action: 'set', target: 'count', value: '{state.count}' }
        }
      ]
    }
  };
</script>

<Ripple {spec} />

Spec Formats

UISpec (v1.0) — Full Control

Explicit widget tree with props, events, and control flow:

{
  "version": "1.0",
  "state": { "query": "" },
  "ui": {
    "type": "flex",
    "props": { "direction": "column", "gap": 3 },
    "children": [
      { "type": "input", "props": { "placeholder": "Search..." }, "bind": "{state.query}" },
      {
        "type": "if",
        "condition": "{state.query != ''}",
        "children": [{ "type": "text", "props": { "text": "Searching: {state.query}" } }]
      }
    ]
  }
}

UniversalSpec (v2.0) — Intent-Based

Declare what the UI should do, and Ripple picks the layout:

{
  "version": "2.0",
  "intent": "browse",
  "title": "Products",
  "data": {
    "items": [
      { "id": "1", "name": "Widget", "image": "/img/widget.jpg", "price": "$9.99" }
    ]
  },
  "fields": { "title": "name", "image": "image", "subtitle": "price" },
  "selection": "single"
}

Built-in Widgets

The complete prop schema and a runnable example for every widget live in dist/manifest.json (regenerated by bun run build:manifest). LLM agents fetch this manifest to learn the API; treat it as the source of truth.

Expressions

Reactive bindings using {expression} syntax:

{state.user.name}              — State path
{item.price}                   — Loop variable
{state.count > 0}              — Comparison
{state.active ? 'On' : 'Off'}  — Ternary
{state.a && state.b}           — Logical AND
{!state.loading}               — Negation

Event Handling

Declarative handlers with 8 action types:

{
  "on_click": [
    { "action": "set", "target": "loading", "value": true },
    { "action": "api", "url": "/api/save", "method": "POST" },
    { "action": "toast", "message": "Saved!", "variant": "success" }
  ]
}

Custom Widgets

import { registerWidget } from '@ripple-ui/svelte';
import MyWidget from './MyWidget.svelte';

registerWidget('my-widget', MyWidget);

Development

bun install              # Install dependencies
bun run dev              # Dev server with playground (also serves /manifest.json)
bun run build            # Build library + manifest to dist/
bun run build:manifest   # Regenerate dist/manifest.json and static/manifest.json
bun run check            # Type-check
bun run test             # Run tests

The dev server serves the widget manifest at http://localhost:5174/manifest.json. Point your LLM tooling at this URL to develop against live changes.

Documentation

Full documentation in docs/:

• Getting Started
• Architecture
• UISpec Reference
• UniversalSpec Reference
• Widgets
• Expressions
• State Management
• Event Handling
• Intent System
• Theming
• Custom Widgets
• API Reference

License

MIT