snice 4.14.0 → 4.16.0

package/dist/symbols.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.13.0
+ * snice v4.15.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.13.0
+ * snice v4.15.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/tooltip-observer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Initialize attribute-based tooltips.
+ * Any element with a `tooltip` attribute will show a tooltip on interaction.
+ * Configure via CSS custom properties (--tooltip-position, --tooltip-delay, etc.).
+ * Idempotent — safe to call multiple times.
+ */
+export declare function useTooltips(): void;
+/**
+ * Disconnect the tooltip observer and remove all portals.
+ */
+export declare function cleanupTooltips(): void;

package/dist/transitions.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.13.0
+ * snice v4.15.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.13.0
+ * snice v4.15.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/docs/ai/DEVELOPMENT.md

@@ -89,7 +89,7 @@ All CDN builds use the shared runtime (external `snice` imports). Load `snice-ru
 - IIFE: `.js` + `.min.js`
 - Sourcemaps + README
 
-**Size:** Runtime ~18KB gzip, components ~1-93KB each
+**Size:** Runtime ~20KB gzip, components ~1-93KB each
 
 **Features:**
 - Shared runtime (external snice imports)

package/docs/ai/api.md

@@ -3,7 +3,7 @@
 ## Class Decorators
 
 ```typescript
-@element('tag-name') // Define custom element
+@element('tag-name', options?: { formAssociated?: boolean }) // Define custom element
 @page({ tag, routes, guards?, placard? }) // Define routable page
 @controller('name') // Define behavior module
 @layout('name') // Define page wrapper
@@ -30,6 +30,9 @@
 @styles()
 // Returns: CSSResult from css`...`
 // Scoped to shadow DOM
+// Called once during initialization — NOT reactive
+// Only one per element (last wins if multiple declared)
+// For dynamic styles, use CSS custom properties set in template
 ```
 
 ## Properties
@@ -46,7 +49,7 @@
 ## Lifecycle
 
 ```typescript
-@ready() // After initial render
+@ready() // After styles + event handlers set up (render is async microtask, may not be complete)
 @dispose() // On disconnectedCallback
 @moved() // On adoptedCallback
 @adopted() // On adoptedCallback
@@ -55,8 +58,9 @@
 ## DOM Queries
 
 ```typescript
-@query(selector: string) // Single element
-@queryAll(selector: string) // NodeListOf<Element>
+@query(selector: string, options?: { light?: boolean }) // Single element
+@queryAll(selector: string, options?: { light?: boolean }) // NodeListOf<Element>
+// Default: queries shadow DOM. Use { light: true } in controllers on native elements
 ```
 
 ## Events
@@ -80,8 +84,10 @@ html`
 // Keyboard: 'keydown:Enter', 'keydown.escape', 'keydown:ctrl+s', 'keydown:~Space'
 // Supports both ':' and '.' notation
 
-@dispatch(eventName: string)
+@dispatch(eventName: string, options?: { debounce?, throttle?, dispatchOnUndefined? })
 // Fires CustomEvent after method, detail = return value
+// Supports async methods (dispatches after promise resolves)
+// dispatchOnUndefined: false (default) — skips dispatch if method returns undefined
 ```
 
 ## Communication
@@ -252,7 +258,7 @@ attr="${val}" // Attribute
 interface TemplateResult { readonly _$litType$: number; }
 interface CSSResult { cssText: string; }
 interface OnOptions { debounce?, throttle?, preventDefault?, stopPropagation?, once?, capture?, passive?, target? }
-interface RenderOptions { debounce?, throttle?, once?, sync? }
+interface RenderOptions { debounce?, throttle?, once?, sync?, differential? }
 interface Layout { update(context, placards, route, params) }
 interface Placard { name, title, icon?, description?, order?, show?, visibleOn?, parent?, group?, searchTerms?, hotkeys?, breadcrumbs?, tooltip? }
 // Guards: synchronous only, receive context AND params
