@colletdev/core 0.1.3

package/generated/.gitattributes

@@ -0,0 +1,2 @@
+# Everything here is auto-generated. Edit the generators, not these files.
+* linguist-generated=true

package/generated/index.d.ts

@@ -0,0 +1,120 @@
+// Auto-generated by scripts/generate-elements.mjs — DO NOT EDIT
+// TypeScript declarations for @colletdev/core main entry point.
+
+import { CxElement, CxFormElement } from '../src/runtime.js';
+
+/** All available component names (kebab-case, matching <cx-{name}> tags). */
+export type ComponentName =
+  | 'accordion'
+  | 'activity-group'
+  | 'alert'
+  | 'autocomplete'
+  | 'avatar'
+  | 'backdrop'
+  | 'badge'
+  | 'breadcrumb'
+  | 'button'
+  | 'card'
+  | 'carousel'
+  | 'chat-input'
+  | 'checkbox'
+  | 'code-block'
+  | 'collapsible'
+  | 'date-picker'
+  | 'dialog'
+  | 'drawer'
+  | 'fab'
+  | 'file-upload'
+  | 'listbox'
+  | 'menu'
+  | 'message-bubble'
+  | 'message-group'
+  | 'message-part'
+  | 'pagination'
+  | 'popover'
+  | 'profile-menu'
+  | 'progress'
+  | 'radio-group'
+  | 'scrollbar'
+  | 'search-bar'
+  | 'select'
+  | 'sidebar'
+  | 'skeleton'
+  | 'slider'
+  | 'speed-dial'
+  | 'spinner'
+  | 'split-button'
+  | 'stepper'
+  | 'switch'
+  | 'table'
+  | 'tabs'
+  | 'text'
+  | 'text-input'
+  | 'thinking'
+  | 'toast'
+  | 'toggle-group'
+  | 'tooltip';
+
+/** Options for `init()`. */
+export interface InitOptions {
+  /** Base URL for all assets. Derives `{baseUrl}/tokens.css`, `{baseUrl}/cx-utilities.css`, and `{baseUrl}/wasm_api_bg.wasm`. */
+  baseUrl?: string;
+  /** Explicit URL for tokens.css (overrides baseUrl). */
+  tokensUrl?: string;
+  /** Explicit URL for cx-utilities.css (overrides baseUrl). */
+  utilitiesUrl?: string;
+  /** Explicit URL for the WASM binary (overrides baseUrl). */
+  wasmUrl?: string;
+  /**
+   * Register only these components (kebab-case names). Default: all.
+   *
+   * Enables tree-shaking — only the behavior JS for listed components is
+   * downloaded. Unlisted components never leave the server.
+   *
+   * @example init({ components: ['button', 'text-input', 'select'] })
+   */
+  components?: ComponentName[];
+  /**
+   * If true, WASM loads in background — init() returns after styles load.
+   * Elements render immediately when WASM is ready (no blank flash).
+   *
+   * Combine with `components` for maximum performance:
+   * @example init({ lazy: true, components: ['button', 'card'] })
+   */
+  lazy?: boolean;
+}
+
+/**
+ * Initialize Collet Custom Elements.
+ *
+ * Loads WASM + shared styles, then registers Custom Elements.
+ * Must be called before using any <cx-*> element.
+ *
+ * Auto-detect mode (default, no "components" option): scans the DOM for
+ * existing <cx-*> elements and registers only those. A MutationObserver then
+ * watches for new elements added later (route changes, lazy loads) and
+ * auto-registers them on-demand. Zero configuration, zero waste.
+ *
+ * FOUC prevention: injects :not(:defined) CSS immediately, hiding
+ * <cx-*> elements until their class is registered. No flash of empty content.
+ *
+ * Component behavior JS is loaded via dynamic import — only the components
+ * you use are downloaded. Bundlers (Vite, Webpack, Rollup) automatically
+ * code-split each component into its own chunk.
+ *
+ * @example
+ * // Zero-config — auto-detects from DOM + watches for new elements
+ * await init();
+ *
+ * // Selective — only 3 components, no auto-detection
+ * await init({ components: ['button', 'text-input', 'select'] });
+ *
+ * // Lazy + auto-detect — fastest possible first paint
+ * await init({ lazy: true });
+ */
+export function init(options?: InitOptions): Promise<void>;
+
+/** All available component names for selective registration. */
+export const componentNames: readonly ComponentName[];
+
+export { CxElement, CxFormElement };

