Builder Block Registry

A builder node stores a string type; it never serialises a Svelte component. The block registry resolves that key to both agent-readable metadata and the component used by the recursive renderer.

Source metadata contract

The metadata types below are copied verbatim from src/lib/builder/spec.ts:

/** Serialisable block metadata exposed to agents via `window.bitsBuilder.blocks()`. */
export type BlockField = {
	key: string;
	label: string;
	kind: 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'items';
	/** for kind === 'select' */
	options?: string[];
	min?: number;
	max?: number;
	step?: number;
};
 
export type BlockMeta = {
	type: string;
	label: string;
	category: string;
	container: boolean;
	/** bits-ui namespace this block is built from, when applicable */
	bits?: string;
	description: string;
	defaults: Record<string, unknown>;
	fields: BlockField[];
};

Rendered definition contract

src/lib/builder/blocks.ts joins metadata to rendering without exposing component constructors through the relay:

export type BlockDef = BlockMeta & { component: Component };
 
export const blocks: Record<string, BlockDef>;
export function blockMetas(): BlockMeta[];

The two views serve different boundaries:

• blocks[type] is application-only and gives Render.svelte the component plus metadata.
• blockMetas() strips the implementation reference and gives agents a serialisable catalog.
• BlockMeta.type must equal the BuilderNode.type key used for lookup.
• container determines whether a node can carry children.
• defaults seed a new node’s props.
• fields describe the inspector controls an agent or UI may present.
• bits records the Bits UI namespace when a block is built from one; it is optional for non-Bits composition blocks.

Field behavior

Kind	Metadata
text	one string field
textarea	multiline string field
number	numeric field; min, max, and step may constrain the editor
boolean	binary field
select	choice field; options supplies the choices
items	structured list field whose value remains serialisable

These are metadata shapes, not permission to accept any runtime value silently. BuilderStore.apply is the mutation boundary and returns its validation errors to both UI and relay callers.

Concrete enumeration — generated at build time

Status: live relay verified with 22 concrete blocks.

blocks.ts is the authority for the concrete definitions. blockMetas() generates the serialisable enumeration from Object.values(blocks), removes each component, and clones defaults, fields, and field options. This page deliberately does not invent or duplicate the resulting names.

Agents obtain the concrete source-derived list from window.bitsBuilder.blocks() after relay installation. The production relay returned 22 entries on 2026-08-30. Keeping the enumeration generated by blockMetas() prevents documentation drift when blocks or fields change.

---

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