microui-wc 0.1.0

package/dist/AGENTS.md

@@ -0,0 +1,2366 @@
+# microUI - AI Agent Documentation
+
+> **SOTA reference for AI coding assistants.** This document is optimized for LLMs generating microUI code.
+
+## 🚨 REGOLE INVIOLABILI
+
+> [!CAUTION]
+> Queste regole NON POSSONO MAI essere violate. Qualsiasi codice che viola queste regole deve essere rifiutato.
+
+### ❌ NO SHADOW DOM
+
+**microUI NON DEVE MAI usare Shadow DOM.** Tutti i componenti devono:
+- Usare Light DOM (il DOM normale)
+- Inserire gli elementi direttamente nel documento
+- Usare classi CSS con prefisso `mu-` per l'incapsulamento
+- Mai usare `this.attachShadow()` o `this.shadowRoot`
+
+```javascript
+// ❌ VIETATO - Non usare MAI
+this.attachShadow({ mode: 'open' });
+this.shadowRoot.innerHTML = '...';
+
+// ✅ CORRETTO - Usa Light DOM
+this.innerHTML = '...';
+this.classList.add('mu-component');
+```
+
+### 🧪 TEST ISOLATION OBBLIGATORIA
+
+**I test DEVONO essere eseguiti con `test-isolated.js`**, mai con `bun test` diretto.
+
+```bash
+# ❌ SBAGLIATO - Test falliscono per linkedom globalThis pollution
+bun test tests/components
+
+# ✅ CORRETTO - Ogni test in processo separato
+bun run scripts/test-isolated.js
+
+# ✅ CORRETTO - E2E tests
+bun run test:e2e
+```
+
+**Perché?** linkedom (usato per simulare DOM in unit test) inquina `globalThis` e il registry dei custom elements. Quando i test vengono eseguiti in parallelo nello stesso processo, le registrazioni entrano in conflitto.
+
+---
+
+## 🛠️ COMPONENT DEVELOPMENT GUIDELINES
+
+> **Linee guida obbligatorie per creare nuovi componenti microUI.** Seguire queste regole previene memory leak, crash e garantisce consistenza con il framework.
+
+### 📋 Template Componente Completo
+
+```javascript
+/**
+ * mu-example.js - Description of what this component does
+ * 
+ * @example
+ * <mu-example label="Test" value="123"></mu-example>
+ */
+
+import { MuElement, define } from '../core/MuElement.js';
+import { escapeHTML } from '../core/utils.js';  // Per contenuti user-facing
+
+export class MuExample extends MuElement {
+    static get observedAttributes() {
+        return ['label', 'value', 'disabled'];
+    }
+
+    static baseClass = 'mu-example';
+    static cssFile = 'example';
+
+    constructor() {
+        super();
+        this._internalState = null;
+    }
+
+    // ========================
+    // LIFECYCLE (OBBLIGATORIO)
+    // ========================
+    
+    connectedCallback() {
+        super.connectedCallback();  // ⚠️ OBBLIGATORIO - Inizializza AbortController
+        this.render();
+    }
+
+    disconnectedCallback() {
+        super.disconnectedCallback();  // ⚠️ OBBLIGATORIO se usi timer/subscriptions
+        // Cleanup subscriptions manuali (es. breakpoints.subscribe)
+    }
+
+    attributeChangedCallback(name, oldVal, newVal) {
+        if (this.isConnected && oldVal !== newVal) {
+            this.render();
+        }
+    }
+
+    // ========================
+    // PROPERTIES
+    // ========================
+
+    get label() {
+        return this.getAttribute('label') || '';
+    }
+
+    get value() {
+        return this.getAttribute('value') || '';
+    }
+
+    get disabled() {
+        return this.hasAttribute('disabled');
+    }
+
+    // ========================
+    // RENDER (XSS-Safe)
+    // ========================
+
+    render() {
+        // ✅ SEMPRE escapare contenuti user-facing
+        this.innerHTML = `
+            <div class="mu-example">
+                <label>${escapeHTML(this.label)}</label>
+                <input 
+                    type="text" 
+                    value="${escapeHTML(this.value)}"
+                    placeholder="${escapeHTML(this.getAttribute('placeholder') || '')}"
+                    ${this.disabled ? 'disabled' : ''}
+                >
+            </div>
+        `;
+        this._attachEventListeners();
+    }
+
+    // ========================
+    // EVENT LISTENERS (Memory-Safe)
+    // ========================
+
+    _attachEventListeners() {
+        const input = this.querySelector('input');
+        
+        // ✅ CORRETTO: Usa this.listen() per auto-cleanup
+        this.listen(input, 'input', (e) => {
+            this.dispatchEvent(new CustomEvent('mu-input', {
+                bubbles: true,
+                detail: { value: e.target.value }
+            }));
+        });
+
+        // ✅ CORRETTO: this.listen() per eventi window/document
+        this.listen(window, 'resize', () => this._handleResize());
+        
+        // ✅ CORRETTO: Keyboard accessibility
+        if (!this.disabled) {
+            this.setupActivation(() => this._handleClick());
+        }
+    }
+
+    // ========================
+    // TIMER (Memory-Safe)
+    // ========================
+
+    _startPolling() {
+        // ✅ CORRETTO: Usa this.setInterval() per auto-cleanup
+        this.setInterval(() => this._poll(), 5000);
+    }
+
+    _debounce() {
+        // ✅ CORRETTO: Usa this.setTimeout() per auto-cleanup
+        this.setTimeout(() => this._doSomething(), 300);
+    }
+
+    // ========================
+    // ERROR REPORTING (AI Agent)
+    // ========================
+
+    _validate() {
+        if (!this.label) {
+            // ✅ Segnala errori per AI agent debugging
+            this.logError('MISSING_LABEL', 'mu-example requires a label attribute');
+        }
+    }
+}
+
+// Registration (idempotent)
+if (!customElements.get('mu-example')) {
+    customElements.define('mu-example', MuExample);
+}
+```
+
+### ⚠️ ANTI-PATTERN: Cosa NON Fare Mai
+
+```javascript
+// ❌ VIETATO: addEventListener diretto (memory leak)
+this.querySelector('button').addEventListener('click', handler);
+
+// ❌ VIETATO: setTimeout/setInterval raw (memory leak)
+setTimeout(() => this.update(), 1000);
+setInterval(() => this.poll(), 5000);
+
+// ❌ VIETATO: Nessun super.connectedCallback() (AbortController non inizializzato)
+connectedCallback() {
+    this.render();  // this.listen() non funzionerà!
+}
+
+// ❌ VIETATO: innerHTML senza escaping (XSS vulnerability)
+this.innerHTML = `<div>${userInput}</div>`;
+
+// ❌ VIETATO: removeEventListener con arrow function (non funziona mai)
+window.removeEventListener('resize', () => this.handleResize());
+
+// ❌ VIETATO: Temporal dead zone con setTimeout
+const id = setTimeout(() => { this._timers.delete(id); }, delay);
+
+// ❌ VIETATO: Shadow DOM
+this.attachShadow({ mode: 'open' });
+
+// ❌ VIETATO: DOM Teleportation senza reset del flag listener (Bug Jan 2026)
+// Quando un componente sposta SE STESSO nel DOM (es. appendChild(this)),
+// disconnectedCallback aborta i listener ma il flag impedisce ri-registrazione
+connectedCallback() {
+    if (!this._listenerSetup) {  // ⚠️ Il flag resta true dopo disconnect!
+        this._listenerSetup = true;
+        this.listen(this, 'click', handler);  // Perso dopo teleportation
+    }
+}
+// ✅ CORRETTO: Reset del flag in disconnectedCallback
+disconnectedCallback() {
+    super.disconnectedCallback();
+    this._listenerSetup = false;  // Permette ri-registrazione dopo move
+}
+```
+
+### ✅ PATTERN OBBLIGATORI
+
+| Pattern | Metodo | Perché |
+|---------|--------|--------|
+| **Event Listeners** | `this.listen(target, type, handler)` | Auto-cleanup via AbortController |
+| **Timers** | `this.setTimeout()` / `this.setInterval()` | Auto-cleanup su disconnectedCallback |
+| **XSS Prevention** | `escapeHTML(userInput)` | Previene injection in innerHTML |
+| **Keyboard A11y** | `this.setupActivation(callback)` | Gestisce Enter/Space per elementi interattivi |
+| **AI Debugging** | `this.logError(code, message)` | Errori strutturati per AI agents |
+| **Lifecycle** | `super.connectedCallback()` | Inizializza AbortController per this.listen() |
+| **DOM Teleportation** | Reset flag in `disconnectedCallback()` | Previene listener orfani dopo move |
+
+### 🚀 SOTA Patterns (Feb 2026)
+
+Pattern moderni che dovrebbero essere usati per nuovi componenti e per migrazioni.
+
+#### ✅ Performance CSS (COMPLETATO - v3.5.28)
+
+Il framework applica **by default** le seguenti ottimizzazioni:
+
+| Tecnica | File | Beneficio |
+|---------|------|-----------|
+| `will-change` | animations.css | GPU compositor hints per 13+ classi animazione |
+| `CSS contain` | layout.css, components.css | Isola repaint scope per mu-layout, modals |
+| `content-visibility: auto` | components.css | Skip rendering off-screen per mu-example |
+| Speculation Rules API | shell.html | Prefetch route bundle predittivo |
+| View Transitions API | shell.html | Animazioni smooth tra pagine SPA |
+
+**Lighthouse Score**: 98/100 Performance, 100/100 Accessibility/BP/SEO
+
+```css
+/* Framework applica automaticamente: */
+mu-example {
+    content-visibility: auto;
+    contain-intrinsic-size: auto 300px;
+}
+
+mu-layout {
+    contain: layout style;
+}
+
+.mu-spin {
+    animation: mu-spin 1s linear infinite;
+    will-change: transform;
+}
+```
+
+#### ✅ Native `<dialog>` per Modal (COMPLETATO)
+**mu-modal** usa ora `<dialog>` nativo con `showModal()`:
+- Top-layer automatico (niente z-index manuali)
+- Focus trap built-in
+- ESC key gestito nativamente
+- `::backdrop` per scrim animato
+- `margin: auto` per centrare
+
+```javascript
+// ✅ SOTA: Native dialog
+this.#dialog = document.createElement('dialog');
+this.#dialog.showModal();
+
+// ❌ VECCHIO: Position fixed + z-index + manual focus trap
+this.style.cssText = 'position:fixed;z-index:9999;';
+document.body.appendChild(this);
+```
+
+#### 🔜 Popover API (CANDIDATI)
+I seguenti componenti potrebbero beneficiare della **Popover API**:
+
+| Componente | Pattern Attuale | SOTA Migration |
+|------------|----------------|----------------|
+| `mu-dropdown` | Portal container + z-index | `popover` attribute |
+| `mu-tooltip` | Position fixed + z-index | `popover` attribute |
+
+**Benefici Popover API**:
+- Light-dismiss automatico (click outside)
+- Top-layer (niente z-index issues)
+- `showPopover()` / `hidePopover()` / `togglePopover()`
+- Keyboard accessibility built-in
+
+```html
+<!-- SOTA: Declarative popover -->
+<button popovertarget="my-menu">Open</button>
+<div id="my-menu" popover>Menu content</div>
+```
+
+### 🔒 Security Checklist
+
+Prima di completare un componente, verifica:
+
+- [ ] Tutti i contenuti user-facing usano `escapeHTML()`
+- [ ] Attributi interpolati in innerHTML sono escaped
+- [ ] Slot content controllato (developer-provided) o escaped
+- [ ] Nessun `eval()`, `Function()`, `document.write()`
+
+### ♿ Accessibility Checklist
+
+- [ ] Elementi interattivi hanno `tabindex="0"`
+- [ ] Role ARIA appropriato (`role="button"`, `role="menuitem"`, etc.)
+- [ ] `setupActivation()` per attivazione via keyboard (Enter/Space)
+- [ ] `aria-label` o label associata per screen reader
+- [ ] Stati (`aria-checked`, `aria-expanded`, etc.) aggiornati dinamicamente
+
+### 🧪 Testing Checklist
+
+- [ ] Unit test con `bun run scripts/test-isolated.js`
+- [ ] E2E test per interazioni browser reali
+- [ ] Coverage ≥97%
+- [ ] Test memory leak: componente aggiunto/rimosso dal DOM non lascia listener
+
+---
+
+## TL;DR - Copy-Paste Templates
+
+### Agent-First Features (v3.5)
+microUI is optimized for AI Agents with deep introspection, runtime feedback, enterprise-scale infrastructure, and 2026 multimodal/MCP support.
+
+**1. Introspection (Metadata)**
+A `custom-elements.json` manifest is included in the root. Agents can read this to understand:
+- Component Attributes (names, types, defaults)
+- Events and payloads
+- CSS Shadow Parts
+
+**2. Runtime Debugging (Agent Logger)**
+Components validate usage and log structured errors to `window.__MICROUI_ERRORS__`.
+```javascript
+// Check for errors in E2E tests
+const errors = await page.evaluate(() => window.__MICROUI_ERRORS__);
+if (errors.length > 0) console.error('microUI Errors:', errors);
+```
+
+**3. Agent API (v3.3) - LLM-Friendly Component Access**
+Direct API for LLM agents to introspect and interact with components:
+
+```javascript
+// Get all components as structured data (for agent parsing)
+const tree = microUI.getMuComponentTree();
+// Returns: [{ tag, id, label, description, state, actions, rect, interactive, visible }]
+
+// Get only interactive visible components
+const buttons = microUI.getMuComponentTree(document.body, {
+    visibleOnly: true,
+    interactiveOnly: true
+});
+
+// Describe a component in natural language
+microUI.describeComponent('#submit-btn');
+// Returns: 'Button "Submit". Click to activate.'
+
+// Find components by label (fuzzy match)
+const matches = microUI.findByLabel('save');
+
+// Get all registered microUI components
+const components = microUI.getRegisteredComponents();
+// Returns: Map<tag, constructor>
+```
+
+**4. Enterprise-Scale Features (v3.4) - Large Application Infrastructure**
+
+For building complex, multi-team applications:
+
+```javascript
+// === NAMESPACED STORES ===
+// Isolated state per feature/team - no conflicts
+const userStore = microUI.createNamespacedStore('user', { profile: null });
+const cartStore = microUI.createNamespacedStore('cart', { items: [] });
+
+// Access stores by namespace
+microUI.getStore('user');       // Returns userStore
+microUI.getAllStores();         // { user: ..., cart: ... }
+
+// Serialize/restore entire app state
+const snapshot = microUI.captureAppState();
+localStorage.setItem('state', JSON.stringify(snapshot));
+microUI.restoreAppState(JSON.parse(localStorage.getItem('state')));
+
+// === FEATURE REGISTRY ===
+// Organize code by feature for multi-team development
+microUI.createFeature('user', {
+    routes: ['/profile', '/settings'],
+    store: userStore,
+    components: ['mu-user-card', 'mu-user-form'],
+    meta: { team: 'user-team' }
+});
+
+microUI.getFeatures();              // All features
+microUI.getFeatureSummary();        // Overview with stats
+microUI.getFeatureComponents('user'); // Components in feature
+
+// === OBSERVABILITY ===
+// Track state changes for debugging
+microUI.enableObservability();
+microUI.getStateHistory('user');    // Timeline of state changes
+microUI.getErrors();                // All caught errors
+```
+
+```html
+<!-- === ERROR BOUNDARIES === -->
+<!-- Catch errors with fallback UI - one error doesn't crash everything -->
+<mu-error-boundary fallback="<p>Something went wrong</p>">
+    <mu-complex-widget></mu-complex-widget>
+</mu-error-boundary>
+
+<!-- Custom error handling -->
+<mu-error-boundary onerror="logError(event.detail.error)">
+    <mu-data-table :items="${data}"></mu-data-table>
+</mu-error-boundary>
+```
+
+**5. Agent Automation (v3.5) - 2026 Multimodal & MCP Support**
+
+Based on UI-TARS, A2UI, and Anthropic MCP research (2025-2026):
+
+```javascript
+// === VISUAL MARKERS (for screenshot-based agents) ===
+// Enable overlay labels for multimodal AI agents
+microUI.enableVisualMarkers({ style: 'badge' }); // or 'outline'
+
+// Agent takes screenshot, sees: [B1] Save, [B2] Cancel, [I1] Email
+// Then references elements by marker ID:
+const saveBtn = microUI.getMarkerElement('B1');
+saveBtn.click();
+
+// Get all marker mappings
+microUI.getMarkerMap();
+// { B1: { tag: 'mu-button', label: 'Save' }, I1: { tag: 'mu-input'... } }
+
+microUI.disableVisualMarkers(); // Clean up
+
+// === STRUCTURED SCHEMA (for code generation) ===
+// Get JSON Schema for type-safe code gen
+microUI.getComponentSchema('mu-button');
+// { properties: { variant: { enum: ['filled'...] } }, actions: ['click'] }
+
+microUI.getAllSchemas();           // All 11 documented components
+microUI.getSchemaQuickRef('mu-input'); // Minimal summary
+
+// === MCP ACTIONS (standard agent-tool protocol) ===
+// MCP-compatible action definitions (Anthropic/Google 2026 standard)
+microUI.getMCPActions();
+// Returns 10 standardized actions:
+// click_button, fill_input, toggle_checkbox, select_option,
+// open_modal, close_modal, select_tab, get_component_tree,
+// enable_visual_markers, confirm_dialog
+```
+
+**Semantic Attributes (auto-inferred):**
+```html
+<!-- Components auto-add data-mu-action and data-mu-role -->
+<mu-button variant="filled">Save</mu-button>
+<!-- Becomes: data-mu-action="submit" data-mu-role="primary-action" -->
+
+<mu-button variant="text">Cancel</mu-button>
+<!-- Becomes: data-mu-action="cancel" data-mu-role="tertiary-action" -->
+```
+
+### Minimal Page Setup
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link rel="stylesheet" href="dist/microui.css">
+</head>
+<body>
+    <!-- Your content here -->
+    <script type="module" src="dist/microui.esm.js"></script>
+</body>
+</html>
+```
+
+### Common Patterns (Copy These)
+
+```html
+<!-- Form with validation -->
+<mu-form>
+    <mu-stack gap="md">
+        <mu-input label="Email" type="email" required></mu-input>
+        <mu-input label="Password" type="password" required></mu-input>
+        <mu-button variant="filled">Submit</mu-button>
+    </mu-stack>
+</mu-form>
+
+<!-- Card layout -->
+<mu-grid cols="3" gap="md">
+    <mu-card variant="elevated">
+        <h3>Title</h3>
+        <p>Content</p>
+        <mu-button variant="text">Action</mu-button>
+    </mu-card>
+</mu-grid>
+
+<!-- Navigation tabs -->
+<mu-tabs active="0">
+    <mu-tab>Tab 1</mu-tab>
+    <mu-tab>Tab 2</mu-tab>
+</mu-tabs>
+
+<!-- Modal dialog -->
+<mu-modal id="my-modal">
+    <h2>Modal Title</h2>
+    <p>Content</p>
+    <mu-button onclick="this.closest('mu-modal').close()">Close</mu-button>
+</mu-modal>
+<mu-button onclick="document.getElementById('my-modal').open()">Open Modal</mu-button>
+
+<!-- Toast notification -->
+<script type="module">
+import { showToast } from './dist/microui.esm.js';
+showToast('Success!', { variant: 'success', duration: 3000 });
+</script>
+```
+
+---
+
+## Quick Reference
+
+### All Components (49)
+
+| Category | Components | Common Attributes |
+|----------|------------|-------------------|
+| **Layout** | `mu-container`, `mu-stack`, `mu-grid`, `mu-navbar`, `mu-sidebar`, `mu-divider` | `gap="xs\|sm\|md\|lg"`, `direction="row\|column"` |
+| **Form** | `mu-button`, `mu-input`, `mu-textarea`, `mu-checkbox`, `mu-switch`, `mu-radio`, `mu-radio-group`, `mu-dropdown`, `mu-option`, `mu-chip`, `mu-form` | `variant`, `disabled`, `required`, `value` |
+| **Display** | `mu-card`, `mu-tabs`, `mu-tab`, `mu-table`, `mu-avatar`, `mu-badge`, `mu-progress`, `mu-skeleton`, `mu-alert`, `mu-icon` | `variant="elevated\|outlined\|filled"` |
+| **Feedback** | `mu-modal`, `mu-toast`, `mu-toast-container`, `mu-tooltip`, `mu-spinner`, `mu-confirm` | `duration`, `position` |
+| **Performance** | `mu-virtual-list`, `mu-lazy`, `mu-repeat` | `items`, `renderItem` |
+| **Data** | `mu-fetch` | `url`, `auto`, `interval` |
+| **Enterprise** | `mu-error-boundary` | `fallback` |
+| **Utility** | `mu-theme-toggle` | - |
+
+### Attribute Cheatsheet
+
+```html
+<!-- Sizes -->
+size="xs" | size="sm" | size="md" | size="lg" | size="xl"
+
+<!-- Gaps (for layout) -->
+gap="xs" (4px) | gap="sm" (8px) | gap="md" (16px) | gap="lg" (24px) | gap="xl" (32px)
+
+<!-- Button variants -->
+variant="filled" | variant="elevated" | variant="tonal" | variant="outlined" | variant="text" | variant="danger"
+
+<!-- Card variants -->
+variant="elevated" | variant="outlined" | variant="filled"
+
+<!-- Alert variants -->
+variant="info" | variant="success" | variant="warning" | variant="error"
+
+<!-- Direction (stack) -->
+direction="row" | direction="column"
+
+<!-- Alignment -->
+align="start" | align="center" | align="end" | align="stretch"
+justify="start" | justify="center" | justify="end" | justify="space-between"
+```
+
+---
+
+## Component Details
+
+### mu-button
+```html
+<mu-button variant="filled" size="md" disabled>Label</mu-button>
+```
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `variant` | `filled`, `elevated`, `tonal`, `outlined`, `text`, `danger` | `filled` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `disabled` | boolean | `false` |
+
+**Events:** `click` (native)
+
+### mu-input
+```html
+<mu-input label="Email" type="email" placeholder="Enter email" required></mu-input>
+```
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `type` | `text`, `email`, `password`, `number`, `tel`, `url` | `text` |
+| `label` | string | - |
+| `placeholder` | string | - |
+| `value` | string | `""` |
+| `disabled` | boolean | `false` |
+| `required` | boolean | `false` |
+| `variant` | `outlined`, `filled` | `outlined` |
+
+**Events:** `mu-input` (on keystroke), `mu-change` (on blur)
+**Accessibility:** Uses `for/id` association, `aria-label` fallback
+
+**Accessibility:** `role="checkbox"`, `aria-checked="true|false|mixed"`, keyboard (Space/Enter)
+
+### mu-switch
+```html
+<mu-switch label="Dark mode" checked></mu-switch>
+```
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `label` | string | - |
+| `checked` | boolean | `false` |
+| `disabled` | boolean | `false` |
+
+**Events:** `mu-change` with `{ checked: boolean }`
+**Accessibility:** `role="switch"`, `aria-checked`, keyboard (Space/Enter)
+
+### mu-radio-group / mu-radio
+```html
+<mu-radio-group name="size" value="md">
+    <mu-radio value="sm">Small</mu-radio>
+    <mu-radio value="md">Medium</mu-radio>
+    <mu-radio value="lg">Large</mu-radio>
+</mu-radio-group>
+```
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `name` | string (group) | - |
+| `value` | string | - |
+| `disabled` | boolean | `false` |
+
+**Events:** `mu-change` with `{ value: string }` on group
+**Accessibility:** `role="radiogroup"`, `role="radio"`, `aria-checked`
+
+### mu-dropdown
+```html
+<mu-dropdown placeholder="Select option" value="1">
+    <mu-option value="1">Option 1</mu-option>
+    <mu-option value="2">Option 2</mu-option>
+</mu-dropdown>
+```
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `placeholder` | string | - |
+| `value` | string | - |
+| `disabled` | boolean | `false` |
+
+**Events:** `mu-change` with `{ value: string, label: string }`
+**Events:** `mu-change` with `{ value: string, label: string }`
+**Accessibility:** `role="listbox"`, `aria-expanded`, full keyboard navigation (Arrows, Enter, Escape, Space)
+
+### mu-modal
+```html
+<mu-modal id="dialog">
+    <h2>Title</h2>
+    <p>Content</p>
+</mu-modal>
+```
+**Methods:** `.open()`, `.close()`
+**Events:** `mu-open`, `mu-close`
+
+### mu-tabs / mu-tab
+```html
+<mu-tabs active="0" id="my-tabs">
+    <mu-tab>First</mu-tab>
+    <mu-tab>Second</mu-tab>
+</mu-tabs>
+```
+**Events:** `mu-change` with `{ index: number }`
+
+### mu-stack (Flexbox layout)
+```html
+<mu-stack direction="row" gap="md" align="center" justify="space-between">
+    <div>Item 1</div>
+    <div>Item 2</div>
+</mu-stack>
+```
+
+### mu-grid (CSS Grid)
+```html
+<mu-grid cols="3" gap="md">
+    <mu-card>1</mu-card>
+    <mu-card>2</mu-card>
+    <mu-card>3</mu-card>
+</mu-grid>
+```
+**Responsive Behavior:** Grids with `cols="3"`, `cols="4"`, or `cols="6"` **automatically collapse to 1 column** on mobile (< 600px).
+
+### mu-virtual-list (10K+ items)
+```javascript
+const list = document.querySelector('mu-virtual-list');
+list.items = largeArray;
+list.itemHeight = 50;
+list.renderItem = (item) => `<div class="item">${item.name}</div>`;
+```
+
+---
+
+## Responsive Breakpoints (MD3)
+
+microUI follows **Material Design 3 Window Size Classes** for adaptive layouts:
+
+| Class | Width | Components Behavior |
+|-------|-------|---------------------|
+| **Compact** | < 600px | `mu-grid` → 1 column, `mu-bottom-nav` visible, `mu-drawer` → modal |
+| **Medium** | 600-839px | `mu-drawer` → rail mode |
+| **Expanded** | ≥ 840px | `mu-drawer` → expanded, `mu-bottom-nav` hidden |
+
+### Breakpoints API
+```javascript
+import { breakpoints } from 'microui/core/breakpoints';
+
+// Reactive subscriptions (for components that need to react to changes)
+const unsubscribe = breakpoints.subscribe((size) => {
+    console.log(`Now in ${size} mode`); // 'compact', 'medium', 'expanded'
+});
+
+// Direct checks (live queries - always current, no caching)
+if (breakpoints.isCompact) {
+    // Mobile-specific logic
+}
+
+if (breakpoints.isMedium) {
+    // Tablet-specific logic
+}
+
+if (breakpoints.isExpanded) {
+    // Desktop-specific logic
+}
+
+// Cleanup when done
+unsubscribe();
+```
+
+### Best Practices for Responsive Agents
+
+1. **Don't hardcode media queries** - Use the centralized `breakpoints` utility
+2. **Use CSS for simple responsive** - `mu-grid` automatically collapses via CSS
+3. **Subscribe for complex logic** - Components needing JS-driven adaptation should subscribe
+4. **Clean up subscriptions** - Always unsubscribe in `disconnectedCallback()`
+
+```javascript
+// Example: Component that adapts to breakpoints
+class MyComponent extends MuElement {
+    #unsubscribe = null;
+
+    connectedCallback() {
+        super.connectedCallback();
+        this.#unsubscribe = breakpoints.subscribe(() => {
+            this.#updateLayout();
+        });
+    }
+
+    disconnectedCallback() {
+        this.#unsubscribe?.();
+    }
+
+    #updateLayout() {
+        if (breakpoints.isCompact) {
+            this.classList.add('mobile');
+        } else {
+            this.classList.remove('mobile');
+        }
+    }
+}
+```
+
+---
+
+## JavaScript API
+
+### Signals (Reactive State)
+```javascript
+import { signal, computed, effect } from 'microui';
+
+const count = signal(0, 'my-counter');  // name for debugging
+const doubled = computed(() => count() * 2);
+
+effect(() => {
+    console.log('Count:', count());  // Auto-tracks dependencies
+});
+
+count.set(5);           // Set value
+count.update(n => n + 1); // Update with function
+count.peek();           // Read without tracking
+```
+
+### EventBus (CrossBus)
+```javascript
+import { bus } from 'microui';
+
+// Subscribe
+const unsub = bus.on('my:event', (data) => console.log(data));
+
+// Emit (111M ops/sec - synchronous)
+bus.emit('my:event', { key: 'value' });
+
+// Cleanup
+unsub();
+```
+
+### Keyboard Manager (ESC Stack)
+
+Centralized LIFO stack for handling ESC key in modal-like components. When multiple modals/dropdowns are open, ESC closes only the **topmost** one.
+
+```javascript
+import { keyboard } from 'microui/core/keyboard';
+
+class MuMyModal extends MuElement {
+    #unsubEsc = null;
+
+    open() {
+        this.hidden = false;
+        // Register ESC handler - returns unsubscribe function
+        this.#unsubEsc = keyboard.pushEscapeHandler(this, () => this.close());
+    }
+
+    close() {
+        this.hidden = true;
+        // Always unsubscribe when closing
+        this.#unsubEsc?.();
+        this.#unsubEsc = null;
+    }
+
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.#unsubEsc?.();  // Cleanup on removal
+    }
+}
+```
+
+**API:**
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `pushEscapeHandler(element, callback)` | `() => void` | Register handler, returns unsubscribe function |
+| `isTopmost(element)` | `boolean` | Check if element is top of stack |
+| `stackDepth` | `number` | Current stack depth (for debugging) |
+
+### Layer System (Z-Index)
+
+Centralized z-index constants to avoid magic numbers. Auto-injected as CSS custom properties.
+
+```javascript
+import { Z_INDEX } from 'microui/core/layers';
+
+// Use in JavaScript
+this.style.zIndex = Z_INDEX.modal;
+```
+
+```css
+/* Use in CSS (auto-injected as --z-* tokens) */
+.my-modal { z-index: var(--z-modal); }
+.my-tooltip { z-index: var(--z-tooltip); }
+```
+
+**Layer Hierarchy (lowest to highest):**
+| Token | Value | Use For |
+|-------|-------|---------|
+| `base` | 1 | Default content |
+| `sticky` | 100 | Sticky headers, FABs |
+| `dropdown` | 1000 | Dropdowns, menus, popovers |
+| `drawer` | 1100 | Navigation drawers |
+| `modal` | 1200 | Modal dialogs |
+| `toast` | 1300 | Toast notifications |
+| `tooltip` | 1400 | Tooltips |
+| `overlay` | 9999 | Full-screen overlays |
+| `devtools` | 999999 | Agent dev tools (always on top) |
+
+### Confirm Dialog (Agent-Friendly)
+```javascript
+import { muConfirm } from 'microui';
+
+// Simple confirm - returns Promise<boolean>
+const ok = await muConfirm('Delete this item?');
+if (ok) deleteItem();
+
+// With options
+const confirmed = await muConfirm('Are you sure?', {
+    title: 'Confirm Delete',
+    confirmText: 'Delete',
+    cancelText: 'Cancel',
+    variant: 'danger'  // 'primary' | 'danger' | 'warning'
+});
+```
+
+### Data Fetcher Component
+```html
+<!-- Declarative data fetching with automatic states -->
+<mu-fetch url="/api/users" id="users">
+    <template slot="loading"><mu-skeleton lines="3"></mu-skeleton></template>
+    <template slot="error"><mu-alert variant="error">${error}</mu-alert></template>
+    <template slot="empty"><p>No users found</p></template>
+</mu-fetch>
+
+<script type="module">
+const fetcher = document.getElementById('users');
+
+// Set render function for array data
+fetcher.renderItem = (user) => `
+    <mu-card variant="outlined">
+        <strong>${user.name}</strong> - ${user.email}
+    </mu-card>
+`;
+
+// Programmatic access
+fetcher.data;        // Current data
+fetcher.state;       // 'idle' | 'loading' | 'success' | 'error'
+fetcher.refetch();   // Re-fetch data
+
+// Events
+fetcher.addEventListener('mu-success', (e) => {
+    console.log('Data loaded:', e.detail.data);
+});
+</script>
+```
+
+### Form State Management
+```javascript
+import { createFormState } from 'microui';
+
+const form = document.querySelector('mu-form');
+const state = createFormState(form, {
+    email: { required: true, type: 'email' },
+    password: { required: true, minLength: 8 },
+    name: { maxLength: 50 }
+});
+
+// Check validation
+console.log(state.isValid);     // true if all fields valid
+console.log(state.isDirty);     // true if any field changed
+
+// Per-field state
+state.fields.email.value;       // Current value
+state.fields.email.error;       // Error message or null
+state.fields.email.touched;     // true after blur
+state.fields.email.dirty;       // true if changed from initial
+
+// Actions
+state.validate();               // Validate all, mark touched
+state.getValues();              // { email: '...', password: '...' }
+state.getErrors();              // { email: null, password: 'Min 8 chars' }
+state.reset();                  // Reset to initial values
+```
+
+
+### Toast Notifications
+```javascript
+import { showToast } from 'microui';
+
+showToast('Operation successful', {
+    variant: 'success',  // 'info' | 'success' | 'warning' | 'error'
+    duration: 3000       // ms, 0 for persistent
+});
+```
+
+### Theme Control
+```javascript
+import { Theme } from 'microui';
+
+Theme.init();           // Auto-detect or use saved
+Theme.set('dark');      // 'light' | 'dark' | 'system'
+Theme.toggle();         // Switch light/dark
+const current = Theme.get();
+```
+
+### View Transitions
+```javascript
+import { transition } from 'microui';
+
+await transition(() => {
+    document.querySelector('#content').innerHTML = newHTML;
+});
+```
+
+---
+
+## Cache Control (PWA)
+
+microUI includes a Service Worker with intelligent caching. Control via console:
+
+```javascript
+// Clear all caches and reload
+await microUICache.clear();
+
+// Get cache status
+await microUICache.status();
+// Returns: { version: "2.0.18", caches: { "microui-precache-2.0.18": 5 } }
+
+// Force check for updates
+await microUICache.update();
+
+// Prefetch URLs into cache
+await microUICache.prefetch(['/assets/image.webp', '/data.json']);
+```
+
+---
+
+## PWA Development for Agents
+
+> **Complete guide for AI agents building Progressive Web Apps with microUI.**
+
+### 1. Service Worker Setup
+
+Copy this template to your app root as `sw.js`:
+
+```javascript
+// sw.js - microUI Service Worker Template
+const VERSION = '1.0.0';  // Bump on each deploy
+const CACHE_PREFIX = 'myapp';
+const PRECACHE_NAME = `${CACHE_PREFIX}-precache-${VERSION}`;
+const RUNTIME_NAME = `${CACHE_PREFIX}-runtime-${VERSION}`;
+
+// Critical assets (precached on install)
+const PRECACHE_ASSETS = [
+    '/',
+    '/shell.html',
+    '/dist/microui.css',
+    '/dist/routes/shell.js',
+    '/dist/routes/home.js',
+    '/favicon.png'
+];
+
+// INSTALL: Precache critical assets
+self.addEventListener('install', (event) => {
+    event.waitUntil(
+        caches.open(PRECACHE_NAME)
+            .then(cache => cache.addAll(PRECACHE_ASSETS))
+            .then(() => self.skipWaiting())
+    );
+});
+
+// ACTIVATE: Cleanup old caches
+self.addEventListener('activate', (event) => {
+    event.waitUntil(
+        caches.keys().then(names => 
+            Promise.all(names
+                .filter(n => n.startsWith(CACHE_PREFIX) && n !== PRECACHE_NAME && n !== RUNTIME_NAME)
+                .map(n => caches.delete(n))
+            )
+        ).then(() => self.clients.claim())
+    );
+});
+
+// FETCH: Route requests
+self.addEventListener('fetch', (event) => {
+    const { request } = event;
+    if (request.method !== 'GET') return;
+    
+    const url = new URL(request.url);
+    if (url.origin !== self.location.origin) return;
+    
+    // HTML: Network-first (always fresh)
+    if (request.destination === 'document') {
+        event.respondWith(networkFirst(request));
+        return;
+    }
+    
+    // JS/CSS: Stale-while-revalidate (fast + fresh)
+    event.respondWith(staleWhileRevalidate(request));
+});
+
+async function networkFirst(request) {
+    try {
+        const response = await fetch(request);
+        const cache = await caches.open(PRECACHE_NAME);
+        cache.put(request, response.clone());
+        return response;
+    } catch {
+        return caches.match(request) || caches.match('/');
+    }
+}
+
+async function staleWhileRevalidate(request) {
+    const cache = await caches.open(RUNTIME_NAME);
+    const cached = await cache.match(request);
+    
+    const fetchPromise = fetch(request).then(response => {
+        if (response.ok) cache.put(request, response.clone());
+        return response;
+    }).catch(() => null);
+    
+    return cached || fetchPromise || caches.match('/');
+}
+```
+
+### 2. Register Service Worker
+
+Add to your `shell.html` (after app shell loads):
+
+```html
+<script>
+if ('serviceWorker' in navigator) {
+    navigator.serviceWorker.register('/sw.js')
+        .then(reg => console.log('SW registered:', reg.scope))
+        .catch(err => console.error('SW failed:', err));
+}
+</script>
+```
+
+### 3. Caching Strategy Guide
+
+| Asset Type | Strategy | Why |
+|------------|----------|-----|
+| **HTML** | Network-first | Always get fresh content |
+| **JS/CSS/Images** | Stale-while-revalidate | Fast load + background update |
+| **Fonts (woff2)** | Cache-first | Immutable, never changes |
+| **API calls** | Network-only | Data must be fresh |
+
+### 4. App Shell + Service Worker Integration
+
+```
+Initial Load Flow:
+─────────────────────────────────────────────────────────
+Browser → SW Installed? ─No→ Network → Cache critical assets
+                        │
+                       Yes
+                        │
+                        ▼
+              Cache → Return shell.js (instant)
+                        │
+                        ▼
+              Render App Shell (navbar, theme)
+                        │
+                        ▼
+              Lazy load route (home.js)
+                        │
+                        ▼
+              Background: Check for SW update
+```
+
+### 5. PWA Checklist for Agents
+
+```
+[ ] manifest.json created (name, icons, theme_color)
+[ ] sw.js in app root  
+[ ] PRECACHE_ASSETS includes shell.js + CSS
+[ ] VERSION bumped on each deploy
+[ ] Meta tags: theme-color, apple-mobile-web-app-capable
+[ ] Favicon + PWA icons (192x192, 512x512)
+[ ] HTTPS enabled (required for SW)
+[ ] Tested offline mode
+```
+
+### 6. Manifest Template
+
+```json
+{
+  "name": "My microUI App",
+  "short_name": "MyApp",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#FFFBFE",
+  "theme_color": "#6750A4",
+  "icons": [
+    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
+  ]
+}
+```
+
+### 7. Agent Workflow: Creating a PWA
+
+```bash
+# 1. Copy SW template
+cp demo/sw.js my-app/sw.js
+
+# 2. Update PRECACHE_ASSETS with your routes
+# 3. Create manifest.json
+# 4. Add meta tags to shell.html
+# 5. Register SW in shell.html
+# 6. Build and test
+bun run build
+```
+
+---
+
+## Accessibility Compliance (WCAG 2.1)
+
+All form components include proper ARIA attributes:
+
+| Component | Role | Key Attributes |
+|-----------|------|----------------|
+| `mu-checkbox` | `checkbox` | `aria-checked="true\|false\|mixed"`, `tabindex` |
+| `mu-switch` | `switch` | `aria-checked`, `aria-label` |
+| `mu-radio` | `radio` | `aria-checked`, `tabindex` |
+| `mu-radio-group` | `radiogroup` | - |
+| `mu-dropdown` | trigger + listbox | `aria-haspopup`, `aria-expanded` |
+| `mu-button` | `button` | `tabindex` |
+| `mu-input` | - | `for/id` label association, `aria-label` fallback |
+
+**Keyboard navigation:** All interactive components support `Tab`, `Space`, `Enter`.
+
+---
+
+## Best Practices for AI Agents
+
+### DO ✅
+1. **Use semantic components** - `<mu-input label="Email">` not `<input placeholder="Email">`
+2. **Use layout components** - `<mu-stack gap="md">` not manual CSS flexbox
+3. **Use declarative HTML** - Attributes over JavaScript for configuration
+4. **Always include labels** - For accessibility compliance
+5. **Use `variant` attributes** - For consistent MD3 styling
+6. **Use `mu-virtual-list`** - For lists with 100+ items
+7. **Use `mu-lazy`** - For below-the-fold heavy components
+
+### DON'T ❌
+1. **Don't use raw CSS for layout** - Use `mu-stack`, `mu-grid`, `mu-container`
+2. **Don't forget `variant`** - Buttons/cards need explicit variant
+3. **Don't manipulate Shadow DOM** - Components manage their own internals
+4. **Don't use inline styles for spacing** - Use `gap` attributes
+5. **Don't create custom form controls** - Use the provided accessible ones
+
+### CSS Fallback Pattern ⚡
+Layout components (`mu-stack`, `mu-grid`) have **CSS fallback styles** that apply BEFORE JavaScript loads. This prevents Flash of Unstyled Content (FOUC).
+
+```css
+/* CSS attribute selectors work immediately */
+mu-stack { display: flex; flex-direction: column; gap: 16px; }
+mu-stack[gap="lg"] { gap: 24px; }
+
+mu-grid { display: grid; gap: 16px; }
+mu-grid[cols="3"] { grid-template-columns: repeat(3, 1fr); }
+```
+
+**Why this matters:** HTML is parsed before JavaScript executes. Without CSS fallback, layout elements have no styling until custom element upgrade completes.
+
+### Common Mistakes to Avoid
+```html
+<!-- WRONG: Missing variant -->
+<mu-button>Click</mu-button>
+
+<!-- CORRECT: Explicit variant -->
+<mu-button variant="filled">Click</mu-button>
+
+<!-- WRONG: Raw div layout -->
+<div style="display: flex; gap: 16px;">
+
+<!-- CORRECT: Use mu-stack -->
+<mu-stack direction="row" gap="md">
+
+<!-- WRONG: Placeholder only (accessibility issue) -->
+<mu-input placeholder="Email"></mu-input>
+
+<!-- CORRECT: Use label -->
+<mu-input label="Email"></mu-input>
+```
+
+### XSS Prevention Patterns ⚠️
+
+microUI provides centralized utilities for safe HTML rendering. **Always use these patterns when handling dynamic content.**
+
+```javascript
+// Import centralized utility
+import { escapeHTML } from 'microui';
+
+// ✅ SAFE: Escape user-provided content
+const userName = '<script>alert("xss")</script>';
+element.innerHTML = `<span>${escapeHTML(userName)}</span>`;
+// Result: <span>&lt;script&gt;alert("xss")&lt;/script&gt;</span>
+
+// ✅ SAFE: Use textContent for plain text
+element.textContent = userName;
+
+// ✅ SAFE: Use createElement + property assignment
+const img = document.createElement('img');
+img.src = userProvidedUrl;
+img.alt = userProvidedAlt; // Property, not attribute string
+element.appendChild(img);
+
+// ❌ UNSAFE: Never use innerHTML with unescaped user data
+element.innerHTML = `<span>${userName}</span>`; // XSS RISK!
+```
+
+| Pattern | When to Use |
+|---------|-------------|
+| `escapeHTML(str)` | Dynamic values in template literals with `innerHTML` |
+| `textContent` | Displaying plain text (no HTML needed) |
+| `createElement` | Creating elements with user-provided attributes |
+| Static templates | When content is hardcoded (safe) |
+
+**Components using these patterns:** `mu-datatable`, `mu-api-table`, `mu-avatar`, `mu-fetch`
+
+---
+
+## File Structure
+```
+dist/
+├── microui.esm.js       # Full ESM bundle (230 KB)
+├── microui.min.js       # Full IIFE bundle (231 KB)
+├── microui.css          # Combined CSS (64 KB)
+├── microui.d.ts         # TypeScript definitions
+├── routes/              # v3.5 Route Bundles (SOTA)
+│   ├── shell.js         # App Shell (Navbar, Theme, Bus) - 5 KB
+│   ├── home.js          # Home route components
+│   ├── chunk-*.js       # Shared dependencies (deduplicated)
+│   ├── route-deps.json  # Auto-generated page dependencies
+│   └── page-components.json  # Debug: components per page
+└── AGENTS.md            # This file
+```
+
+---
+
+## Automatic Bundle Dependencies (v3.5)
+
+> **Build-time static analysis** detects which components each page uses.
+
+The build process scans HTML for `<mu-*>` tags and automatically:
+1. **Generates `route-deps.json`** - Maps pages to their required route bundles
+2. **Generates `page-components.json`** - Lists all mu-* components found per page
+
+### How It Works
+
+```bash
+bun run build:framework
+# Output:
+#   ✅ route-deps.json (19 pages with dependencies)
+#   ✅ page-components.json (20 pages scanned)
+```
+
+**Generated `dist/routes/route-deps.json`:**
+```json
+{
+  "enterprise": ["alerts", "buttons", "cards", "tabs"],
+  "buttons": ["cards", "layout", "tabs"],
+  "home": ["cards", "icons", "layout"]
+}
+```
+
+**Runtime:** The demo loads this JSON and auto-fetches required routes before rendering:
+```javascript
+// Automatic dependency loading
+const routeDeps = await fetch('dist/routes/route-deps.json').then(r => r.json());
+async function loadRouteWithDeps(name) {
+    await Promise.all((routeDeps[name] || []).map(dep => loadRoute(dep)));
+    await loadRoute(name);
+}
+```
+
+### Benefits
+
+| Feature | Before (Manual) | After (Automatic) |
+|---------|----------------|-------------------|
+| Maintenance | Edit `routeDependencies` map | Zero - auto-detected |
+| New pages | Must update build config | Just add HTML |
+| Debugging | Guess missing deps | Check `page-components.json` |
+
+### Build Utils API
+
+```javascript
+import { scanPageComponents, componentsToRoutes } from './scripts/build-utils.js';
+
+// Extract mu-* tags from HTML
+const components = scanPageComponents(htmlContent);
+// { "home": ["mu-card", "mu-icon", "mu-stack"], "buttons": [...] }
+
+// Map components to route bundles
+const routes = componentsToRoutes(["mu-tabs", "mu-button"]);
+// [\"buttons\", \"tabs\"]
+```
+
+### Auto-Versioning (v3.5.2)
+
+The build script automatically increments the version cache buster in `demo/shell.html`:
+
+```bash
+bun run build:framework
+# Output:
+#   🔄 Updating version cache buster...
+#   ✅ Version updated to 2.0.23
+```
+
+**How it works:**
+- Extracts current version from `?v=X.X.X` pattern
+- Increments patch version (e.g., `2.0.21` → `2.0.22`)
+- Replaces all occurrences in demo/shell.html
+
+**Benefits:**
+- No more stale cache issues after component updates
+- Zero manual version management needed
+- Browser automatically downloads updated bundles
+
+
+---
+
+## App Shell Architecture (v3.2)
+
+For SOTA performance, use the **App Shell** pattern. Load the critical shell first, then lazily load routes.
+
+```html
+<head>
+    <link rel="stylesheet" href="dist/microui.css">
+</head>
+<body>
+    <!-- Global Shell Components -->
+    <mu-navbar>...</mu-navbar>
+    <mu-toast-container></mu-toast-container>
+
+    <!-- App Router -->
+    <mu-router base="/app-dist/pages" default="home"></mu-router>
+
+    <!-- Loader Script -->
+    <script type="module">
+        // 1. Load Shell (Navbar, Theme, Signals, Toasts)
+        await import('./dist/routes/shell.js');
+        
+        // 2. Initialize Router (which loads pages + their bundles)
+        const router = document.querySelector('mu-router');
+        
+        // Helper to manually load a route bundle if needed
+        window.loadRoute = async (name) => {
+            await import(`./dist/routes/${name}.js`);
+        };
+    </script>
+</body>
+```
+
+| Bundle | Content | Size (gzip) |
+|--------|---------|-------------|
+| `shell.js` | Navbar, Theme, CrossBus, Toasts | ~5 KB |
+| `home.js` | Landing page components | ~2 KB |
+| `forms.js` | (Example) Input, Button, Checkbox | ~7 KB |
+
+**Why this is SOTA:** 
+- The user only downloads `shell.js` (small) to see the UI.
+- Page bundles (`home.js`) are only downloaded when navigating to that page.
+- Common code (CrossBus, BaseClass) is shared via `chunk-*.js` files automatically.
+
+---
+
+## Performance Metrics
+- **Bundle size:** 230 KB full / 8 KB route-based (gzipped: 75 KB / 3 KB)
+- **Lighthouse:** 100% Performance, 100% Accessibility, 100% SEO, 100% Best Practices
+- **EventBus:** 111M ops/sec (CrossBus emitSync)
+- **Virtual List:** Handles 10K+ items at 60fps
+- **First paint:** <100ms (precached assets)
+
+---
+
+## Performance Patterns (SOTA)
+
+> **Critical patterns for 100% Lighthouse scores and excellent UX.**
+
+### 1. Skeleton Loading (Perceived Performance)
+
+Use `mu-skeleton` to show content placeholders while loading:
+
+```html
+<!-- Before data loads -->
+<mu-card>
+    <mu-skeleton type="text" width="60%"></mu-skeleton>
+    <mu-skeleton type="text" lines="3"></mu-skeleton>
+    <mu-skeleton type="button"></mu-skeleton>
+</mu-card>
+
+<!-- Replace with real content when ready -->
+<mu-card>
+    <h3>User Profile</h3>
+    <p>Actual content...</p>
+    <mu-button>Edit</mu-button>
+</mu-card>
+```
+
+| Attribute | Values | Default |
+|-----------|--------|---------|
+| `type` | `text`, `avatar`, `button`, `image` | `text` |
+| `width` | CSS width | `100%` |
+| `lines` | Number of text lines | `1` |
+| `animated` | boolean | `true` |
+
+### 2. Lazy Loading (Below-the-fold)
+
+Use `mu-lazy` to defer loading of non-critical content:
+
+```html
+<!-- Content loads only when scrolled into view -->
+<mu-lazy threshold="200px">
+    <mu-card>
+        <img src="heavy-image.webp">
+        <p>This loads lazily</p>
+    </mu-card>
+</mu-lazy>
+
+<!-- With loading placeholder -->
+<mu-lazy placeholder="<mu-skeleton type='image'></mu-skeleton>">
+    <img src="hero.webp" alt="Hero">
+</mu-lazy>
+```
+
+| Attribute | Description | Default |
+|-----------|-------------|---------|
+| `threshold` | Distance from viewport to trigger load | `100px` |
+| `placeholder` | HTML to show while loading | (empty) |
+
+### 3. Resource Hints (Preload Critical Assets)
+
+Add to `<head>` for faster loading:
+
+```html
+<head>
+    <!-- Preconnect to external origins (fonts, CDN) -->
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    
+    <!-- Preload critical assets (above-the-fold) -->
+    <link rel="preload" href="/dist/microui.css" as="style">
+    <link rel="preload" href="/dist/routes/shell.js" as="script" crossorigin>
+    <link rel="preload" href="/assets/logo.webp" as="image" type="image/webp">
+    
+    <!-- Prefetch likely next pages (after current page loads) -->
+    <link rel="prefetch" href="/dist/routes/home.js">
+</head>
+```
+
+| Hint | When to Use | Priority |
+|------|-------------|----------|
+| `preconnect` | External domains you'll fetch from | 🔴 High |
+| `preload` | Critical above-the-fold assets | 🔴 High |
+| `prefetch` | Next likely navigation | 🟢 Low |
+| `dns-prefetch` | External domains (fallback) | 🟢 Low |
+
+### 4. Core Web Vitals Optimization
+
+| Metric | Target | How to Achieve |
+|--------|--------|----------------|
+| **LCP** (Largest Contentful Paint) | < 2.5s | Preload hero image, inline critical CSS |
+| **FID** (First Input Delay) | < 100ms | Code split, defer non-critical JS |
+| **CLS** (Cumulative Layout Shift) | < 0.1 | Set dimensions on images, reserve space |
+
+```html
+<!-- LCP: Preload hero image with fetchpriority -->
+<link rel="preload" as="image" href="/hero.webp" fetchpriority="high">
+
+<!-- CLS: Always set dimensions -->
+<img src="photo.webp" width="800" height="600" alt="...">
+
+<!-- CLS: Reserve space for dynamic content -->
+<div style="min-height: 300px;">
+    <mu-lazy><mu-card>...</mu-card></mu-lazy>
+</div>
+```
+
+### 5. View Transitions (Smooth Navigation)
+
+Use the View Transitions API for cinematic page changes:
+
+```javascript
+import { transition, transitionNamed } from 'microui';
+
+// Basic transition
+await transition(() => {
+    document.getElementById('content').innerHTML = newHTML;
+});
+
+// Named transition with custom animation
+await transitionNamed(() => {
+    router.navigate('/users');
+}, { name: 'page-slide' });
+```
+
+```css
+/* Custom transition animation */
+::view-transition-old(page-slide) {
+    animation: slide-out 0.3s ease-out;
+}
+::view-transition-new(page-slide) {
+    animation: slide-in 0.3s ease-out;
+}
+```
+
+### 6. Virtual List (Large Datasets)
+
+For lists with 100+ items, use `mu-virtual-list`:
+
+```javascript
+const list = document.querySelector('mu-virtual-list');
+list.items = largeArray;        // 10K+ items OK
+list.itemHeight = 48;           // Fixed height for calculation
+list.renderItem = (item, index) => `
+    <div class="list-item">
+        <span>${item.name}</span>
+        <span>${item.email}</span>
+    </div>
+`;
+```
+
+### 7. Speculative Route Preloading
+
+Preload routes on hover for instant navigation:
+
+```javascript
+// Add to navigation links
+document.querySelectorAll('a[data-route]').forEach(link => {
+    link.addEventListener('mouseenter', () => {
+        const route = link.dataset.route;
+        // Prefetch route bundle
+        import(`/dist/routes/${route}.js`);
+    });
+});
+```
+
+---
+
+## Error Handling Patterns
+
+### 1. Runtime Error Collection
+
+microUI logs all component errors to `window.__MICROUI_ERRORS__`:
+
+```javascript
+// In E2E tests or debug console
+const errors = window.__MICROUI_ERRORS__ || [];
+errors.forEach(err => {
+    console.error(`[${err.component}] ${err.message}`, err.details);
+});
+```
+
+### 2. Async Error Handling
+
+Wrap async operations with proper error handling:
+
+```javascript
+async function loadUserData() {
+    try {
+        const response = await fetch('/api/users');
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        return await response.json();
+    } catch (error) {
+        // Show user-friendly error
+        showToast('Failed to load data. Please retry.', { variant: 'error' });
+        // Log for debugging
+        console.error('loadUserData failed:', error);
+        return null;
+    }
+}
+```
+
+### 3. Error Boundary Pattern
+
+Create a wrapper to catch render errors:
+
+```javascript
+function safeRender(container, renderFn) {
+    try {
+        container.innerHTML = renderFn();
+    } catch (error) {
+        container.innerHTML = `
+            <mu-alert variant="error">
+                Something went wrong. Please refresh the page.
+            </mu-alert>
+        `;
+        console.error('Render error:', error);
+    }
+}
+
+// Usage
+safeRender(document.getElementById('content'), () => {
+    return `<mu-card>${userData.name}</mu-card>`;
+});
+```
+
+### 4. Network Error Handling
+
+```javascript
+// Fetch with timeout and retry
+async function fetchWithRetry(url, options = {}, retries = 3) {
+    for (let i = 0; i < retries; i++) {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            
+            const response = await fetch(url, {
+                ...options,
+                signal: controller.signal
+            });
+            
+            clearTimeout(timeout);
+            if (response.ok) return response;
+        } catch (error) {
+            if (i === retries - 1) throw error;
+            await new Promise(r => setTimeout(r, 1000 * (i + 1)));
+        }
+    }
+}
+```
+
+### 5. Agent Debugging Tips
+
+```javascript
+// Enable verbose logging
+window.__MICROUI_DEBUG__ = true;
+
+// Check component registration
+customElements.get('mu-button'); // Returns class or undefined
+
+// Inspect component state
+const btn = document.querySelector('mu-button');
+console.log(btn.getAttribute('variant'), btn.disabled);
+
+// Force component re-render
+btn.render?.();
+```
+
+---
+
+## Page-Based App Development (v3.2)
+
+> **For AI Agents building apps with microUI.** This is the recommended architecture.
+
+### Creating a New Page
+
+Create a single file in `app/pages/`:
+
+```html
+<!-- app/pages/users.html -->
+<mu-page route="users" title="Users">
+  <script type="x-dependencies">
+    mu-table
+    mu-button
+    mu-stack
+    mu-tabs
+  </script>
+  
+  <template>
+    <h1 class="page-title">Users</h1>
+    <mu-table id="users-table"></mu-table>
+    <mu-button onclick="addUser()">Add User</mu-button>
+  </template>
+</mu-page>
+```
+
+### Build & Run
+
+```bash
+# Build everything (framework + app)
+bun run build
+
+# Or separately:
+bun run build:framework   # → dist/
+bun run build:app         # → app-dist/
+
+# Serve
+npx serve app-dist
+```
+
+### File Structure
+
+```
+microUI/
+├── src/                    # Framework source
+│   └── components/         # 49 components
+│
+├── dist/                   # Framework build
+│   ├── microui.esm.js      # Full bundle
+│   ├── microui.css         # CSS
+│   └── components/         # Per-component builds
+│
+├── app/                    # App source
+│   ├── pages/              # One file per page
+│   │   ├── home.html
+│   │   ├── users.html
+│   │   └── settings.html
+│   └── shell.html          # App shell
+│
+└── app-dist/               # App build (auto-generated)
+    ├── routes/             # Auto-bundled from x-dependencies
+    ├── pages/              # Copied HTML pages
+    └── pages.json          # Manifest
+```
+
+### How It Works
+
+1. **Agent creates** `app/pages/mypage.html` with `<mu-page>` component
+2. **Build extracts** dependencies from `<script type="x-dependencies">`
+3. **Build generates** route bundle in `app-dist/routes/mypage.js`
+4. **Router lazy-loads** page HTML and route bundle on navigation
+
+### mu-router
+
+```html
+<mu-router base="/app-dist/pages" default="home"></mu-router>
+```
+
+| Attribute | Description | Default |
+|-----------|-------------|---------|
+| `base` | Path to pages directory | `/app/pages` |
+| `default` | Default route when no hash | `home` |
+
+**Events:** `mu-route-change`, `mu-page-loaded`, `mu-page-error`
+
+**Methods:** `.navigate(route)`
+
+### mu-page
+
+```html
+<mu-page route="mypage" title="My Page">
+  <script type="x-dependencies">mu-button, mu-card</script>
+  <template><!-- content --></template>
+</mu-page>
+```
+
+| Attribute | Description |
+|-----------|-------------|
+| `route` | Route name (used in URL hash) |
+| `title` | Page title (set on navigation) |
+
+---
+
+## Agent Workflow: Adding a Page
+
+```bash
+# 1. Create page file
+cat > app/pages/dashboard.html << 'EOF'
+<mu-page route="dashboard" title="Dashboard">
+  <script type="x-dependencies">
+    mu-card
+    mu-stack
+    mu-grid
+  </script>
+  <template>
+    <h1 class="page-title">Dashboard</h1>
+    <mu-grid cols="3" gap="md">
+      <mu-card variant="elevated">Widget 1</mu-card>
+      <mu-card variant="elevated">Widget 2</mu-card>
+      <mu-card variant="elevated">Widget 3</mu-card>
+    </mu-grid>
+  </template>
+</mu-page>
+EOF
+
+# 2. Build
+bun run build:app
+
+# 3. Navigate to: http://localhost:5001/app-dist/#dashboard
+```
+
+---
+
+## Agent Workflow: Adding a Component
+
+```bash
+# 1. Create component file
+cat > src/components/mu-counter.js << 'EOF'
+import { MuElement, define } from '../core/MuElement.js';
+
+export class MuCounter extends MuElement {
+  static baseClass = 'mu-counter';
+  static observedAttributes = ['value'];
+  
+  render() {
+    const value = parseInt(this.attr('value', '0'));
+    this.innerHTML = `
+      <button class="mu-counter__dec">-</button>
+      <span class="mu-counter__value">${value}</span>
+      <button class="mu-counter__inc">+</button>
+    `;
+    this.#setupEvents();
+  }
+  
+  #setupEvents() {
+    this.querySelector('.mu-counter__dec')
+      .addEventListener('click', () => this.#change(-1));
+    this.querySelector('.mu-counter__inc')
+      .addEventListener('click', () => this.#change(1));
+  }
+  
+  #change(delta) {
+    const current = parseInt(this.attr('value', '0'));
+    this.setAttribute('value', current + delta);
+    this.emit('mu-change', { value: current + delta });
+  }
+}
+
+define('mu-counter', MuCounter);
+EOF
+
+# 2. Add to index.js exports (if needed)
+# 3. Build framework
+bun run build:framework
+```
+
+---
+
+## State Management for Complex Apps
+
+> **For apps with shared state across components and pages.**
+
+### Global Store Pattern
+```javascript
+// store/index.js - Centralized reactive state
+import { signal, computed, effect } from 'microui';
+
+export const store = {
+    // Core state
+    user: signal(null, 'user'),
+    items: signal([], 'items'),
+    loading: signal(false, 'loading'),
+    
+    // Computed values (auto-update when dependencies change)
+    itemCount: computed(() => store.items().length),
+    isAuthenticated: computed(() => store.user() !== null),
+    
+    // Actions
+    async fetchItems() {
+        store.loading.set(true);
+        try {
+            const data = await fetch('/api/items').then(r => r.json());
+            store.items.set(data);
+        } finally {
+            store.loading.set(false);
+        }
+    },
+    
+    login(userData) {
+        store.user.set(userData);
+    },
+    
+    logout() {
+        store.user.set(null);
+    }
+};
+
+// Auto-persist to localStorage
+effect(() => {
+    const user = store.user();
+    if (user) localStorage.setItem('user', JSON.stringify(user));
+    else localStorage.removeItem('user');
+});
+
+// Restore on load
+const savedUser = localStorage.getItem('user');
+if (savedUser) store.user.set(JSON.parse(savedUser));
+```
+
+### Binding State to Components
+```javascript
+import { store } from './store/index.js';
+import { effect } from 'microui';
+
+// Auto-update UI when state changes
+effect(() => {
+    const user = store.user();
+    document.querySelector('#user-name').textContent = user?.name || 'Guest';
+    document.querySelector('#login-btn').hidden = !!user;
+    document.querySelector('#logout-btn').hidden = !user;
+});
+
+// Show loading state
+effect(() => {
+    document.querySelector('#spinner').hidden = !store.loading();
+});
+```
+
+### State in Custom Components
+```javascript
+export class MuUserCard extends MuElement {
+    connectedCallback() {
+        super.connectedCallback();
+        // Re-render when user changes
+        this.#unsubscribe = effect(() => {
+            this.user = store.user();
+            this.render();
+        });
+    }
+    
+    disconnectedCallback() {
+        this.#unsubscribe?.();
+    }
+}
+```
+
+---
+
+## Data-Driven Components
+
+> **Components that render dynamic data from arrays/objects.**
+
+### mu-repeat (Declarative Lists)
+```html
+<mu-repeat id="user-list"></mu-repeat>
+
+<script type="module">
+const list = document.getElementById('user-list');
+
+// Set data and render template
+list.items = await fetch('/api/users').then(r => r.json());
+list.renderItem = (user, index) => `
+    <mu-card variant="outlined">
+        <mu-stack direction="row" gap="md" align="center">
+            <mu-avatar initials="${user.name[0]}" size="md"></mu-avatar>
+            <mu-stack gap="xs">
+                <strong>${user.name}</strong>
+                <small>${user.email}</small>
+            </mu-stack>
+            <mu-button variant="text" data-id="${user.id}">Edit</mu-button>
+        </mu-stack>
+    </mu-card>
+`;
+
+// Listen for item events
+list.addEventListener('click', (e) => {
+    const btn = e.target.closest('[data-id]');
+    if (btn) console.log('Edit user:', btn.dataset.id);
+});
+</script>
+```
+
+### mu-table (Data Tables with Sorting)
+```html
+<mu-table id="data-table"></mu-table>
+
+<script type="module">
+const table = document.getElementById('data-table');
+
+// Configure columns
+table.columns = [
+    { key: 'name', label: 'Name', sortable: true },
+    { key: 'email', label: 'Email', sortable: true },
+    { key: 'role', label: 'Role', sortable: true },
+    { key: 'actions', label: '', render: (row) => `
+        <mu-button variant="text" size="sm" data-action="edit" data-id="${row.id}">
+            <mu-icon name="edit"></mu-icon>
+        </mu-button>
+    `}
+];
+
+// Set data
+table.data = await fetch('/api/users').then(r => r.json());
+
+// Handle actions
+table.addEventListener('click', (e) => {
+    const btn = e.target.closest('[data-action]');
+    if (btn?.dataset.action === 'edit') {
+        console.log('Edit:', btn.dataset.id);
+    }
+});
+</script>
+```
+
+### mu-virtual-list (10K+ Items)
+```javascript
+const list = document.querySelector('mu-virtual-list');
+list.items = hugeArray;      // 10,000+ items OK
+list.itemHeight = 56;        // Fixed height for virtualization
+list.renderItem = (item) => `
+    <div class="list-row">${item.name}</div>
+`;
+```
+
+---
+
+## Error Handling Patterns
+
+> **Production-ready error handling for complex apps.**
+
+### Runtime Error Detection
+```javascript
+// Check for microUI component errors
+const errors = window.__MICROUI_ERRORS__ || [];
+if (errors.length) {
+    console.error('microUI component errors:', errors);
+    // Report to monitoring service
+    fetch('/api/errors', {
+        method: 'POST',
+        body: JSON.stringify({ errors, url: location.href })
+    });
+}
+```
+
+### Global Error Boundary
+```javascript
+// Catch all unhandled errors
+window.addEventListener('error', (event) => {
+    console.error('Uncaught error:', event.error);
+    showToast('Something went wrong', { variant: 'error' });
+    
+    // Prevent default browser error UI
+    event.preventDefault();
+});
+
+// Catch unhandled promise rejections
+window.addEventListener('unhandledrejection', (event) => {
+    console.error('Unhandled rejection:', event.reason);
+    showToast('Network or async error', { variant: 'warning' });
+});
+```
+
+### API Error Handling
+```javascript
+// services/api.js
+export async function fetchAPI(endpoint, options = {}) {
+    try {
+        const res = await fetch(`/api${endpoint}`, {
+            headers: { 'Content-Type': 'application/json' },
+            ...options
+        });
+        
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({}));
+            throw new Error(error.message || `HTTP ${res.status}`);
+        }
+        
+        return res.json();
+    } catch (err) {
+        showToast(err.message || 'Network error', { variant: 'error' });
+        throw err;
+    }
+}
+
+// Usage
+import { fetchAPI } from './services/api.js';
+const users = await fetchAPI('/users');
+```
+
+---
+
+## Architecture for Large Apps (10+ Pages)
+
+> **Recommended structure for complex multi-page applications.**
+
+### Directory Structure
+```
+my-app/
+├── shell.html           # App shell (minimal HTML)
+├── sw.js                # Service Worker
+├── manifest.json        # PWA manifest
+├── store/
+│   └── index.js         # Global reactive state (signals)
+├── pages/
+│   ├── home.js          # Lazy-loaded route modules
+│   ├── users.js
+│   ├── settings.js
+│   └── not-found.js
+├── components/
+│   ├── user-card.js     # Reusable custom components
+│   ├── data-table.js
+│   └── nav-menu.js
+├── services/
+│   └── api.js           # API client with error handling
+└── assets/
+    ├── logo.webp
+    └── icons/
+```
+
+### Route-Based Code Splitting
+```html
+<!-- shell.html - App Shell -->
+<body>
+    <mu-navbar>...</mu-navbar>
+    <main id="app"></main>
+    <mu-toast-container></mu-toast-container>
+    
+    <script type="module">
+        // Route configuration
+        const routes = {
+            home: () => import('./pages/home.js'),
+            users: () => import('./pages/users.js'),
+            settings: () => import('./pages/settings.js'),
+            default: () => import('./pages/not-found.js')
+        };
+        
+        async function navigate() {
+            const hash = location.hash.slice(1) || 'home';
+            const loader = routes[hash] || routes.default;
+            
+            try {
+                const module = await loader();
+                document.getElementById('app').innerHTML = '';
+                await module.render(document.getElementById('app'));
+            } catch (err) {
+                console.error('Route error:', err);
+                document.getElementById('app').innerHTML = `
+                    <mu-alert variant="error">Failed to load page</mu-alert>
+                `;
+            }
+        }
+        
+        window.addEventListener('hashchange', navigate);
+        navigate(); // Initial load
+    </script>
+</body>
+```
+
+### Page Module Pattern
+```javascript
+// pages/users.js
+import { store } from '../store/index.js';
+import { fetchAPI } from '../services/api.js';
+
+export async function render(container) {
+    // Show skeleton while loading
+    container.innerHTML = `
+        <mu-doc-page title="Users">
+            <mu-skeleton type="text" lines="5"></mu-skeleton>
+        </mu-doc-page>
+    `;
+    
+    // Fetch data
+    const users = await fetchAPI('/users');
+    store.users.set(users);
+    
+    // Render content
+    container.innerHTML = `
+        <mu-doc-page title="Users">
+            <mu-stack gap="md">
+                <mu-stack direction="row" justify="space-between">
+                    <h2>All Users (${users.length})</h2>
+                    <mu-button variant="filled" id="add-user">Add User</mu-button>
+                </mu-stack>
+                <mu-repeat id="user-list"></mu-repeat>
+            </mu-stack>
+        </mu-doc-page>
+    `;
+    
+    // Setup repeat
+    const list = container.querySelector('#user-list');
+    list.items = users;
+    list.renderItem = (user) => `
+        <mu-card variant="outlined">
+            <strong>${user.name}</strong> - ${user.email}
+        </mu-card>
+    `;
+}
+```
+
+### Performance Checklist for Large Apps
+```
+[ ] Use route-based code splitting (only load needed code)
+[ ] Preload critical routes with <link rel="prefetch">
+[ ] Use mu-virtual-list for lists with 100+ items
+[ ] Use mu-lazy for below-the-fold content
+[ ] Implement skeleton loading for perceived performance
+[ ] Cache API responses with Service Worker
+[ ] Use signals for state (not prop drilling)
+[ ] Minimize bundle size with tree-shaking
+```
+
+---
+
+## 🚀 Development Server
+
+> **CRITICAL**: Use the project's official `server.js` for development and Lighthouse testing.
+
+### Quick Start
+```bash
+# Start the Lighthouse-optimized dev server
+bun server.js
+
+# Server runs on port 5001 (auto-increments if busy)
+# 🚀 http://localhost:5001/
+```
+
+### URL Routing
+
+| URL | Maps To | Description |
+|-----|---------|-------------|
+| `/` | `/demo/shell.html` | Main showcase (App Shell pattern with dynamic route loading) |
+| `/shell.html` | `/demo/shell.html` | App Shell pattern (dynamic route loading) |
+| `/content/*` | `/demo/content/*` | Content fragments for shell.html |
+| `/sw.js` | `/demo/sw.js` | Service Worker |
+| `/manifest.json` | `/demo/manifest.json` | PWA manifest |
+| `/favicon.png` | `/demo/favicon.png` | Favicon |
+| `/-/health` | - | Health check endpoint |
+| `/-/clear-cache` | - | Clear browser cache |
+
+### Server Features
+
+The `server.js` is optimized for **Lighthouse 100** scores:
+
+1. **Cache-Control Headers**
+   - `1 year` for versioned assets (`/dist/`, `/assets/`)
+   - `must-revalidate` for HTML (bf-cache friendly)
+   - `1 hour` for other resources
+
+2. **Gzip Compression**
+   - Auto-compresses `.html`, `.css`, `.js`, `.json`, `.svg`
+
+3. **Link Preload Headers**
+   - Sends HTTP `Link` headers for critical resources
+
+4. **Security**
+   - Directory traversal protection
+   - `X-Content-Type-Options: nosniff`
+
+### Running Lighthouse Audits
+```bash
+# Run the automated Lighthouse audit script
+source ~/.nvm/nvm.sh && nvm use 22
+node lighthouse-audit.mjs
+
+# Output shows scores for shell.html
+# Results saved to /tmp/lighthouse-shell.json
+```
+
+### Current Lighthouse Scores (v0.1.0)
+
+| Page | Performance | Accessibility | Best Practices | SEO |
+|------|-------------|---------------|----------------|-----|
+| `shell.html` | 98 | 100 | 100 | 100 |
+
+### CLS Prevention Pattern
+
+To prevent Cumulative Layout Shift from custom elements, pre-define dimensions:
+
+```css
+/* In <head> style block - REQUIRED for Lighthouse Performance */
+mu-bottom-nav:not(:defined) {
+    display: block;
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    height: var(--mu-bottom-nav-height, 80px);
+    z-index: 1000;
+}
+```
+
+### Srcset for Retina Images
+
+Always use srcset for hero images to pass "Serves images with low resolution":
+
+```html
+<picture>
+    <source srcset="logo-400.webp 1x, logo-800.webp 2x" type="image/webp">
+    <img src="logo-400.jpg" width="400" height="223" alt="Description">
+</picture>
+
+<!-- Preload with imagesrcset -->
+<link rel="preload" as="image" type="image/webp" 
+      href="logo-400.webp" 
+      imagesrcset="logo-400.webp 1x, logo-800.webp 2x" 
+      fetchpriority="high">
+```
+
+### Skip Link Anchors (Accessibility)
+
+All hash links must have focusable targets:
+
+```html
+<!-- Before each page section, add anchor with tabindex -->
+<div id="installation" tabindex="-1" aria-hidden="true"></div>
+<div id="page-installation" class="page">
+    <!-- Page content -->
+</div>
+```
+
+---
+
+*Last updated: v0.1.0 - 2026-02-02*