package/generated/index.js

@@ -0,0 +1,521 @@
+// Auto-generated by scripts/generate-elements.mjs — DO NOT EDIT
+// Main entry point for @colletdev/core Custom Elements.
+//
+// Usage:
+//   import { init } from '@colletdev/core';
+//   await init();                                                 // all components (recommended)
+//   await init({ components: ['button', 'card'] });               // only load what you use
+//   await init({ lazy: true });                                   // non-blocking WASM
+//   await init({ lazy: true, components: ['button', 'card'] });   // both optimizations
+//   // <cx-*> elements are now registered and functional.
+//
+// Tree-shaking: component behavior JS is loaded via dynamic import().
+// When using `components: [...]`, only the listed components' JS files
+// are downloaded — the rest never leave the server. Bundlers (Vite,
+// Webpack, Rollup) automatically code-split each component into its
+// own chunk.
+//
+// LAZY LOADING: WASM binary (~893 KB), CSS strings (~173 KB), and WASM
+// glue (~21 KB) are loaded via dynamic import() inside init() — NOT at
+// module level. This means `import { init } from '@colletdev/core'`
+// costs only ~4 KB. Everything else loads on-demand when init() is called.
+
+import { initWasm, loadSharedStyles, loadInlineSharedStyles, loadMotionStyles, loadInlineMotionStyles, injectTokensToHead, injectFoucPrevention, CxElement, CxFormElement } from '../src/runtime.js';
+
+// Package version — used for CDN fallback URL
+const PKG_VERSION = '0.1.3';
+
+// ─── Lazy WASM + CSS ───
+// WASM glue and CSS strings are NOT imported at module level.
+// They're loaded on first init() call via dynamic import(), which lets
+// bundlers code-split them into separate chunks. The main entry point
+// stays tiny (~4 KB) — the heavy assets only download when needed.
+let _cx_render = null;
+let _wasmInit = null;
+
+async function _ensureWasm() {
+  if (!_cx_render) {
+    const wasm = await import('../wasm/wasm_api.js');
+    _wasmInit = wasm.default;
+    _cx_render = wasm.cx_render;
+  }
+}
+
+// Thin wrappers: cx_render dispatcher → per-component functions.
+// Element definitions receive these as wasmFn(config) — the dispatcher
+// is invisible to consumers. Same DX, 91 KB less WASM.
+// The wrappers call _cx_render (populated by _ensureWasm in init).
+const cx_accordion = (config) => _cx_render('accordion', config);
+const cx_activity_group = (config) => _cx_render('activity_group', config);
+const cx_alert = (config) => _cx_render('alert', config);
+const cx_autocomplete = (config) => _cx_render('autocomplete', config);
+const cx_avatar = (config) => _cx_render('avatar', config);
+const cx_backdrop = (config) => _cx_render('backdrop', config);
+const cx_badge = (config) => _cx_render('badge', config);
+const cx_breadcrumb = (config) => _cx_render('breadcrumb', config);
+const cx_button = (config) => _cx_render('button', config);
+const cx_card = (config) => _cx_render('card', config);
+const cx_carousel = (config) => _cx_render('carousel', config);
+const cx_chat_input = (config) => _cx_render('chat_input', config);
+const cx_checkbox = (config) => _cx_render('checkbox', config);
+const cx_code_block = (config) => _cx_render('code_block', config);
+const cx_collapsible = (config) => _cx_render('collapsible', config);
+const cx_date_picker = (config) => _cx_render('date_picker', config);
+const cx_dialog = (config) => _cx_render('dialog', config);
+const cx_drawer = (config) => _cx_render('drawer', config);
+const cx_fab = (config) => _cx_render('fab', config);
+const cx_file_upload = (config) => _cx_render('file_upload', config);
+const cx_listbox = (config) => _cx_render('listbox', config);
+const cx_menu = (config) => _cx_render('menu', config);
+const cx_message_bubble = (config) => _cx_render('message_bubble', config);
+const cx_message_group = (config) => _cx_render('message_group', config);
+const cx_message_part = (config) => _cx_render('message_part', config);
+const cx_pagination = (config) => _cx_render('pagination', config);
+const cx_popover = (config) => _cx_render('popover', config);
+const cx_profile_menu = (config) => _cx_render('profile_menu', config);
+const cx_progress = (config) => _cx_render('progress', config);
+const cx_radio_group = (config) => _cx_render('radio_group', config);
+const cx_scrollbar = (config) => _cx_render('scrollbar', config);
+const cx_search_bar = (config) => _cx_render('search_bar', config);
+const cx_select = (config) => _cx_render('select', config);
+const cx_sidebar = (config) => _cx_render('sidebar', config);
+const cx_skeleton = (config) => _cx_render('skeleton', config);
+const cx_slider = (config) => _cx_render('slider', config);
+const cx_speed_dial = (config) => _cx_render('speed_dial', config);
+const cx_spinner = (config) => _cx_render('spinner', config);
+const cx_split_button = (config) => _cx_render('split_button', config);
+const cx_stepper = (config) => _cx_render('stepper', config);
+const cx_switch = (config) => _cx_render('switch', config);
+const cx_table = (config) => _cx_render('table', config);
+const cx_tabs = (config) => _cx_render('tabs', config);
+const cx_text = (config) => _cx_render('text', config);
+const cx_text_input = (config) => _cx_render('text_input', config);
+const cx_thinking = (config) => _cx_render('thinking', config);
+const cx_toast = (config) => _cx_render('toast', config);
+const cx_toggle_group = (config) => _cx_render('toggle_group', config);
+const cx_tooltip = (config) => _cx_render('tooltip', config);
+
+// Component registry — keyed by kebab-case name (matches <cx-{name}> tag).
+// Each thunk dynamically imports its element definition file and calls
+// customElements.define(). Only invoked components are downloaded.
+const _registry = {
+  'accordion': async () => {
+    const { defineCxAccordion } = await import('../src/elements/accordion.js');
+    defineCxAccordion(cx_accordion, CxElement);
+  },
+  'activity-group': async () => {
+    const { defineCxActivityGroup } = await import('../src/elements/activity_group.js');
+    defineCxActivityGroup(cx_activity_group, CxElement);
+  },
+  'alert': async () => {
+    const { defineCxAlert } = await import('../src/elements/alert.js');
+    defineCxAlert(cx_alert, CxElement);
+  },
+  'autocomplete': async () => {
+    const { defineCxAutocomplete } = await import('../src/elements/autocomplete.js');
+    defineCxAutocomplete(cx_autocomplete, CxFormElement);
+  },
+  'avatar': async () => {
+    const { defineCxAvatar } = await import('../src/elements/avatar.js');
+    defineCxAvatar(cx_avatar, CxElement);
+  },
+  'backdrop': async () => {
+    const { defineCxBackdrop } = await import('../src/elements/backdrop.js');
+    defineCxBackdrop(cx_backdrop, CxElement);
+  },
+  'badge': async () => {
+    const { defineCxBadge } = await import('../src/elements/badge.js');
+    defineCxBadge(cx_badge, CxElement);
+  },
+  'breadcrumb': async () => {
+    const { defineCxBreadcrumb } = await import('../src/elements/breadcrumb.js');
+    defineCxBreadcrumb(cx_breadcrumb, CxElement);
+  },
+  'button': async () => {
+    const { defineCxButton } = await import('../src/elements/button.js');
+    defineCxButton(cx_button, CxElement);
+  },
+  'card': async () => {
+    const { defineCxCard } = await import('../src/elements/card.js');
+    defineCxCard(cx_card, CxElement);
+  },
+  'carousel': async () => {
+    const { defineCxCarousel } = await import('../src/elements/carousel.js');
+    defineCxCarousel(cx_carousel, CxElement);
+  },
+  'chat-input': async () => {
+    const { defineCxChatInput } = await import('../src/elements/chat_input.js');
+    defineCxChatInput(cx_chat_input, CxElement);
+  },
+  'checkbox': async () => {
+    const { defineCxCheckbox } = await import('../src/elements/checkbox.js');
+    defineCxCheckbox(cx_checkbox, CxFormElement);
+  },
+  'code-block': async () => {
+    const { defineCxCodeBlock } = await import('../src/elements/code_block.js');
+    defineCxCodeBlock(cx_code_block, CxElement);
+  },
+  'collapsible': async () => {
+    const { defineCxCollapsible } = await import('../src/elements/collapsible.js');
+    defineCxCollapsible(cx_collapsible, CxElement);
+  },
+  'date-picker': async () => {
+    const { defineCxDatePicker } = await import('../src/elements/date_picker.js');
+    defineCxDatePicker(cx_date_picker, CxFormElement);
+  },
+  'dialog': async () => {
+    const { defineCxDialog } = await import('../src/elements/dialog.js');
+    defineCxDialog(cx_dialog, CxElement);
+  },
+  'drawer': async () => {
+    const { defineCxDrawer } = await import('../src/elements/drawer.js');
+    defineCxDrawer(cx_drawer, CxElement);
+  },
+  'fab': async () => {
+    const { defineCxFab } = await import('../src/elements/fab.js');
+    defineCxFab(cx_fab, CxElement);
+  },
+  'file-upload': async () => {
+    const { defineCxFileUpload } = await import('../src/elements/file_upload.js');
+    defineCxFileUpload(cx_file_upload, CxElement);
+  },
+  'listbox': async () => {
+    const { defineCxListbox } = await import('../src/elements/listbox.js');
+    defineCxListbox(cx_listbox, CxElement);
+  },
+  'menu': async () => {
+    const { defineCxMenu } = await import('../src/elements/menu.js');
+    defineCxMenu(cx_menu, CxElement);
+  },
+  'message-bubble': async () => {
+    const { defineCxMessageBubble } = await import('../src/elements/message_bubble.js');
+    defineCxMessageBubble(cx_message_bubble, CxElement);
+  },
+  'message-group': async () => {
+    const { defineCxMessageGroup } = await import('../src/elements/message_group.js');
+    defineCxMessageGroup(cx_message_group, CxElement);
+  },
+  'message-part': async () => {
+    const { defineCxMessagePart } = await import('../src/elements/message_part.js');
+    defineCxMessagePart(cx_message_part, CxElement);
+  },
+  'pagination': async () => {
+    const { defineCxPagination } = await import('../src/elements/pagination.js');
+    defineCxPagination(cx_pagination, CxElement);
+  },
+  'popover': async () => {
+    const { defineCxPopover } = await import('../src/elements/popover.js');
+    defineCxPopover(cx_popover, CxElement);
+  },
+  'profile-menu': async () => {
+    const { defineCxProfileMenu } = await import('../src/elements/profile_menu.js');
+    defineCxProfileMenu(cx_profile_menu, CxElement);
+  },
+  'progress': async () => {
+    const { defineCxProgress } = await import('../src/elements/progress.js');
+    defineCxProgress(cx_progress, CxElement);
+  },
+  'radio-group': async () => {
+    const { defineCxRadioGroup } = await import('../src/elements/radio_group.js');
+    defineCxRadioGroup(cx_radio_group, CxFormElement);
+  },
+  'scrollbar': async () => {
+    const { defineCxScrollbar } = await import('../src/elements/scrollbar.js');
+    defineCxScrollbar(cx_scrollbar, CxElement);
+  },
+  'search-bar': async () => {
+    const { defineCxSearchBar } = await import('../src/elements/search_bar.js');
+    defineCxSearchBar(cx_search_bar, CxElement);
+  },
+  'select': async () => {
+    const { defineCxSelect } = await import('../src/elements/select.js');
+    defineCxSelect(cx_select, CxFormElement);
+  },
+  'sidebar': async () => {
+    const { defineCxSidebar } = await import('../src/elements/sidebar.js');
+    defineCxSidebar(cx_sidebar, CxElement);
+  },
+  'skeleton': async () => {
+    const { defineCxSkeleton } = await import('../src/elements/skeleton.js');
+    defineCxSkeleton(cx_skeleton, CxElement);
+  },
+  'slider': async () => {
+    const { defineCxSlider } = await import('../src/elements/slider.js');
+    defineCxSlider(cx_slider, CxFormElement);
+  },
+  'speed-dial': async () => {
+    const { defineCxSpeedDial } = await import('../src/elements/speed_dial.js');
+    defineCxSpeedDial(cx_speed_dial, CxElement);
+  },
+  'spinner': async () => {
+    const { defineCxSpinner } = await import('../src/elements/spinner.js');
+    defineCxSpinner(cx_spinner, CxElement);
+  },
+  'split-button': async () => {
+    const { defineCxSplitButton } = await import('../src/elements/split_button.js');
+    defineCxSplitButton(cx_split_button, CxElement);
+  },
+  'stepper': async () => {
+    const { defineCxStepper } = await import('../src/elements/stepper.js');
+    defineCxStepper(cx_stepper, CxElement);
+  },
+  'switch': async () => {
+    const { defineCxSwitch } = await import('../src/elements/switch.js');
+    defineCxSwitch(cx_switch, CxFormElement);
+  },
+  'table': async () => {
+    const { defineCxTable } = await import('../src/elements/table.js');
+    defineCxTable(cx_table, CxElement);
+  },
+  'tabs': async () => {
+    const { defineCxTabs } = await import('../src/elements/tabs.js');
+    defineCxTabs(cx_tabs, CxElement);
+  },
+  'text': async () => {
+    const { defineCxText } = await import('../src/elements/text.js');
+    defineCxText(cx_text, CxElement);
+  },
+  'text-input': async () => {
+    const { defineCxTextInput } = await import('../src/elements/text_input.js');
+    defineCxTextInput(cx_text_input, CxFormElement);
+  },
+  'thinking': async () => {
+    const { defineCxThinking } = await import('../src/elements/thinking.js');
+    defineCxThinking(cx_thinking, CxElement);
+  },
+  'toast': async () => {
+    const { defineCxToast } = await import('../src/elements/toast.js');
+    defineCxToast(cx_toast, CxElement);
+  },
+  'toggle-group': async () => {
+    const { defineCxToggleGroup } = await import('../src/elements/toggle_group.js');
+    defineCxToggleGroup(cx_toggle_group, CxFormElement);
+  },
+  'tooltip': async () => {
+    const { defineCxTooltip } = await import('../src/elements/tooltip.js');
+    defineCxTooltip(cx_tooltip, CxElement);
+  },
+};
+
+// All available component names (for validation and enumeration)
+export const componentNames = Object.keys(_registry);
+
+// ─── WASM Loading with Fallback Chain ───
+// 1. Explicit URL (wasmUrl or baseUrl) — always tried first
+// 2. import.meta.url default (wasm-pack) — works in plain ESM, some bundlers
+// 3. public/ probe — checks if user copied WASM to public/ (common Vite pattern)
+// 4. CDN fallback (jsdelivr) — works when package is published to npm
+//
+// Helper: validate a WASM response before passing to WebAssembly.instantiate.
+// Prevents cryptic "expected magic word" errors when server returns HTML (SPA fallback).
+async function fetchWasmValidated(url) {
+  const resp = await fetch(url);
+  if (!resp.ok) throw new Error(`HTTP ${resp.status} for ${url}`);
+  const type = resp.headers.get('Content-Type') || '';
+  // Accept application/wasm, application/octet-stream, or no type (e.g., file:// protocol)
+  if (type && !type.includes('wasm') && !type.includes('octet-stream')) {
+    throw new Error(`Wrong MIME type "${type}" for ${url} (expected application/wasm)`);
+  }
+  return resp;
+}
+
+async function loadWasm(resolvedWasm) {
+  // Ensure WASM glue is loaded (lazy import)
+  await _ensureWasm();
+
+  // Explicit URL provided — use it directly
+  if (resolvedWasm) {
+    return initWasm(() => _wasmInit({ module_or_path: resolvedWasm }));
+  }
+
+  // Try default import.meta.url resolution (works in plain ESM + some bundlers)
+  try {
+    return await initWasm(() => _wasmInit());
+  } catch (primaryError) {
+    const msg = String(primaryError.message || primaryError);
+    const isBundlerIssue = msg.includes('expected magic word') || msg.includes('CompileError')
+      || msg.includes('failed to asynchronously prepare') || msg.includes('Unexpected token')
+      || msg.includes('Incorrect response MIME type');
+
+    if (!isBundlerIssue) throw primaryError;
+
+    // Try /wasm_api_bg.wasm (user may have copied to public/)
+    try {
+      const resp = await fetchWasmValidated('/wasm_api_bg.wasm');
+      return await initWasm(() => _wasmInit({ module_or_path: resp }));
+    } catch { /* not in public/ */ }
+
+    console.warn('[cx] WASM not found locally. Trying CDN...');
+
+    // CDN fallback — jsdelivr mirrors npm packages
+    const cdnUrl = `https://cdn.jsdelivr.net/npm/@colletdev/core@${PKG_VERSION}/wasm/wasm_api_bg.wasm`;
+    try {
+      const resp = await fetchWasmValidated(cdnUrl);
+      return await initWasm(() => _wasmInit({ module_or_path: resp }));
+    } catch (cdnError) {
+      throw new Error(
+        '[cx] WASM binary could not be loaded.\n\n' +
+        'Run this once after install:\n' +
+        '  cp node_modules/@colletdev/core/wasm/wasm_api_bg.wasm public/\n\n' +
+        'Then reload. No code changes needed — init() finds it automatically.\n\n' +
+        `(This step is not needed once @colletdev/core is published to npm.)\n` +
+        `Debug: ${primaryError.message}`
+      );
+    }
+  }
+}
+
+// ─── Auto-Detect ───
+// Scan the document for existing cx-* elements and return their names.
+// Used when init() is called without a components list — zero-config tree-shaking.
+function detectComponentsFromDOM() {
+  const found = new Set();
+  for (const el of document.querySelectorAll('*')) {
+    const tag = el.tagName.toLowerCase();
+    if (tag.startsWith('cx-')) {
+      const name = tag.slice(3);
+      if (name in _registry) found.add(name);
+    }
+  }
+  return found;
+}
+
+// ─── SPA Auto-Registration ───
+// MutationObserver watches for new cx-* elements entering the DOM after init().
+// When a new Collet element appears (React route change, lazy-loaded component,
+// conditional render), its behavior JS is dynamically imported and registered
+// automatically. The developer never needs to maintain a component list.
+let _observer = null;
+const _registered = new Set();
+
+function startAutoRegistration() {
+  if (_observer) return;
+  _observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node.nodeType !== 1) continue;
+        // Check the added node itself
+        _maybeRegister(node);
+        // Check descendants (e.g., a React subtree mount)
+        if (node.querySelectorAll) {
+          for (const child of node.querySelectorAll('*')) {
+            _maybeRegister(child);
+          }
+        }
+      }
+    }
+  });
+  _observer.observe(document.body, { childList: true, subtree: true });
+}
+
+function _maybeRegister(el) {
+  const tag = el.tagName.toLowerCase();
+  if (!tag.startsWith('cx-')) return;
+  const name = tag.slice(3);
+  if (_registered.has(name) || !(name in _registry)) return;
+  _registered.add(name);
+  // Fire-and-forget — dynamic import + define. Element renders
+  // when its class upgrades (built into Custom Elements spec).
+  _registry[name]();
+}
+
+export async function init(options = {}) {
+  const {
+    // Explicit asset URLs (optional — zero-config works without these)
+    baseUrl,
+    tokensUrl,
+    utilitiesUrl,
+    wasmUrl,
+    // Selective: only register these components (kebab-case names, e.g. 'button', 'text-input')
+    components,
+    // Lazy: start WASM loading but don't wait — elements render when WASM is ready
+    lazy,
+  } = options;
+
+  // FOUC prevention — injected immediately, before any async work.
+  // Hides cx-* elements via :not(:defined) until their class registers.
+  injectFoucPrevention(Object.keys(_registry));
+
+  const useExplicitCss = !!(tokensUrl || utilitiesUrl || baseUrl != null);
+
+  // Use != null (not truthiness) so baseUrl: '' works correctly
+  const resolvedTokens = tokensUrl || (baseUrl != null ? `${baseUrl}/tokens.css` : null);
+  const resolvedUtilities = utilitiesUrl || (baseUrl != null ? `${baseUrl}/cx-utilities.css` : null);
+  const resolvedWasm = wasmUrl || (baseUrl != null ? `${baseUrl}/wasm_api_bg.wasm` : undefined);
+
+  // Start WASM loading (with fallback chain)
+  const wasmPromise = loadWasm(resolvedWasm);
+
+  const styleTasks = [];
+
+  if (useExplicitCss) {
+    // Explicit URLs provided — fetch CSS from URLs (original behavior)
+    if (resolvedUtilities) {
+      styleTasks.push(loadSharedStyles([resolvedUtilities]));
+    }
+    if (resolvedTokens) {
+      if (!document.querySelector(`link[href="${resolvedTokens}"]`)) {
+        const link = document.createElement('link');
+        link.rel = 'stylesheet';
+        link.href = resolvedTokens;
+        document.head.appendChild(link);
+      }
+      styleTasks.push(loadMotionStyles(resolvedTokens));
+    }
+  } else {
+    // Zero-config — lazy-load CSS strings (dynamic import keeps them out of main chunk).
+    // TOKENS_CSS goes to <head> (vars, fonts, themes — inherits into Shadow DOM).
+    // TOKENS_SHADOW_CSS is the pre-split Shadow DOM subset (animations, motion, component rules).
+    // No runtime CSS parsing needed — the build produces the exact strings for each context.
+    const { TOKENS_CSS, TOKENS_SHADOW_CSS, UTILITIES_CSS } = await import('./styles.js');
+    injectTokensToHead(TOKENS_CSS);
+    styleTasks.push(loadInlineMotionStyles(TOKENS_SHADOW_CSS));
+    styleTasks.push(loadInlineSharedStyles(UTILITIES_CSS));
+  }
+
+  if (lazy) {
+    await Promise.all(styleTasks);
+  } else {
+    await Promise.all([wasmPromise, ...styleTasks]);
+  }
+
+  // Determine which components to register.
+  let names;
+  let autoDetected = false;
+
+  if (components) {
+    // Explicit list — register exactly these, warn on unknowns.
+    names = components.filter(c => c in _registry);
+    const unknown = components.filter(c => !(c in _registry));
+    if (unknown.length > 0) {
+      console.warn(`[cx] Unknown components: ${unknown.join(', ')}. Available: ${Object.keys(_registry).join(', ')}`);
+    }
+  } else {
+    // Auto-detect: scan DOM for cx-* elements already present.
+    const found = detectComponentsFromDOM();
+    if (found.size > 0) {
+      names = [...found];
+      autoDetected = true;
+    } else {
+      // Nothing in DOM yet (SPA with deferred rendering) — register all.
+      names = Object.keys(_registry);
+    }
+  }
+
+  // Register components — dynamic imports load only their behavior JS.
+  await Promise.all(names.map(name => _registry[name]()));
+  for (const name of names) _registered.add(name);
+
+  // Start MutationObserver for SPA auto-registration.
+  // New cx-* elements that appear later (route changes, lazy loads)
+  // are automatically imported and registered on-demand.
+  if (!components) {
+    startAutoRegistration();
+  }
+
+  const mode = autoDetected ? ` Auto-detected ${names.length} from DOM.` : '';
+  console.log(`[cx] ${names.length} Custom Elements registered.${lazy ? ' WASM loading in background.' : ' WASM ready.'}${mode}`);
+}
+
+// Re-export base classes for advanced usage
+export { CxElement, CxFormElement };