Bits UI Showcase

UI Builder

Properties1
descriptionArchitecture and source contracts for the serialisable canvas, block registry, persistence, and browser relay.

2 min read

UI Builder

The builder keeps the design document independent of rendered Svelte components. A BuilderSpec is plain serialisable data; a block registry maps each node type to metadata and an implementation; a reactive store owns mutation history and messages; and a recursive renderer turns the node forest into the preview.

Source boundaries

BoundaryRepository surfaceContract
Data modelsrc/lib/builder/spec.tsversioned node tree, chat state, block metadata, and mutation vocabulary
Block registrysrc/lib/builder/blocks.tsrendered component definitions plus serialisable metadata
Statesrc/lib/builder/store.svelte.tsapply, select, undo, redo, persistence, messages, and export
Renderersrc/lib/builder/Render.svelterecursive node rendering, editable mouse/keyboard selection, and unknown-type fallback
Relaysrc/lib/builder/relay.tsversion 1 window.bitsBuilder surface, cloned state boundaries, and lifecycle markers
Exportsrc/lib/builder/export.tsSvelte source projection with Bits UI namespace collection
Persistencesrc/routes/api/builder/session/+server.tsvalidated GET and bounded POST of { spec, messages }
User interfacesrc/routes/builder and src/routes/relaycanvas/editor surface and relay-oriented workbench

The model contract is detailed in Spec model. The concrete block shape is in Block registry. Browser-agent integration is in Relay protocol.

State flow

  1. The UI or relay submits one or more BuilderOp values.
  2. BuilderStore.apply validates and applies the batch, returning { ok, errors }.
  3. Valid operations apply in order. An error does not roll back earlier mutations in the batch. If at least one operation changes the spec, one pre-batch spec/selection snapshot enters undo history; a selection-only batch does not.
  4. Render.svelte recursively resolves each type through the block registry.
  5. The UI and window.bitsBuilder share the same store rather than mutate parallel documents.
  6. save() and load() exchange the spec and messages through the builder session endpoint.
  7. exportCode() projects the current spec to Svelte source.

Trust boundary

The relay is an in-browser integration point for an OMP agent operating through the browser relay. The application dependency set contains no server-side LLM SDK, and the relay contract does not accept or store an LLM provider key. This is a transport choice, not a claim that arbitrary browser scripts are trusted: an agent must still inspect applyOps failures before reporting success.

Verification state

  • Builder source surfaces: present in the repository.
  • Application build: verified with 0 svelte-check errors and warnings.
  • Browser interaction: verified through the live window.bitsBuilder relay.
  • Persistence: live GET/write/read round trip returned 200 with equivalent state.
  • Exported Svelte behavior: sample and all-block exports compiled; the live export reflected the rendered switch.

The exact relay, persistence, validation, history, and canvas receipts are recorded in Operations.

loca.zone · bits.loca.zone · Svelte · Bits UI

3 items under this folder.