@thebase/ui 0.0.4

package/docs/icons.md

@@ -0,0 +1,113 @@
+# Built-in Icons
+
+BaseUI ships the full Lucide icon set as a built-in CDN-ready icon library. Icons use the `b-icon` attribute, render as CSS masks, and inherit `currentColor` from the surrounding button, link, menu item, block, or theme.
+
+```html
+<button b-ui="button" type="button">
+  <span b-icon="search"></span>
+  Search
+</button>
+
+<button b-ui="button" b-att-variant="outline" type="button" aria-label="Open sidebar">
+  <span b-icon="panel-left" b-icon-size="1rem"></span>
+</button>
+```
+
+## Install
+
+Load the normal BaseUI assets. No separate icon script is required.
+
+```html
+<link rel="stylesheet" href="/dist/baseui.min.css">
+<script src="/dist/baseui.min.js" defer></script>
+```
+
+The build publishes every Lucide SVG to `dist/icons/lucide/` and writes the generated icon manifest to `dist/icons/lucide.json`.
+
+## Markup
+
+Use the Lucide icon name in kebab-case, camelCase, snake_case, or space-separated form. BaseUI normalizes the name to the matching Lucide SVG file.
+
+```html
+<span b-icon="check"></span>
+<span b-icon="panel-left"></span>
+<span b-icon="PanelLeft"></span>
+<span b-icon="panel_left"></span>
+```
+
+Use `b-icon-size` when the surrounding component should not control the icon size.
+
+```html
+<span b-icon="bell" b-icon-size="20px"></span>
+<span b-icon="settings" b-icon-size="1.25rem"></span>
+```
+
+## Color
+
+Icons inherit `currentColor`, so set color on the parent element or let BaseUI component variants and themes do it.
+
+```html
+<button b-ui="button" b-att-variant="destructive" type="button">
+  <span b-icon="trash-2"></span>
+  Delete
+</button>
+
+<span class="text-body-secondary">
+  <span b-icon="info"></span>
+  Muted helper text
+</span>
+```
+
+## Accessibility
+
+Decorative icons should not have a label. BaseUI marks them with `aria-hidden="true"`.
+
+```html
+<span b-icon="mail"></span>
+```
+
+Icon-only controls need an accessible name on the control, not just on the icon.
+
+```html
+<button b-ui="button" b-att-variant="outline" type="button" aria-label="Copy invite link">
+  <span b-icon="copy"></span>
+</button>
+```
+
+Standalone meaningful icons can use `aria-label`.
+
+```html
+<span b-icon="circle-check" aria-label="Complete"></span>
+```
+
+## Self-hosting
+
+By default, icon URLs point to the pinned Lucide CDN configured in the registry. To serve icons from your own BaseUI build, point `b-icon-base-url` at the published icon folder.
+
+```html
+<span b-icon="search" b-icon-base-url="/dist/icons/lucide"></span>
+```
+
+The same override is available through JavaScript.
+
+```js
+BaseUI.icons.lucide.url("search", { baseUrl: "/dist/icons/lucide" });
+```
+
+## JavaScript API
+
+Use the API when you need to build URLs or render icons into existing nodes.
+
+```js
+BaseUI.icons.lucide.normalizeName("Panel_Left");
+BaseUI.icons.lucide.url("panel-left");
+BaseUI.icons.lucide.render(document.querySelector("#status-icon"), "circle-check", {
+  size: "18px",
+});
+```
+
+The compatibility form still works, but new markup should prefer the shorter `b-icon` attribute.
+
+```html
+<span b-ui="icon" b-att-icon="search"></span>
+```

package/docs/installation.md

