@mhmo91/schmancy 0.9.2 → 0.9.4

package/ai/theme-button.md

@@ -0,0 +1,26 @@
+# schmancy-theme-button
+
+> Minimal palette-icon button that spins 360° on click. Hook its `click` to toggle/regenerate your theme.
+
+## Usage
+```html
+<schmancy-theme-button @click=${() => this.toggleTheme()}></schmancy-theme-button>
+```
+
+## Behavior
+- Renders a `schmancy-button` (variant `text`) wrapping a palette `schmancy-icon`.
+- On click: Web Animations API rotates the icon 360° over 300ms.
+- No properties — it's a UI affordance; wire the theme logic via `@click`.
+
+## Typical Wiring
+```typescript
+import { theme } from '@mhmo91/schmancy'
+
+// Toggle dark/light
+<schmancy-theme-button @click=${() => theme.toggleScheme()}></schmancy-theme-button>
+
+// Randomize primary color
+<schmancy-theme-button @click=${() => theme.randomize()}></schmancy-theme-button>
+```
+
+See [theme.md](./theme.md) for the full theme service API.

package/ai/typewriter.md

@@ -0,0 +1,46 @@
+# schmancy-typewriter
+
+> Text-reveal component powered by [TypeIt](https://typeitjs.com). Characters pop in with entrance + wobble physics; custom cursor pulses with drop-shadow glow.
+
+## Usage
+```html
+<schmancy-typewriter>
+  Hello, world.
+</schmancy-typewriter>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `speed` | number | `35` | Ms per character typed |
+| `deleteSpeed` | number | `20` | Ms per character deleted |
+| `delay` | number | `0` | Initial delay before typing (inherited via `delayContext`) |
+| `autoStart` | boolean | `true` | Start typing on connect |
+| `cursorChar` | string | `''` | Character for the cursor (empty = default block cursor) |
+| `once` | boolean | `true` | Only animate once per session (`sessionStorage` hash) |
+| `loop` | boolean | `false` | Loop infinitely (overrides `once`) |
+| `cyclePause` | number | `1500` | Default pause for cycling (ms) |
+
+## Behavior
+- **Lazy start** via IntersectionObserver — won't type until visible.
+- **Session caching** — when `once=true`, content hash is stored; subsequent visits skip the animation.
+- **Delay coordination** — consumes `delayContext`, staggering with parent `schmancy-delay`.
+- Character entrance animation: scale 0.3 → 1.1 → 1 with blur-to-focus.
+- Alternating characters get a subtle `wobble` rotation.
+- Cursor pulses with `drop-shadow(0 0 8px currentColor)` glow.
+
+## Slot Content
+Text (or nested HTML) goes in the default slot. TypeIt handles strings, tags, line breaks.
+
+```html
+<schmancy-typewriter speed="50">
+  First line.<br>
+  <strong>Bold second.</strong>
+</schmancy-typewriter>
+```
+
+## Vs. `typewriter` directive
+- **Component (`schmancy-typewriter`)**: slot-based, lazy-starts on visibility, one-shot content reveal with cached skipping.
+- **Directive (`typewriter([...phrases])`)**: cycles through a phrase array with typing + deleting + optional Web Audio sound. See [directives.md](./directives.md).
+
+Use the directive for looping taglines. Use the component for one-time paragraph reveals.

package/ai/utils.md

@@ -0,0 +1,95 @@
+# Schmancy Utils
+
+> Non-component utilities exported from `@mhmo91/schmancy` (or `@mhmo91/schmancy/utils`). Animation presets, similarity search, number formatting, intersection observer wrapper, overlay z-index manager, and content hashing.
+
+## Animation
+
+See [animation.md](./animation.md) for the full Blackbird spring system. In brief:
+
+```typescript
+import {
+  SPRING_SMOOTH, SPRING_SNAPPY, SPRING_BOUNCY, SPRING_GENTLE,
+  createAnimation, createRevealAnimation, createDismissAnimation, createScaleAnimation,
+  getEasing, prefersReducedMotion,
+  ANIMATION_CSS_VARS, tailwindAnimations, GRID_ANIMATION_CSS,
+} from '@mhmo91/schmancy'
+```
+
+## Number Formatting — `numbers` / `Numbers`
+Locale-aware number formatting + currency + rounding.
+```typescript
+import numbers from '@mhmo91/schmancy'
+
+numbers.roundNumber(3.14159, 2)              // 3.14
+numbers.format(1234567.89)                   // "1,234,567.89" (system locale)
+numbers.format(1234.5, 'de-DE')              // "1.234,5"
+numbers.formatCurrency(99.95, 'EUR')         // "€99.95"
+numbers.systemLocale                         // "en-US" / "de-DE" / etc.
+```
+
+## Fuzzy Search — `similarity(query, target, options?)`
+Autocomplete-tuned similarity scoring. Prioritizes start-matches and word boundaries.
+```typescript
+import { similarity } from '@mhmo91/schmancy'
+
+similarity('john', 'John Doe')   // ~0.975 (starts-with)
+similarity('doe', 'John Doe')    // ~0.765 (word-boundary)
+similarity('jhn', 'John Doe')    // ~0.3–0.5 (fuzzy)
+```
+
+Tiers:
+- `1.00` exact
+- `0.95–1.00` target starts with query
+- `0.765–0.85` word-boundary match
+- `0.56–0.70` substring
+- `0.50` subsequence
+- `0.00–0.50` fuzzy (Dice + Levenshtein + Jaccard + anagram)
+
+Options:
+| Key | Default | Effect |
+|-----|---------|--------|
+| `normalizeAccents` | `true` | Strip diacritics before compare |
+| `includeWordJaccard` | `true` | Add word-set overlap to fuzzy score |
+| `maxLevenshteinDistance` | `0` | Early-terminate above this distance (`0` = off) |
+
+## Intersection Observer — `intersection$(element, options?)`
+RxJS wrapper around `IntersectionObserver`.
+```typescript
+import { intersection$ } from '@mhmo91/schmancy'
+
+intersection$(this.card, { threshold: 0.5 })
+  .pipe(takeUntil(this.disconnecting))
+  .subscribe(entries => {
+    if (entries[0].isIntersecting) this.loadContent()
+  })
+```
+
+## Overlay Stack — `overlayStack`
+Singleton z-index coordinator used internally by dialogs, sheets, and windows. Ensures overlays stack in open order.
+
+```typescript
+import { overlayStack } from '@mhmo91/schmancy'
+
+// Anonymous (fire-and-forget) — dialogs/sheets
+const z = overlayStack.getNextZIndex()
+// …on close:
+overlayStack.release()
+
+// ID-tracked — windows (supports bringToFront)
+overlayStack.assignZIndex('my-window')
+overlayStack.bringToFront('my-window')
+overlayStack.releaseId('my-window')
+```
+
+Base z-index: `10000`. Counter resets when all overlays close.
+
+## Content Hashing — `hashContent(string)`
+Fast 32-bit FNV-1a style hash, returns a hex string. Used by [`schmancy-delay`](./delay.md) and [`schmancy-typewriter`](./typewriter.md) for session-scoped caching.
+```typescript
+import hashContent from '@mhmo91/schmancy/utils/hashContent'
+const key = hashContent(element.outerHTML)   // stable across renders for identical content
+```
+
+## See Also
+- [rxjs-utils](./rxjs-utils.md) — DOM observation helpers (`waitForElement`, `waitUntil`, etc.)
+- [discovery](./discovery.md) — cross-shadow component discovery

package/ai/window.md

@@ -0,0 +1,67 @@
+# schmancy-window
+
+> Floating draggable window with corner snapping, resize, and minimize/maximize states. Replaces deprecated `schmancy-float`.
+
+## Usage
+```html
+<schmancy-window id="chat" corner="bottom-right">
+  <span slot="header">Chat</span>
+  <schmancy-icon slot="icon">chat</schmancy-icon>
+  <div>Window body content…</div>
+</schmancy-window>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `id` | string | `'default'` | Unique window identifier (used by `windowManager` registry) |
+| `open` | boolean | `false` | Body expanded state |
+| `corner` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Anchor corner |
+| `freePosition` | boolean | `false` | Keep dragged position instead of snapping to corner |
+| `resizable` | boolean | `false` | Allow user resizing from edges |
+| `visualState` | `'minimized' \| 'normal' \| 'maximized'` | `'normal'` | Reflected state attribute |
+| `expandedWidth` | string | responsive | e.g. `'320px'`, `'24rem'` |
+| `expandedHeight` | string | auto | e.g. `'400px'`, `'50vh'` |
+| `minWidth` | number | `280` | Minimum width px during resize |
+| `minHeight` | number | `200` | Minimum height px during resize |
+| `lowered` | boolean | `false` | Lower elevation shadow in collapsed state |
+
+## Slots
+| Slot | Purpose |
+|------|---------|
+| `icon` | Leading icon in the head (minimized FAB state) |
+| `header` | Header label (visible when expanded) |
+| (default) | Window body content (lazy rendered — not in DOM until first open) |
+
+## Behavior
+- Drag from head to reposition. Release snaps to the nearest corner unless `freePosition`.
+- `windowManager` tracks focused window and resolves overlap between multiple windows.
+- `cursorGlow` applied to head while expanded.
+- Collapsed state uses a clip-path reveal animation; expand uses `SPRING_SMOOTH` physics.
+- Body content mounts lazily on first expand (`_hasOpened`).
+- All animations respect `prefers-reduced-motion` via `reducedMotion$`.
+
+## Examples
+```html
+<!-- Chat-style window docked bottom-right -->
+<schmancy-window id="support" corner="bottom-right">
+  <schmancy-icon slot="icon">support_agent</schmancy-icon>
+  <span slot="header">Support</span>
+  <div class="p-4">How can we help?</div>
+</schmancy-window>
+
+<!-- Resizable, free-position floating panel -->
+<schmancy-window id="inspector" resizable free-position expanded-width="420px" expanded-height="60vh">
+  <span slot="header">Inspector</span>
+  <div>…</div>
+</schmancy-window>
+```
+
+## windowManager
+```typescript
+import { windowManager } from '@mhmo91/schmancy/window'
+
+windowManager.focus('support')       // Bring window to front
+windowManager.getBounds('inspector') // Read tracked bounds
+windowManager.all$ .subscribe(...)    // Observable of registered windows
+```

package/dist/ai/INDEX.md

@@ -0,0 +1,72 @@
+# Schmancy — Documentation Index
+
+A Web Component UI library on Lit + RxJS + Tailwind CSS.
+
+## Foundations
+
+The framework pieces — touch before components.
+
+- [Area](./area.md) — `<schmancy-area>`, `<schmancy-route>`, `area.push()`, `lazy()` for routing.
+- [Store](./store.md) — `createContext`, `@select`, `@selectItem`, storage backends.
+- [Mixins](./mixins.md) — `$LitElement` base class.
+- [Theme](./theme.md) — `<schmancy-theme>`, color scheme, CSS variables.
+- [Directives](./directives.md) — Lit directives for physics, effects, text, visibility, interaction.
+- [Animation](./animation.md) — Spring presets (`SPRING_SMOOTH`, etc.), `createAnimation`.
+
+## Components by job
+
+### Display
+[Typography](./typography.md) · [Icons](./icons.md) · [Avatar](./avatar.md) · [Divider](./divider.md) · [Badge](./badge.md) · [Code Highlight](./code-highlight.md) · [Typewriter](./typewriter.md) · [JSON](./json.md) · [Iframe](./iframe.md) · [Map](./map.md) · [Charts](./charts.md)
+
+### Surfaces & layout
+[Surface](./surface.md) · [Card](./card.md) · [Scroll / Grid / Flex](./layout.md) · [Page](./page.md) · [Content Drawer](./content-drawer.md) · [Window](./window.md) · [Boat](./boat.md) · [Float](./float.md)
+
+### Forms
+[Form](./form.md) · [Input](./input.md) · [Textarea](./textarea.md) · [Select](./select.md) · [Autocomplete](./autocomplete.md) · [Option](./option.md) · [Checkbox](./checkbox.md) · [Radio Group](./radio-group.md) · [Chips](./chips.md) · [Date Range](./date-range.md) · [Date Range Inline](./date-range-inline.md) · [Range](./range.md) · [Extra (Country/Timezone)](./extra.md)
+
+### Navigation
+[Nav Drawer](./nav-drawer.md) · [Tabs](./tabs.md) · [Navigation Bar](./navigation-bar.md) · [Navigation Rail](./navigation-rail.md) · [Steps](./steps.md) · [Teleport](./teleport.md) · [Theme Button](./theme-button.md)
+
+### Overlays
+[Dialog](./dialog.md) · [Sheet](./sheet.md) · [Notification](./notification.md) · [Menu](./menu.md) · [Dropdown](./dropdown.md) · [Tooltip](./tooltip.md) · [Lightbox](./lightbox.md) · [Expand](./expand.md)
+
+### Interactive
+[Button](./button.md) · [List](./list.md) · [Details](./details.md) · [Table](./table.md) · [Tree](./tree.md) · [Slider](./slider.md) · [QR Scanner](./qr-scanner.md)
+
+### Feedback
+[Progress](./progress.md) · [Busy](./busy.md) · [Connectivity](./connectivity.md) · [Delay](./delay.md)
+
+### Domain
+[Mailbox](./mailbox.md)
+
+## Services (imperative APIs)
+
+| Service | Purpose |
+|---------|---------|
+| `area` | Route navigation (see [area](./area.md)) |
+| `$dialog` | Open dialogs (see [dialog](./dialog.md)) |
+| `$notify` | Toast notifications (see [notification](./notification.md)) |
+| `schmancyContentDrawer` | Side panel (see [content-drawer](./content-drawer.md)) |
+| `theme` | Theme state, `fullscreen$` (see [theme](./theme.md)) |
+| `sound` | Audio feedback (see [audio](./audio.md)) |
+| `overlayStack` | Z-index coordinator (see [utils](./utils.md)) |
+| `windowManager` | Window registry (see [window](./window.md)) |
+
+## Utilities
+
+[Discovery](./discovery.md) — cross-shadow component lookup.
+[RxJS Utils](./rxjs-utils.md) — `waitForElement`, `waitUntil`, `mutationObserver`.
+[Utils](./utils.md) — `similarity`, `numbers`, `overlayStack`, `intersection$`, `hashContent`.
+[Audio](./audio.md) — synthesized feedback sounds.
+
+## Conventions
+
+- Lists use `repeat(items, item => item.id, tpl)`.
+- View switching uses `cache(...)`.
+- Expensive work uses `guard([deps], fn)`.
+- DOM access uses `ref(createRef())`.
+- Conditionals use `when(...)`, `choose(...)`, `ifDefined(...)`.
+- All RxJS subscriptions end with `.pipe(takeUntil(this.disconnecting))`.
+- Don't use `setTimeout` / `setInterval` / `addEventListener` — use RxJS (`timer`, `interval`, `fromEvent`).
+- Colors come from `--schmancy-sys-color-*` CSS vars or Tailwind theme classes.
+- `classMap(...)` must be the sole expression in `class=`; never mix with string interpolation.

package/dist/ai/area.md

@@ -1,61 +1,141 @@
-# schmancy-area / schmancy-route
+# Area — Routing
 
-> Client-side router with named areas, lazy loading, route guards, and browser history integration.
+Schmancy's client-side router. Three pieces:
+
+| Piece | Role |
+|-------|------|
+| `<schmancy-area name="...">` | Named region that renders one route at a time |
+| `<schmancy-route when="tag">` | Declares which component can render in an area |
+| `area.push(...)` | Imperative navigation |
+
+Areas can be nested to compose shell-plus-sub-view layouts.
+
+## Example
 
-## Usage
 ```html
-<schmancy-area name="main" default="home-page">
-  <schmancy-route when="home-page" .component=${lazy(() => import('./home'))}></schmancy-route>
-  <schmancy-route when="settings-page" .component=${lazy(() => import('./settings'))}></schmancy-route>
+<schmancy-area name="root" .default=${lazy(() => import('./pages/home.page'))}>
+  <schmancy-route when="home-page"
+    .component=${lazy(() => import('./pages/home.page'))}></schmancy-route>
+
+  <schmancy-route when="app-index"
+    .component=${lazy(() => import('./app/app.page'))}
+    .guard=${authState$.pipe(
+      map(u => !!u && !u.isAnonymous),
+      takeUntil(this.disconnecting),
+    )}
+    @redirect=${() => area.push({
+      component: 'home-page',
+      area: 'root',
+      historyStrategy: 'replace',
+    })}></schmancy-route>
 </schmancy-area>
 ```
 
-## Properties (schmancy-area)
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| name | string | required | Unique area name |
-| default | RouteComponent | - | Default route component |
-
-## Properties (schmancy-route)
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| when | string | required | Route identifier (must match `@customElement` tag) |
-| component | RouteComponent | required | Component to render (class, tag name, or lazy) |
-| exact | boolean | `false` | Exact path matching |
-| guard | Observable<boolean> | - | Route guard observable |
-
-## Programmatic Navigation (area service)
+## `schmancy-area` properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | string (required) | Area identifier used in `area.push({ area })` |
+| `default` | `RouteComponent \| string` | Fallback when no route matches |
+
+## `schmancy-route` properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `when` | string (required) | Must match a `@customElement('tag')` tag name |
+| `component` | `RouteComponent` (required) | Class, tag name, or `lazy()` wrapper |
+| `guard` | `Observable<boolean>` | When emits `false`, blocks and dispatches `redirect` event |
+| `exact` | boolean | Strict-equality matching |
+
+## `area` service
+
 ```typescript
 import { area } from '@mhmo91/schmancy'
 
-// Navigate
-area.push({ area: 'main', component: 'settings-page', params: { id: '123' } })
+area.push({
+  area: 'root',
+  component: 'app-index',
+  params?: { id: '123' },
+  historyStrategy?: 'push' | 'replace' | 'silent',
+})
+```
+
+`historyStrategy`:
+- `'push'` (default) — adds a browser-history entry
+- `'replace'` — overwrites the current entry (use after guards or redirects)
+- `'silent'` — changes the area without touching history
 
-// Subscribe to area changes
-area.on('main').pipe(takeUntil(this.disconnecting)).subscribe(route => { ... })
+### Subscribe to route state
 
-// Get params
-area.params<{id: string}>('main').pipe(takeUntil(this.disconnecting)).subscribe(params => { ... })
+```typescript
+area.on('root').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(route => { /* route.component, route.params */ })
+
+area.params<{ id: string }>('detail').pipe(
+  takeUntil(this.disconnecting),
+).subscribe(params => this.loadItem(params.id))
 ```
 
-## Lazy Loading
+## Lazy loading
+
 ```typescript
 import { lazy } from '@mhmo91/schmancy'
-const LazyPage = lazy(() => import('./my-page'))
+const HomePage = lazy(() => import('./home.page'))
+
+// Optional preload
+html`<button @mouseenter=${() => HomePage.preload()}>Home</button>`
+```
+
+## Guards
+
+`guard` is an Observable<boolean>.
+
+- Emits `true` → route renders.
+- Emits `false` → route dispatches a `redirect` event. Handle it with `area.push(...)`.
 
-// Preload on hover
-element.addEventListener('mouseenter', () => LazyPage.preload())
+Auth guard:
+
+```typescript
+<schmancy-route when="app-index"
+  .component=${lazy(() => import('./app'))}
+  .guard=${authState$.pipe(
+    map(u => !!u),
+    takeUntil(this.disconnecting),
+  )}
+  @redirect=${() => area.push({
+    component: 'home-page', area: 'root', historyStrategy: 'replace',
+  })}></schmancy-route>
 ```
 
-## Examples
+Compound guard (multiple streams):
+
+```typescript
+.guard=${combineLatest([permissions$, orgContext.$]).pipe(
+  takeUntil(this.disconnecting),
+  map(([perms, org]) => perms.includes('billing.view') && org?.billing?.configured),
+)}
+```
+
+## Nested areas
+
+Areas nest by rendering an inner `<schmancy-area>` inside a route component. A common shape is an outer area for "signed-in vs. not" and an inner area for sub-views of the signed-in shell.
+
 ```html
-<!-- With route guard -->
-<schmancy-area name="admin" default="admin-dashboard">
-  <schmancy-route when="admin-dashboard"
-    .component=${lazy(() => import('./dashboard'))}
-    .guard=${isAdmin$}>
-  </schmancy-route>
+<!-- outer -->
+<schmancy-area name="root">
+  <schmancy-route when="app-index" .component=${AppShell}></schmancy-route>
+</schmancy-area>
+
+<!-- inner (inside AppShell.render()) -->
+<schmancy-area name="app" default="home-page">
+  <schmancy-route when="home-page" .component=${...}></schmancy-route>
+  <schmancy-route when="settings-page" .component=${...}></schmancy-route>
 </schmancy-area>
 ```
 
-**Critical:** `when="tag-name"` MUST exactly match `@customElement('tag-name')` on the component class.
+## Rules
+
+- `when="tag-name"` must match `@customElement('tag-name')` exactly.
+- Guards emit `false` → always use `historyStrategy: 'replace'` in the `@redirect` handler.
+- Every subscription in guards / route state uses `takeUntil(this.disconnecting)`.

package/dist/ai/audio.md

@@ -0,0 +1,69 @@
+# Schmancy Audio
+
+> Emotional sound service — synthesizes short, empathetic sounds via Web Audio API keyed on feelings (joyful, tense, calm, etc.). No assets. No external players. Just tones + puffs generated on demand.
+
+## Usage
+```typescript
+import { sound } from '@mhmo91/schmancy'
+
+sound.play('joyful')     // trigger a feeling sound
+sound.setVolume(0.2)     // 0..1
+sound.setMuted(true)
+sound.resetTheme()       // back to defaults
+```
+
+## Feelings
+Organized by emotional category:
+
+| Category | Feelings |
+|----------|----------|
+| Happy | `joyful`, `content`, `excited`, `grateful`, `proud`, `loved` |
+| Sad | `sad`, `disappointed`, `hurt`, `lonely`, `melancholy` |
+| Anxious | `worried`, `nervous`, `overwhelmed`, `tense` |
+| Angry | `frustrated`, `angry`, `annoyed` |
+| Tired | `tired`, `drained`, `bored` |
+| Calm | `calm`, `peaceful`, `relaxed`, `focused` |
+| Connected | `connected`, `supported`, `welcomed` |
+| Mixed | `confused`, `nostalgic`, `bittersweet` |
+
+(See `mood-audio.types.ts` for the authoritative list.)
+
+## Observable API
+```typescript
+sound.theme$.subscribe(theme => console.log(theme?.name ?? 'default'))
+sound.volume$.subscribe(v => {})
+sound.muted$.subscribe(m => {})
+```
+
+## Settings Persistence
+Volume, mute, and custom theme persist to `localStorage` under key `schmancy-sound-settings` (via `createContext`).
+
+## AI-Generated Themes
+```typescript
+import type { SoundTheme } from '@mhmo91/schmancy'
+
+const customTheme: SoundTheme = {
+  name: 'ocean',
+  sounds: {
+    joyful: { puffs: [...], tones: [...] },
+    // partial override — falls through to defaults for anything omitted
+  }
+}
+
+sound.setTheme(customTheme)
+```
+
+Each `FeelingSound` consists of:
+- **puffs** — short bursts (air/noise, e.g. `{ startTime, duration, frequency, volume }`)
+- **tones** — oscillators (`sine`/`triangle`/`square`/`sawtooth` with envelope)
+
+## Built-in Feedback Hooks
+Other Schmancy components play these automatically:
+- [`schmancy-connectivity-status`](./connectivity.md) on offline/online.
+- Some success/error paths in notifications and dialogs via the `$sounds` legacy helper.
+
+## Legacy API
+- `$sounds` — older generator exported for compatibility.
+- `EmotionalSoundGenerator` — underlying class.
+
+Prefer `sound` for new code.

package/dist/ai/boat.md

@@ -0,0 +1,47 @@
+# schmancy-boat
+
+> Draggable floating FAB that expands into a panel. Great for persistent assistant/chat panels.
+
+> **Note:** `schmancy-window` is the evolved successor with more capabilities (resize, maximize, multi-window registry). Prefer `schmancy-window` for new code unless you want the simpler FAB-to-panel model.
+
+## Usage
+```html
+<schmancy-boat id="assistant" icon="smart_toy" label="Assistant">
+  <div slot="header">Assistant</div>
+  <div class="p-4">Panel body content</div>
+</schmancy-boat>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `id` | string | `'default'` | Unique identifier (persists drag position in localStorage) |
+| `icon` | string | — | Material icon for the FAB state |
+| `label` | string | — | Label text in FAB state |
+| `open` | boolean | `false` | Panel open/closed (reflected) |
+| `corner` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Anchor corner |
+| `expandedWidth` | string | responsive | e.g. `'320px'` |
+| `lowered` | boolean | `false` | Lower shadow in FAB state |
+
+## Getter / Setter
+```typescript
+boat.state = 'expanded' | 'collapsed'   // equivalent to open = true/false
+boat.state                              // current state
+boat.expand() / boat.close()
+```
+
+## Behavior
+- Drag to reposition. Releases snap to the nearest corner.
+- Open/close uses clip-path + `SPRING_SMOOTH` for elegant reveal.
+- Position persists in `localStorage` under `schmancy-boat-{id}`.
+- Respects `prefers-reduced-motion`.
+
+## Example
+```html
+<schmancy-boat id="chat" icon="chat" label="Chat" corner="bottom-right">
+  <span slot="header">Messages</span>
+  <schmancy-list class="p-2">
+    <!-- messages -->
+  </schmancy-list>
+</schmancy-boat>
+```