API Reference

Exhaustive surface area of the Lego runtime. Every entry on this page maps directly to source under src/. If something isn't here, it isn't part of the public API.

Runtime

Symbol	Purpose
Lego.init(root?, options?)	Boot the engine. Discover templates, hydrate inline blocks, install router & loader, run startup-time route match.
Lego.block(tag, html, logic?, styles?, cascade?, error?, props?)	Define a block from a string template.
Lego.defineLegoFile(content, filename?)	Define a block from .lego SFC content (used by the Vite plugin and runtime loaders).
Lego.route(path, tagName, middleware?)	Register a client-side route. Supports :params, * wildcards, and async middleware.
Lego.snap(el) / Lego.unsnap(el)	Manually mount / unmount a block element.
Lego.mount(tag, target?, props?)	Imperative mount with optional initial state.
Lego.db(key)	Persistence descriptor builder (also exposed as $db inside blocks).
Lego.getLegos() / Lego.getActiveBlocksCount()	Introspection helpers.
Lego.debug.stylesheets(el)	Inspect resolved stylesheets for a block.

Reactive globals

Symbol	Purpose
Lego.globals	Reactive cross-block state. Mutating any property re-renders subscribed blocks.
Lego.globals.$route	Current { url, route, params, query, method, body }.
Lego.globals.$go(path, ...targets)	Programmatic navigation. Returns { get, post, put, patch, delete }.
Lego.globals.$mount	Imperative mount helper (alias of Lego.mount).
Lego.globals.$db	Persistence factory (alias of Lego.db).

Configuration

Symbol	Purpose
Lego.config.syntax	Delimiter style, 'brackets' ([[ ]], default) or 'mustache' ().
Lego.config.debug	Verbose tracing.
Lego.config.onError	Last-resort error handler when no boundary catches.
Lego.config.sanitize	HTML sanitizer used by b-html.safe.
Lego.config.metrics	onRenderStart / onRenderEnd hooks.
Lego.config.loader	Auto-discovery loader for unknown hyphenated tags.
Lego.config.loaderAllowlist	Tag-name allowlist for the loader.

Block surface

Inside a block's logic (mounted, methods, getters), this exposes:

Symbol	Purpose
this.$element	The host element.
this.$vars	DOM refs collected via b-var.
this.$parent	Nearest ancestor block.
this.$emit(name, detail?)	Dispatch a bubbles: true, composed: true CustomEvent.
this.$route, this.$go, this.$mount	Mirror of the reactive globals.
this.mounted() / this.updated() / this.unmounted()	Lifecycle hooks.

Inside template expressions ([[ … ]], @event="…", b-if/b-show/b-html/b-mount), the scope adds:

Symbol	Purpose
state	The block's own state (default scope of every expression).
global	Reactive globals, read global.user.name, etc.
self	The DOM node the binding is on.
event / $event	The DOM event (event handlers only).
$ancestors(tag)	Find the nearest matching block ancestor.
$registry(tag)	Reactive shared state for a registered block tag.
$params	Shortcut for $route.params.
$go, $mount, $db, $emit, $element	Same as the JS-side helpers.

Directives

The complete set, all defined under src/directives/:

Directive	Effect
b-if	Conditional mount/unmount.
b-show	Toggle inline display.
b-for	Keyed list rendering.
b-text	Path-only text binding.
b-html / b-html.safe	Raw HTML, optionally sanitized.
b-sync / .lazy .number .trim	Two-way form binding.
b-init	One-shot expression.
b-enter / .once	IntersectionObserver entry hook.
b-leave / .once	IntersectionObserver exit hook.
b-mount	Reactively mount a tag computed from state.
b-var	Capture DOM refs into $vars.
b-logic / b-data	Inject state at template or instance level.
b-props	Declared prop contract.
b-id	Inline-template tag name.
b-error	Error boundary fallback tag.
b-stylesheets / b-cascade	Adopt named constructable stylesheets.
b-target / b-link / b-action	Routing attributes on <a> / <form>.

Browser support

LegoDOM relies on:

• Custom Elements v1 + Shadow DOM v1
• ES6 Proxy
• IntersectionObserver (only consumed by b-enter / b-leave)
• CSSStyleSheet constructable + adoptedStyleSheets (used by b-stylesheets)

Tested in Chrome 90+, Firefox 90+, Safari 15+, Edge 90+. The directives that need IntersectionObserver and constructable stylesheets degrade gracefully on older browsers, neither throws, but the affected feature won't run.