@@ -0,0 +1,78 @@
+# Installation
+
+See the [Usage Guide](usage-guide.md) for the end-to-end integration path (choosing an API, install, theming, verification). This page covers install mechanics only.
+
+BaseUI is distributed as one CSS file and one JavaScript file for browser use. `dist/baseui.min.js` is fully self-contained: Bootstrap's JS bundle (Popper.js included) and the Owl runtime are embedded ahead of BaseUI's own code, in load order (Bootstrap, then Owl, then BaseUI) — nothing else needs to load first.
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.min.css">
+<script src="https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.min.js" defer></script>
+```
+
+Bootstrap 5 is the bundled baseline CSS framework, and its JS bundle now drives BaseUI's interactive components directly.
+
+`@thebase/ui` is published on npm, so [unpkg](https://unpkg.com/@thebase/ui@0.0.1/) mirrors the same files as an alternative CDN (`https://unpkg.com/@thebase/ui@0.0.1/dist/baseui.min.css` / `baseui.min.js`) if jsDelivr is unreachable in your environment.
+
+For npm/self-hosted usage:
+
+```sh
+npm install @thebase/ui
+```
+
+Then copy or serve `node_modules/@thebase/ui/dist/baseui.min.css` and `node_modules/@thebase/ui/dist/baseui.min.js`.
+
+`dist/bootstrap.bundle.min.js` also ships standalone, unmodified, with its own integrity hash in `dist/baseui.registry.json`, in case a project wants vendored Bootstrap JS on its own — BaseUI itself never needs it loaded separately.
+
+The static bundle auto-mounts existing `[b-ui]` and `[b-icon]` markers on `DOMContentLoaded`. Use `BaseUI.mountAll(root)` after later DOM injection, and `BaseUI.destroy(root)` before removing a mounted subtree that owns listeners or an Owl-backed controller.
+
+The package also ships the complete Lucide SVG icon set under `dist/icons/lucide/` and a generated `dist/icons/lucide.json` manifest. The built-in icon component can use the pinned jsDelivr Lucide CDN by default or your own self-hosted path:
+
+```html
+<span b-icon="search"></span>
+<span b-icon="panel-left" b-icon-base-url="/dist/icons/lucide"></span>
+```
+
+Production pages should use pinned version URLs. `latest` is for demos and experiments.
+
+## Package exports and browser aliases
+
+| Need | npm/bundler export | Browser import-map key | Dist file |
+| --- | --- | --- | --- |
+| Static `b-ui` runtime, Owl framework, every pure Owl component class, theme helper | `@thebase/ui` | `@base/owl`, `@base/component`, `@base/theme` (all three point at the same file) | `dist/baseui.esm.js`, `dist/baseui.min.js` |
+| Styles | `@thebase/ui/baseui.css` | none; load with `<link>` | `dist/baseui.min.css` |
+| Bootstrap JS | embedded; standalone file is a vendoring convenience only, not part of BaseUI's own load path | none | `dist/bootstrap.bundle.min.js` |
+| Named-icon components (`IconEye`, ...) | `@thebase/ui/icons` | `@base/icons` | `dist/baseui.icons.esm.js` |
+| Owl templates XML | `@thebase/ui/dist/baseui.templates.xml` | `@base/templates` | `dist/baseui.templates.xml` |
+| Registry metadata | `@thebase/ui/registry` | none; fetch the JSON file | `dist/baseui.registry.json` |
+
+`@base/templates` points to XML, not JavaScript. Resolve and fetch it (`fetch(import.meta.resolve("@base/templates"))`) before mounting an Owl app that uses BaseUI component classes.
+
+## Release Guardrails
+
+BaseUI intentionally keeps Bootstrap bundled for the browser build, both CSS and JS. Bootstrap's JS bundle and the Owl runtime are embedded directly into `dist/baseui.min.js`/`baseui.esm.js` — in that load order — along with every pure Owl component class and the theme helper, so both the static API and the pure Owl API install with one stylesheet and one script/import: there is no more separate `baseui.owl.*`/`baseui.components.esm.js`/`baseui.theme.esm.js` file to keep in load order. Bootstrap's JS instances (`bootstrap.Modal`, `Dropdown`, `Collapse`, `Tab`, `Toast`, `Carousel`, `Tooltip`, `Popover`, `Alert`) drive the components that map to them, wrapped by BaseUI's own `.behavior.js`/`runtime/*.js` helpers so both the static and pure-Owl APIs share identical ARIA/keyboard/event behavior.
+
+Release checks enforce runtime dependency, peer dependency, scoped CSS selector, and CDN file-size budgets through `npm run lint` and `npm run build`.
+
+## Pure Owl component install
+
+If you're building your own Owl app and want to import BaseUI components as real Owl component classes (`<Button/>`, `<Card/>`, `<Tabs/>`, ...) instead of `b-ui` markup, it's the same one file as the static install, just accessed through an import map:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.min.css">
+<script type="importmap">
+{
+  "imports": {
+    "@base/owl": "https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.esm.js",
+    "@base/component": "https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.esm.js",
+    "@base/theme": "https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.esm.js",
+    "@base/templates": "https://cdn.jsdelivr.net/npm/@thebase/ui@0.0.1/dist/baseui.templates.xml"
+  }
+}
+</script>
+```
+
+`@base/owl`, `@base/component`, and `@base/theme` all resolve to the exact same `dist/baseui.esm.js` module — the browser fetches and evaluates it once, so `Component`/`mount`/`xml` from `@base/owl` and `Button`/`Card`/... from `@base/component` are guaranteed to be the same runtime identity (no separate script needs to load first to set up a shared global). Your own app code should still import Owl from `@base/owl`, never install or import `@odoo/owl` directly — that's what keeps a `class Root extends Component` you write instanceof-compatible with BaseUI's own components. `@base/templates` maps to the templates XML — not a JS module, so resolve it with `import.meta.resolve("@base/templates")` and `fetch()` the result rather than `import`ing it.
+
+For npm/bundler usage, everything (Owl framework, component classes, theme helper) is exported from the one `@thebase/ui` package entry: `import { Component, mount, xml, Button, Card, createThemeController } from "@thebase/ui";` — plus `@thebase/ui/dist/baseui.templates.xml` (component templates — fetch or load them before mounting). Note that importing the main entry always runs its `autoMount()` side effect (it scans the DOM for `[b-ui]`/`[b-icon]` markers on `DOMContentLoaded`) — harmless if your page has none, but worth knowing if you specifically wanted a side-effect-free import.
+
+See [Pure Owl Components](owl-components.md) for the full loading contract, a worked example, and common mistakes.

package/docs/owl-components.md

@@ -0,0 +1,103 @@
+# Pure Owl Components
+
+See the [Usage Guide](usage-guide.md) for when to reach for this API versus the static `b-ui` one. This page covers the pure Owl API only.
+
+BaseUI ships a second, additive public API alongside the static `b-ui` markers: real Owl component classes you import, compose with `static components`, and mount as part of your own Owl app. This page covers how to load and use it; see [Component Authoring](component-authoring.md) for how components implement both APIs from one source folder.
+
+As of 1.1.0, every component in the registry (all 65) has a pure Owl export — there are no static-only components left. Compound components export a root class plus sub-components (e.g. `Dialog`/`DialogTrigger`/`DialogContent`/...); check a component's `owlComponents` entry in `dist/baseui.registry.json`, or its doc page under [`docs/components/`](components/), for the exact export list. A few components have a deliberately reshaped pure Owl API versus their static markup-scanning adapter — see [Registry](registry.md#component-export-policy) for which ones and why.
+
+## What you need to load
+
+Everything — the static `b-ui` runtime, the Owl framework, every pure Owl component class, and the theme helper — is one file: `dist/baseui.esm.js` (or `dist/baseui.min.js` as a classic script). There is no separate `baseui.owl.*`/`baseui.components.esm.js`/`baseui.theme.esm.js` to load.
+
+| File | Purpose |
+| --- | --- |
+| `dist/baseui.min.css` | Bootstrap + BaseUI styling, shared by both APIs. |
+| `@base/owl` (`dist/baseui.esm.js`) | The Owl framework — `Component`, `mount`, `xml`, `useState`, etc. Pinned to Owl `2.8.3`, embedded directly in this file. Import your app's own Owl usage from here too, not `@odoo/owl`. |
+| `@base/component` (`dist/baseui.esm.js`) | The pure Owl component classes — same file as `@base/owl` above, just a different import-map key for readability. |
+| `@base/theme` (`dist/baseui.esm.js`) | Same file again — the theme helper for persisted light/dark toggles, URL overrides, button-label sync, and iframe preview sync. |
+| `@base/templates` (`dist/baseui.templates.xml`) | The Owl templates the component classes reference (`static template = "baseui.Button"`, etc). Must be loaded and passed to `mount()` before any BaseUI component tag renders — a component class alone does not carry its template. |
+
+## Browser (import map) usage
+
+```html
+<link rel="stylesheet" href="/dist/baseui.min.css">
+<script type="importmap">
+{
+  "imports": {
+    "@base/owl": "/dist/baseui.esm.js",
+    "@base/component": "/dist/baseui.esm.js",
+    "@base/theme": "/dist/baseui.esm.js",
+    "@base/templates": "/dist/baseui.templates.xml"
+  }
+}
+</script>
+<script type="module">
+  import { Component, mount, xml } from "@base/owl";
+  import { Button, Card, CardBody, CardHeader, CardTitle } from "@base/component";
+
+  // "@base/templates" is an import-map entry, not a JS module — resolve it
+  // to its mapped URL and fetch the text.
+  const templates = await fetch(import.meta.resolve("@base/templates")).then((r) => r.text());
+
+  class Root extends Component {
+    static components = { Button, Card, CardBody, CardHeader, CardTitle };
+    static template = xml`
+      <Card>
+        <CardHeader><CardTitle>Hello</CardTitle></CardHeader>
+        <CardBody>
+          <Button variant="'default'" label="'Save'" onClick="() => console.log('saved')"/>
+        </CardBody>
+      </Card>`;
+  }
+
+  await mount(Root, document.getElementById("app"), { templates });
+</script>
+```
+
+No `@odoo/owl` import appears anywhere in that snippet — `@base/owl` is the only Owl entry point BaseUI components and consumer apps need. Because `@base/owl`, `@base/component`, and `@base/theme` all point at the exact same `dist/baseui.esm.js` URL, the browser fetches and evaluates it once and every key shares the same module instance — no separate classic `<script>` needs to load first to set up a shared global.
+
+## npm / bundler usage
+
+```sh
+npm install @thebase/ui
+```
+
+```js
+import { Component, mount, xml, Button, Card } from "@thebase/ui";
+import baseuiTemplates from "@thebase/ui/dist/baseui.templates.xml?raw"; // exact loader syntax depends on your bundler
+
+class Root extends Component {
+  static components = { Button, Card };
+  static template = "Root";
+}
+```
+
+There's only one package entry now — `@thebase/ui` exports the Owl framework (built from the exact `@odoo/owl@2.8.3` this BaseUI release vendors; you do not need to install `@odoo/owl` yourself), every pure Owl component class, and the theme helper together. Browser import-map examples above still use the `@base/owl`/`@base/component`/`@base/theme` keys for readability, but they're just local aliases to the same file.
+
+When a bundler cannot import XML with `?raw`, load `dist/baseui.templates.xml` as a served asset and pass the fetched string to `mount(Root, target, { templates })`. The template file is part of the runtime contract, not optional documentation.
+
+## Mixing with the static API
+
+Both APIs come from the exact same bundle now, so there's nothing extra to load — just be clear about which mechanism owns which markup:
+
+- `BaseUI.mountAll(root)` enhances static `[b-ui]` and `[b-icon]` markers.
+- Owl `mount(Root, target, { templates })` renders component tags such as `<Button/>`.
+- Importing the package always also runs `autoMount()` (its `[b-ui]`/`[b-icon]` DOM scan on `DOMContentLoaded`) — harmless if your page has none, but means there's no side-effect-free way to import just the component classes anymore.
+- Both APIs share `dist/baseui.min.css`, `@base/theme`, and the same `b-theme` / `data-bs-theme` root attributes.
+
+## Props, events, slots
+
+- Props are camelCase (`variant`, `label`, `disabled`, `className`).
+- Almost every component that renders its own root element also accepts `style` (a string or a plain object of CSS properties) alongside `className`. Components that only forward a default slot with no wrapping element of their own (`AlertDialog`, `Pwa`, `Sheet`, `ContextMenu`, `Drawer`) have neither prop. A handful of components that already compute an internal style (`Icon`, `AspectRatio`, `Progress`, `ContextMenuContent`, `SidebarMenuSkeleton`) merge your `style` with their own computed value instead of one overwriting the other.
+- Events are callback props (`onClick`, `onChange`, `onOpenChange`), not DOM `CustomEvent`s — that's the static API's contract, not this one.
+- Default slot content works as normal Owl children (`<Badge>Draft</Badge>`); compound components use named slots/sub-tags (`<CardHeader>`, `<DialogFooter>`).
+
+See each component's page under [`docs/components/`](components/) for its specific props table and an Owl usage example alongside the static `b-ui` one.
+
+## Common mistakes
+
+- **Rendering a bare `<Button/>` with no template loaded.** `mount(Root, target)` without `{ templates }` (or `app.addTemplates(...)`) throws — the `.xml` file is a real build/runtime input, not documentation.
+- **Registering `Button` under the wrong tag name.** `static components = { Button }` must match the tag used in the template (`<Button/>`), same as any other Owl component.
+- **Importing from `@odoo/owl`.** Always import from `@base/owl` instead, even in your own app code — it keeps your app on the exact Owl version this BaseUI release was tested against.
+- **Adding a `baseui.owl.min.js`/`baseui.owl.esm.js`/`baseui.components.esm.js` script or import-map entry.** None of those files are published anymore — point `@base/owl`/`@base/component`/`@base/theme` all at `dist/baseui.esm.js` instead.

package/docs/registry.md

@@ -0,0 +1,34 @@
+# Registry
+
+Every release publishes `dist/baseui.registry.json`. The registry lists package metadata, CDN paths, build files, themes, and per-component metadata (type, dependencies, `b-*` attributes, events, and — since the Phase 8 pure-Owl rollout — Owl component/template metadata). It only registers components under `src/components/`; example blocks under `examples/blocks/` are not part of the registry.
+
+BaseUI ships as bundled files only — there is no per-component source distribution. Use the registry's `components` entries to look up a component's contract, not to locate individual source files.
+
+## Build files
+
+`buildFiles` lists every top-level `dist/` artifact the release validates and hashes:
+
+- `baseui.min.css` — Bootstrap 5 + BaseUI styles (static and pure Owl APIs share the same stylesheet).
+- `baseui.min.js` / `baseui.esm.js` — the one bundle for both APIs: the static `b-ui` runtime (`BaseUI.register(...)`, `BaseUI.mountAll()`), the Owl framework (`Component`, `mount`, `xml`, ...), every pure Owl component class (`Button`, `Card`, `Tabs`, ...), and the theme helper (`createThemeController`, `BaseUITheme`). Bootstrap's JS bundle and Owl's global build are embedded ahead of BaseUI's own code, in that load order — no separate `baseui.owl.*`/`baseui.components.esm.js`/`baseui.theme.esm.js`/`bootstrap.bundle.min.js` script is needed.
+- `bootstrap.bundle.min.js` — vendored Bootstrap JS, standalone, unmodified. Ships in case a project wants it on its own; BaseUI's own bundle never needs it loaded separately (it's embedded in `baseui.min.js`/`baseui.esm.js` too).
+- `baseui.icons.esm.js` — the 2000+ generated `Icon<Name>` components (`IconEye`, `IconSearch`, ...), split out because they'd blow the main bundle's size budget. The one deliberate exception to "everything is one bundle".
+- `baseui.templates.xml` — every pure Owl component's compiled `<templates>` body, concatenated into one file. Load this into the Owl `App`'s `templates` config before mounting; `.xml` files under `src/components/` are authoring sources, not something a consumer app loads directly.
+- `icons/lucide.json` — the built-in icon manifest.
+
+## Component export policy
+
+Every component folder under `src/components/<name>/` is one of:
+
+1. **Both APIs** — has `<name>.js` (static `BaseUI.register(...)` adapter) *and* `<name>.component.js` (pure Owl `Component` class(es)). As of the Phase 8 rollout this is **all 65** registry components; there are no static-only exceptions left. A handful of components (`chart`, most notably) have lighter-fidelity pure Owl treatments than their static adapter — see their component doc page for the documented gap — but every registry component has a real Owl export.
+2. Static-only components would report `"type": "static"` with no `owlComponents` field, but none currently exist in this registry.
+
+Per-component registry entries now include:
+
+- `owlComponents` — the exact list of exported Owl class names from `<name>.component.js`, e.g. `["Dialog", "DialogTrigger", "DialogContent", ...]` for compound components. Import these from `@thebase/ui`.
+- `templateName` — the namespaced template name the component's *root* class renders, e.g. `"baseui.Dialog"`. Every template also registers a short un-namespaced alias (e.g. `Dialog`) via `t-call` for local convenience; `templateName` documents the namespaced form because that's the collision-safe one to rely on across a large template set.
+
+Existing fields (`type`, `dependencies`, `attributes`, `events`) are unchanged and describe the static `b-ui` contract; they apply regardless of whether an Owl export also exists.
+
+## Validation
+
+The build validates every registry path against `dist/` and adds SHA-384 integrity hashes for build files and themes. Example blocks (composed static HTML demos styled by `baseui.min.css`) live under `examples/blocks/` with per-block CSS split from `examples/blocks/shared.css`, but are not registry or JavaScript components.

package/docs/runtime-api.md

@@ -0,0 +1,28 @@
+# Runtime API
+
+BaseUI exposes one browser global: `window.BaseUI`.
+
+```js
+BaseUI.version
+BaseUI.register(name, definition)
+BaseUI.component(name)
+BaseUI.mount(selectorOrElement, options)
+BaseUI.mountAll(rootElement)
+BaseUI.destroy(rootElement)
+BaseUI.theme.set("light")
+BaseUI.theme.set("dark")
+BaseUI.theme.set({ primary: "#0f6cbd" })
+```
+
+The static runtime calls `autoMount()` when imported through `dist/baseui.esm.js` or `dist/baseui.min.js`. Existing `[b-ui]` and `[b-icon]` markers are enhanced automatically once the DOM is ready.
+
+`mountAll(rootElement)` scans `[b-ui]` and `[b-icon]` below the given root. Repeated calls are idempotent for already-mounted nodes, so it is safe to call after rendering an AJAX partial or replacing a small subtree. `mount(selectorOrElement, options)` mounts one element and returns its instance metadata when a registered component exists. `destroy(rootElement)` calls component cleanup handlers and dispatches `baseui:destroyed` before a mounted subtree is removed.
+
+Mounted components dispatch lifecycle events on their root element:
+
+- `baseui:mounted` with `{ name, instance }` in `event.detail`.
+- `baseui:destroyed` with `{ name }` in `event.detail`.
+
+`BaseUI.theme.set(...)` is the low-level setter. For persisted light/dark toggles, button-label synchronization, URL `?theme=` overrides, and iframe preview sync, import `createThemeController` from `@base/theme` in browser import maps or `@thebase/ui` in npm/bundler apps.
+
+`BaseUI.mountAll()` is for static `b-ui`/`b-att-*` markers and `b-icon` markers only. It does not register Owl component tags (`<Button/>`, `<Card/>`, ...) and does not know about `@thebase/ui` or `dist/baseui.templates.xml`. To use pure Owl components, import their classes, fetch the templates XML, and list those classes in your own component's `static components`; see [Pure Owl Components](owl-components.md).

package/docs/theming.md

@@ -0,0 +1,55 @@
+# Theming
+
+Set the theme on `html` or a subtree:
+
+```html
+<html b-theme="dark">
+```
+
+At runtime:
+
+```js
+BaseUI.theme.set("dark");
+BaseUI.theme.set({ primary: "#0057d8", radius: "0.5rem" });
+```
+
+BaseUI maps semantic tokens such as `--baseui-background`, `--baseui-primary`, `--baseui-border`, and `--baseui-radius` into Bootstrap 5 variables. Radius tokens are sourced from the shorter public alias family `--base-radius`, `--base-radius-sm`, `--base-radius-md`, `--base-radius-lg`, `--base-radius-xl`, `--base-radius-2xl`, `--base-radius-3xl`, `--base-radius-4xl`, and `--base-radius-full`, then mirrored to `--baseui-radius*` for component CSS.
+
+For a reusable theme toggle with persistence, URL override, button-label sync, and iframe preview sync, import the theme helper:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "@base/theme": "/dist/baseui.esm.js"
+  }
+}
+</script>
+<script type="module">
+  import { createThemeController } from "@base/theme";
+
+  const theme = createThemeController({
+    storageKey: "my-app-theme",
+    toggleSelector: "[b-theme-toggle]",
+    labelSelector: "[b-theme-label]"
+  });
+
+  theme.init();
+</script>
+```
+
+Npm/bundler consumers can import the same API from `@thebase/ui`.
+
+For a ready-made icon button, use the BaseUI component instead of wiring your own click handler:
+
+```html
+<button b-ui="theme-button" b-att-variant="outline" b-att-storage-key="my-app-theme" type="button"></button>
+```
+
+The documentation and example pages use the same theme infrastructure. Owl example modules import `createThemeController` from `@base/theme`; static chrome relies on `b-ui="theme-button"`, which uses the helper internally, so one selected theme is persisted across components, docs, chart galleries, block viewers, and same-origin block preview iframes. Theme changes dispatch `baseui:theme-change` on `document` with `{ theme }` in `event.detail`.
+
+## Design tokens
+
+The default light/dark palettes and radius follow the current [shadcn/ui](https://ui.shadcn.com) Base UI neutral theme: black/neutral primary on white in light mode, neutral-900/50 foreground-background inversion in dark mode, neutral `--baseui-secondary`/`--baseui-muted`/`--baseui-accent` surfaces, `--base-radius: var(--radius, 0.625rem)`, and a derived radius scale (`--base-radius-sm|md|lg|xl`, mirrored as `--baseui-radius-sm|md|lg|xl`) and shadow scale (`--baseui-shadow-sm|md|lg`) for consistent elevation across popovers, menus, dialogs, and toasts. BaseUI reads an existing upstream `--radius` value when present, but it does not redefine `--radius` back to `--baseui-radius`; that one-way bridge avoids CSS custom-property cycles. `--baseui-card`/`--baseui-popover` alias `--baseui-surface` for shadcn-token-name parity.
+
+Because BaseUI ships Bootstrap's stock precompiled CSS, most `.btn-*`/badge colors are not driven by `--bs-*` variables directly — `src/styles/baseui.css` re-points the `.btn-primary`/`.btn-secondary`/`.btn-danger`/`.btn-outline-secondary`/`.btn-light` variants at BaseUI tokens so `BaseUI.theme.set(...)` overrides actually render. Badges use their own `baseui-badge-*` classes (`src/components/badge/badge.css`) instead of Bootstrap's `text-bg-*`, which hardcode non-overridable colors.