@@ -265,7 +271,7 @@ type Guard<T> = (context: T, params: RouteParams) => boolean
 
 ```typescript
 import {
-  element, page, controller, layout,
+  element, controller, layout,  // NOTE: `page` comes from Router(), not from 'snice'
   property, watch, context,
   render, styles, html, css,
   query, queryAll,
@@ -275,8 +281,6 @@ import {
   ready, dispose, moved, adopted,
   Router,
   debounce, throttle, once, memoize,
-  useNativeElementControllers,   // Enable controller= on native HTML elements
-  cleanupNativeElementControllers,
-  attachController, detachController, getController
+  useNativeElementControllers    // Enable controller= on native HTML elements
 } from 'snice';
 ```

package/docs/ai/architecture.md

@@ -5,8 +5,12 @@
 **Separation of concerns:**
 - **Cross-cutting:** Router + global context
 - **Pages:** Orchestrate elements, handle URLs
-- **Elements:** Pure presentation, no business logic
-- **Controllers:** Behavior, data fetching, swappable
+- **Elements:** Generic visual building blocks — no fetch(), no API calls, no business logic
+- **Controllers:** Specific behavior (data, APIs, business rules) — swappable per element
+
+**Generic vs Specific:** Elements say *what* they need, controllers decide *how*.
+Swap controllers to change behavior without touching the component.
+Mock controller for tests, real API controller in production — same element.
 
 **Data flow:**
 - Down: Properties
@@ -125,9 +129,18 @@ onChange() { return { value: this.value }; }
 
 **Element ↔ Controller:** Request/Response
 ```typescript
-// Element requests, controller responds
-@request('channel') method!: (data) => Promise<result>
-@respond('channel') handler(req, respond) { respond(data); }
+// Element requests (async generator: yield sends, await receives)
+@request('fetch-data')
+async *fetchData(): any {
+  return await (yield { id: this.dataId });  // single yield per call
+}
+
+// Controller responds (receives payload, returns result directly)
+@respond('fetch-data')
+async handleFetch(payload: { id: string }) {
+  return await fetch(`/api/${payload.id}`).then(r => r.json());
+}
+// Wiring: <my-element controller="my-controller"></my-element>
 ```
 
 **Global State:** Context

package/docs/ai/components/app-tiles.md

@@ -9,7 +9,7 @@ App launcher grid like Google's app drawer or a phone home screen.
 tiles: AppTile[] = [];           // Programmatic tile data
 columns: number = 4;             // Grid columns
 size: 'sm' | 'md' | 'lg' = 'md'; // Tile size
-variant: 'grid' | 'list' = 'grid'; // Layout variant
+variant: 'grid' | 'list' | 'compact' = 'grid'; // Layout variant
 
 // AppTile interface
 interface AppTile {

package/docs/ai/components/book.md

@@ -1,12 +1,11 @@
 # snice-book
 
-Page-flipping book component with spread/single modes, cover page, touch/keyboard navigation, and animated page turns.
+Page-flipping book component with cover page, keyboard navigation, and animated page turns.
 
 ## Properties
 
 ```ts
 currentPage: number = 0          // attr: current-page
-mode: BookMode = 'spread'        // attr: mode — 'single' | 'spread'
 coverImage: string = ''          // attr: cover-image — URL for cover page image
 title: string = ''               // Book title shown on cover
 author: string = ''              // Author name shown on cover
@@ -25,9 +24,9 @@ readonly totalPages: number      // Getter, count of slotted page elements
 
 ## Methods
 
-- `goToPage(page: number): void` — Navigate to specific page (auto-aligns to spread in spread mode)
-- `nextPage(): void` — Advance by 1 (single) or 2 (spread) pages
-- `prevPage(): void` — Go back by 1 or 2 pages
+- `goToPage(page: number): void` — Navigate to specific page
+- `nextPage(): void` — Advance by 1 page
+- `prevPage(): void` — Go back by 1 page
 - `firstPage(): void` — Jump to page 0
 - `lastPage(): void` — Jump to last page
 
@@ -63,7 +62,7 @@ readonly totalPages: number      // Getter, count of slotted page elements
 ## Usage
 
 ```html
-<snice-book title="My Book" author="Jane Doe" cover-image="/cover.jpg" mode="spread">
+<snice-book title="My Book" author="Jane Doe" cover-image="/cover.jpg">
   <div>Page 1 content</div>
   <div>Page 2 content</div>
   <div>Page 3 content</div>

package/docs/ai/components/camera-annotate.md

@@ -23,9 +23,9 @@ clearAnnotations(): void;
 ## Events
 
 ```typescript
-'@snice/capture'           → { dataURL: string; width: number; height: number }
-'@snice/annotate'          → { annotation: Annotation }
-'@snice/annotation-change' → { annotations: Annotation[] }
+'capture'           → { dataURL: string; width: number; height: number }
+'annotate'          → { annotation: Annotation }
+'annotation-change' → { annotations: Annotation[] }
 ```
 
 ## Types

package/docs/ai/components/candlestick.md

@@ -40,9 +40,9 @@ zoomTo(startIndex: number, endIndex: number): void;  // Zoom to range
 ## Events
 
 ```typescript
-'@snice/candle-click': { candle: CandleData; index: number }
-'@snice/candle-hover': { candle: CandleData; index: number }
-'@snice/crosshair-move': { price: number; date: string; x: number; y: number }
+'candle-click': { candle: CandleData; index: number }
+'candle-hover': { candle: CandleData; index: number }
+'crosshair-move': { price: number; date: string; x: number; y: number }
 ```
 
 ## Usage

package/docs/ai/components/chart.md

@@ -65,7 +65,7 @@ update(datasets: ChartDataset[]): void
 addDataset(dataset: ChartDataset): void
 removeDataset(index: number): void
 toggleDataset(index: number): void
-exportImage(format?: 'png'|'svg'): string
+exportImage(format?: 'svg'): string
 getData(): { datasets: ChartDataset[]; labels: string[] }
 ```
 

package/docs/ai/components/code-block.md

@@ -90,9 +90,9 @@ interface GrammarRequestDetail {
 
 ## Events
 
-- `@snice/code-copy` (detail: { code, codeBlock })
-- `@snice/code-before-highlight` (detail: { code, language, codeBlock })
-- `@snice/code-after-highlight` (detail: { code, language, codeBlock })
+- `code-copy` (detail: { code, codeBlock })
+- `code-before-highlight` (detail: { code, language, codeBlock })
+- `code-after-highlight` (detail: { code, language, codeBlock })
 - `grammar-request` (detail: { url, language, codeBlock }) — only dispatched when `fetch-mode="event"`
 
 ## Grammar System

package/docs/ai/components/doc.md

@@ -6,17 +6,23 @@ Simple WYSIWYG document editor with toolbar and sidebar.
 
 ```html
 <snice-doc></snice-doc>
+<snice-doc icons="material"></snice-doc>
+<snice-doc icons="fontawesome"></snice-doc>
 ```
 
 ## Properties
 
 - `placeholder: string` - Placeholder text (default: `"Start typing..."`)
 - `readonly: boolean` - Readonly mode (default: `false`)
+- `icons: 'default' | 'material' | 'fontawesome'` - Toolbar icon set (default: `"default"`)
 
 ## Methods
 
 - `getHTML(): string` - Get HTML content
 - `setHTML(html: string): void` - Set HTML content
+- `getText(): string` - Get plain text content
+- `getMarkdown(): string` - Get content as markdown
+- `downloadAs(format: 'html' | 'markdown' | 'text', filename?: string): void` - Download document
 - `clear(): void` - Clear all content
 
 ## Toolbar
@@ -26,12 +32,16 @@ Simple WYSIWYG document editor with toolbar and sidebar.
 - **•, 1.** - Bulleted and numbered lists
 - **🔗** - Insert link
 - **🖼** - Insert image
+- **📊** - Insert table
+- **―** - Insert divider
+- **⬇** - Download (HTML, Markdown, or Plain Text)
 
-## Sidebar
+## Icon Sets
 
-- **Image** - Insert image via URL
-- **Table** - Insert table (rows × cols)
-- **Divider** - Insert horizontal rule
+- `default` - Text labels and emoji icons
+- `material` - Material Symbols Outlined (user must load the font in the document)
+- `fontawesome` - Font Awesome 6 solid icons (user must load the font in the document)
+- Fonts cascade from light DOM into shadow DOM — no auto-loading
 
 ## Keyboard Shortcuts
 
@@ -64,26 +74,27 @@ const doc = document.querySelector('snice-doc');
 doc.setHTML(`
   <h1>Title</h1>
   <p>Content with <b>bold</b> and <i>italic</i>.</p>
-  <ul>
-    <li>Item 1</li>
-    <li>Item 2</li>
-  </ul>
 `);
 
-// Get content
+// Export formats
 const html = doc.getHTML();
+const markdown = doc.getMarkdown();
+const text = doc.getText();
 
-// Save/load
-localStorage.setItem('doc', doc.getHTML());
-doc.setHTML(localStorage.getItem('doc'));
+// Download
+doc.downloadAs('markdown', 'my-doc.md');
+doc.downloadAs('html');
+doc.downloadAs('text');
 ```
 
 ## Features
 
 - WYSIWYG contentEditable editing
-- Formatting toolbar
-- Insert images, tables, dividers
-- Collapsible sidebar
+- Formatting toolbar with configurable icon sets
+- Insert images, tables, dividers, links
+- Download as HTML, Markdown, or Plain Text
 - Paste images from clipboard
 - Keyboard shortcuts
 - Readonly mode
+- Dark mode (prefers-color-scheme)
+- Material Icons and Font Awesome support

package/docs/ai/components/file-gallery.md

@@ -134,6 +134,6 @@ Uses `@request/@respond` pattern (`file-gallery-upload`). Handler receives `Uplo
 <!-- Events -->
 <script>
 gallery.addEventListener('files-change', (e) => console.log(e.detail.files));
-gallery.addEventListener('upload-complete', (e) => console.log(e.detail.url));
+gallery.addEventListener('upload-complete', (e) => console.log(e.detail.response));
 </script>
 ```

package/docs/ai/components/input.md

@@ -30,6 +30,8 @@ maxlength: number = -1;
 pattern: string = '';
 autocomplete: string = '';
 name: string = '';
+align: 'top'|'center'|'bottom'|'' = '';  // vertical alignment when host has explicit height
+stretch: boolean = false;                 // input fills full host height
 ```
 
 ## Slots
@@ -119,6 +121,14 @@ inp.addEventListener('input-change', (e) => console.log('Change:', e.detail.valu
   <span slot="prefix-icon" class="material-symbols-outlined">search</span>
   <span slot="suffix-icon" class="material-symbols-outlined">person</span>
 </snice-input>
+
+<!-- Vertical alignment (when host has explicit height) -->
+<snice-input style="height:200px" align="top"></snice-input>
+<snice-input style="height:200px" align="center"></snice-input>
+<snice-input style="height:200px" align="bottom"></snice-input>
+
+<!-- Stretch input to fill height -->
+<snice-input style="height:200px" stretch></snice-input>
 ```
 
 ## Features

package/docs/ai/components/link-preview.md

@@ -17,7 +17,7 @@ size: 'small'|'medium'|'large' = 'medium';
 
 ## Events
 
-- `@snice/link-click` → `{ url: string }`
+- `link-click` → `{ url: string }`
 
 ## Usage
 

package/docs/ai/components/list.md

@@ -38,8 +38,8 @@ disabled: boolean = false;
 
 ## Requests
 
-- `@snice/list/search` → `{ query, list }` - Handle search
-- `@snice/list/load-more` → `{ page, list }` - Infinite scroll
+- `list/search` → `{ query, list }` - Handle search
+- `list/load-more` → `{ page, list }` - Infinite scroll
 
 ## Usage
 

package/docs/ai/components/markdown.md

@@ -5,11 +5,18 @@ Lightweight GFM-compatible markdown renderer with built-in sanitization.
 ## Properties
 
 ```ts
-content: string                          // Markdown source text
 sanitize: boolean                        // Sanitize HTML output (default: true)
 theme: 'default' | 'github'             // Visual theme
 ```
 
+## Methods
+
+- `setContent(markdown: string)` — Set markdown source programmatically
+
+## Input
+
+Content via slotted text or `setContent()`. No `content` attribute/property.
+
 ## Events
 
 - `markdown-render` -> `{ html: string }` -- Fired after markdown is rendered
@@ -47,15 +54,15 @@ theme: 'default' | 'github'             // Visual theme
 ## Usage
 
 ```html
-<snice-markdown
-  content="# Hello\n\nThis is **bold** and *italic*."
-  theme="github"
-></snice-markdown>
+<snice-markdown># Hello
+
+This is **bold** and *italic*.
+</snice-markdown>
 ```
 
 ```js
 const md = document.querySelector('snice-markdown');
-md.content = '## Dynamic Content\n\n- Item 1\n- Item 2';
+md.setContent('## Dynamic Content\n\n- Item 1\n- Item 2');
 
 md.addEventListener('link-click', (e) => {
   console.log('Navigating to:', e.detail.href);

package/docs/ai/components/modal.md

@@ -11,6 +11,8 @@ noBackdropDismiss: boolean = false;  // attr: no-backdrop-dismiss
 noEscapeDismiss: boolean = false;    // attr: no-escape-dismiss
 noFocusTrap: boolean = false;        // attr: no-focus-trap
 noCloseButton: boolean = false;      // attr: no-close-button
+noHeader: boolean = false;           // attr: no-header — hides header entirely
+noFooter: boolean = false;           // attr: no-footer — hides footer entirely
 label: string = '';                  // Accessible label
 ```
 

package/docs/ai/components/music-player.md

@@ -56,13 +56,14 @@ interface Track {
 
 - `player-play` → `{ track }`
 - `player-pause` → `{ track }`
-- `player-stop` → `{ track }`
+- `player-stop` → `{ player }`
 - `player-track-change` → `{ track }`
 - `player-track-ended` → `{ track }`
 - `player-shuffle-change` → `{ shuffle }`
 - `player-repeat-change` → `{ repeat }`
 - `player-volume-change` → `{ volume }`
-- `@snice/player-time-update` → `{ currentTime, duration }`
+- `player-seek` → `{ time }`
+- `player-time-update` → `{ currentTime, duration }`
 - `player-error` → `{ error }`
 
 ## Usage

package/docs/ai/components/network-graph.md

@@ -44,10 +44,10 @@ interface NetworkEdge {
 
 ## Events
 
-- `@snice/node-click` → `{ node: NetworkNode }`
-- `@snice/edge-click` → `{ edge: NetworkEdge }`
-- `@snice/node-drag` → `{ node: NetworkNode, x: number, y: number }`
-- `@snice/graph-zoom` → `{ scale: number, x: number, y: number }`
+- `node-click` → `{ node: NetworkNode }`
+- `edge-click` → `{ edge: NetworkEdge }`
+- `node-drag` → `{ node: NetworkNode, x: number, y: number }`
+- `graph-zoom` → `{ scale: number, x: number, y: number }`
 
 ## Usage
 
@@ -66,7 +66,7 @@ graph.data = {
   ],
 };
 
-graph.addEventListener('@snice/node-click', (e) => console.log(e.detail.node));
+graph.addEventListener('node-click', (e) => console.log(e.detail.node));
 ```
 
 ## Features

package/docs/ai/components/notification-center.md

@@ -6,6 +6,7 @@ Bell icon with dropdown notification panel. Shows unread badge, supports dismiss
 
 ```ts
 notifications: NotificationItem[]       // Array of notification objects
+open: boolean                           // Whether the dropdown panel is visible (default: false)
 ```
 
 ### NotificationItem

package/docs/ai/components/pdf-viewer.md

@@ -1,6 +1,6 @@
 # snice-pdf-viewer
 
-PDF document viewer with toolbar (page navigation, zoom, fit modes, download, print). Uses PDF.js loaded from CDN.
+PDF document viewer with toolbar (page navigation, zoom, fit modes, download, print). Uses a vendored PDF.js bundle.
 
 ## Properties
 

package/docs/ai/components/radio.md

@@ -65,5 +65,5 @@ radio.addEventListener('radio-change', (e) => {
 - Automatic radio group management by name
 - 3 sizes
 - Loading state with spinner
-- Keyboard accessible (arrow keys navigate group)
-- Form-associated custom element
+- Keyboard accessible (arrow keys navigate group, wraps around)
+- Contains native `<input type="radio">` for form participation

package/docs/ai/components/sankey.md

@@ -27,9 +27,9 @@ interface SankeyLink { source: string; target: string; value: number; color?: st
 
 ## Events
 
-- `@snice/sankey-node-click` - `{ node: SankeyNode }` - Node clicked
-- `@snice/sankey-link-click` - `{ link: SankeyLink }` - Link clicked
-- `@snice/sankey-hover` - `{ type: 'node'|'link', item: SankeyNode|SankeyLink } | null` - Hover change
+- `sankey-node-click` - `{ node: SankeyNode }` - Node clicked
+- `sankey-link-click` - `{ link: SankeyLink }` - Link clicked
+- `sankey-hover` - `{ type: 'node'|'link', item: SankeyNode|SankeyLink } | null` - Hover change
 
 ## Usage
 

package/docs/ai/components/select.md

@@ -86,7 +86,7 @@ select.selectOption('1');
 
 ## Notes
 
-- Options must be direct children of select
+- Options can be nested (uses querySelectorAll, not just direct children)
 - Multiple selection values are comma-separated
 - Hidden native select for form submission
 - Dropdown closes outside click

package/docs/ai/components/tooltip.md

@@ -57,3 +57,57 @@ strictPositioning: boolean = false; // attr: strict-positioning
   <button>Wait</button>
 </snice-tooltip>
 ```
+
+## Attribute-Based Tooltips (`useTooltips`)
+
+Opt-in observer for `tooltip` attribute on any element. No wrapper element — safe inside strict-children components (tabs, accordion, etc.).
+
+### Setup
+
+```typescript
+import { useTooltips } from 'snice';
+useTooltips(); // idempotent
+```
+
+### Usage
+
+```html
+<button tooltip="Save changes">Save</button>
+<button tooltip="Below" style="--tooltip-position: bottom">Bottom</button>
+
+<!-- Inside strict-children components -->
+<snice-tabs>
+  <snice-tab slot="nav" tooltip="User settings">Settings</snice-tab>
+</snice-tabs>
+
+<!-- Scoped config via CSS -->
+<style>
+  .toolbar [tooltip] { --tooltip-position: bottom; --tooltip-delay: 200; }
+</style>
+```
+
+### CSS Variable API
+
+| Variable | Default | Description |
+|---|---|---|
+| `--tooltip-position` | `top` | top/bottom/left/right + -start/-end |
+| `--tooltip-trigger` | `hover` | hover, click, focus |
+| `--tooltip-delay` | `0` | Show delay (ms) |
+| `--tooltip-hide-delay` | `0` | Hide delay (ms) |
+| `--tooltip-offset` | `12` | Distance from trigger (px) |
+| `--tooltip-arrow` | (shown) | `none` to hide |
+| `--tooltip-max-width` | `250` | Max width (px) |
+| `--tooltip-z-index` | `10000` | Z-index |
+| `--tooltip-strict-positioning` | (false) | `true` to disable auto-flip |
+| `--tooltip-bg` | `hsl(0 0% 20%)` | Background color |
+| `--tooltip-color` | `white` | Text color |
+| `--tooltip-padding` | `8px 12px` | Content padding |
+| `--tooltip-radius` | `6px` | Border radius |
+| `--tooltip-font-size` | `14px` | Font size |
+
+### Cleanup
+
+```typescript
+import { cleanupTooltips } from 'snice';
+cleanupTooltips(); // disconnect observer, remove portals
+```

package/docs/ai/decorators.md

@@ -1,7 +1,7 @@
 # Decorators
 
 ## Class
-- `@element('tag-name')` - Custom element
+- `@element('tag-name', options?)` - Custom element. Options: `{ formAssociated?: boolean }`
 - `@page({ tag, routes, guards?, placard? })` - Routable page
 - `@controller('name')` - Swappable behavior
 - `@layout('tag-name')` - Page wrapper for routing system
@@ -22,12 +22,12 @@
 - `@adopted(options?: { throttle?, debounce? })` - On adoptedCallback (alias for moved)
 
 ## DOM
-- `@query('selector')` - Single element
-- `@queryAll('selector')` - NodeList
+- `@query('selector', { light? })` - Single element. `{ light: true }` for controllers on native elements
+- `@queryAll('selector', { light? })` - NodeList
 
 ## Events
 - `@on('event', 'selector?')` - Delegation, auto-bound
-- `@dispatch('event-name')` - Emit CustomEvent, detail = return value
+- `@dispatch('event-name', options?)` - Emit CustomEvent, detail = return value. Supports async. Options: `{ debounce?, throttle?, dispatchOnUndefined? }`
 
 ## Communication
 - `@request(channel, options?)` - Async generator request pattern