@mhmo91/schmancy 0.9.2 → 0.9.3

package/ai/area.md

@@ -1,61 +1,215 @@
-# schmancy-area / schmancy-route
+# Area — Routing Foundation
 
-> Client-side router with named areas, lazy loading, route guards, and browser history integration.
+> **Not just a component. The routing framework your app runs on.**
+> `area` is the imperative API. `schmancy-area` is the region where a component lives. `schmancy-route` declares the options.
 
-## 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>
+Routing in Schmancy is four things working together:
+
+| Piece | Role |
+|-------|------|
+| `<schmancy-area name="...">` | Declares a named region of the screen |
+| `<schmancy-route when="tag">` | Declares which component can occupy it |
+| `area.push(...)` | Imperative navigation (click handlers, guards, effects) |
+| `lazy(() => import('...'))` | Code-split route components |
+
+## The Shape of a Real App
+
+Real apps nest areas. Outer `name="root"` handles public vs. authenticated. Inner `name="aria"` handles sub-views inside the authenticated shell.
+
+```typescript
+// app root — handles sign-in / public / authenticated
+@customElement('my-app')
+class MyApp extends $LitElement() {
+  render() {
+    return html`
+      <schmancy-theme root scheme="dark">
+        <schmancy-surface type="solid" fill="all">
+          <schmancy-scroll>
+            <schmancy-area
+              name="root"
+              .default=${lazy(() => import('./pages/landing.page'))}
+            >
+              <schmancy-route when="landing-page"
+                .component=${lazy(() => import('./pages/landing.page'))}
+              ></schmancy-route>
+
+              <schmancy-route when="methodology-page"
+                .component=${lazy(() => import('./pages/methodology.page'))}
+              ></schmancy-route>
+
+              <!-- Guarded route -->
+              <schmancy-route when="app-index"
+                .component=${lazy(() => import('./app/app.page'))}
+                .guard=${firebaseAuthState$.pipe(
+                  map(u => !!u && !u.isAnonymous),
+                  takeUntil(this.disconnecting),
+                )}
+                @redirect=${() => area.push({
+                  component: 'landing-page',
+                  area: 'root',
+                  historyStrategy: 'replace',
+                })}
+              ></schmancy-route>
+            </schmancy-area>
+          </schmancy-scroll>
+        </schmancy-surface>
+      </schmancy-theme>
+    `
+  }
+}
+```
+
+```typescript
+// nested area — inside the app shell
+render() {
+  return html`
+    <schmancy-nav-drawer>
+      <schmancy-nav-drawer-navbar width="180px">
+        <schmancy-list-item @click=${() => area.push({ area: 'aria', component: 'aria-agents-page' })}>
+          Agents
+        </schmancy-list-item>
+        <schmancy-list-item @click=${() => area.push({ area: 'aria', component: 'aria-knowledge-page' })}>
+          Knowledge
+        </schmancy-list-item>
+      </schmancy-nav-drawer-navbar>
+
+      <schmancy-nav-drawer-content>
+        <schmancy-area name="aria" default="aria-knowledge-page">
+          <schmancy-route when="aria-agents-page" .component=${lazy(() => import('./pages/agents'))}></schmancy-route>
+          <schmancy-route when="aria-knowledge-page" .component=${lazy(() => import('./pages/knowledge'))}></schmancy-route>
+          <schmancy-route when="aria-templates-page" .component=${lazy(() => import('./pages/templates'))}></schmancy-route>
+        </schmancy-area>
+      </schmancy-nav-drawer-content>
+    </schmancy-nav-drawer>
+  `
+}
 ```
 
-## Properties (schmancy-area)
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| name | string | required | Unique area name |
-| default | RouteComponent | - | Default route component |
+## `schmancy-area` Properties
 
-## 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 |
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | ✅ | Unique area identifier referenced in `area.push({ area: name })` |
+| `default` | `RouteComponent \| string` | — | Fallback when no route matches — prefer `lazy()` |
+
+## `schmancy-route` Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `when` | string | ✅ | **Must exactly match** a `@customElement('tag')` tag name |
+| `component` | `RouteComponent` | ✅ | Class, tag name, or `lazy()` wrapper |
+| `guard` | `Observable<boolean>` | — | When emits `false`, route blocks and fires `@redirect` |
+| `exact` | boolean | — | Strict-equality matching |
+
+## `area` service (imperative API)
 
-## Programmatic Navigation (area service)
 ```typescript
 import { area } from '@mhmo91/schmancy'
 
-// Navigate
-area.push({ area: 'main', component: 'settings-page', params: { id: '123' } })
+area.push({
+  area: 'root',               // target area name
+  component: 'app-index',     // tag name (or class reference)
+  params?: { id: '123' },     // pushed onto area.params()
+  historyStrategy?: 'push' | 'replace' | 'silent',
+})
+```
+
+`historyStrategy`:
+- `'push'` (default) — browser back button returns to previous route
+- `'replace'` — overwrites current history entry (use after guards / redirects)
+- `'silent'` — changes the area without adding any history (transient state)
 
-// Subscribe to area changes
-area.on('main').pipe(takeUntil(this.disconnecting)).subscribe(route => { ... })
+### Subscribe to route state
+```typescript
+connectedCallback() {
+  super.connectedCallback()
+
+  area.on('root').pipe(
+    takeUntil(this.disconnecting),
+  ).subscribe(route => {
+    console.log('root area is now:', route.component)
+  })
 
-// Get params
-area.params<{id: string}>('main').pipe(takeUntil(this.disconnecting)).subscribe(params => { ... })
+  area.params<{ id: string }>('detail').pipe(
+    takeUntil(this.disconnecting),
+  ).subscribe(params => this.loadItem(params.id))
+}
 ```
 
 ## Lazy Loading
+
+Code-split your routes. `lazy()` returns a preloadable reference.
+
 ```typescript
 import { lazy } from '@mhmo91/schmancy'
-const LazyPage = lazy(() => import('./my-page'))
 
-// Preload on hover
-element.addEventListener('mouseenter', () => LazyPage.preload())
+const HomePage = lazy(() => import('./home.page'))
+
+// Optional: preload on hover
+<schmancy-button
+  @mouseenter=${() => HomePage.preload()}
+  @click=${() => area.push({ area: 'root', component: 'home-page' })}
+>
+  Home
+</schmancy-button>
 ```
 
-## Examples
-```html
-<!-- With route guard -->
-<schmancy-area name="admin" default="admin-dashboard">
-  <schmancy-route when="admin-dashboard"
-    .component=${lazy(() => import('./dashboard'))}
-    .guard=${isAdmin$}>
-  </schmancy-route>
-</schmancy-area>
+## Guards — the production pattern
+
+Guards are **RxJS Observables**, not booleans. This lets auth state flow through naturally.
+
+```typescript
+import { firebaseAuthState$ } from './contexts/user.context'
+
+<schmancy-route when="app-index"
+  .component=${lazy(() => import('./app/app.page'))}
+  .guard=${firebaseAuthState$.pipe(
+    map(user => !!user && !user.isAnonymous),
+    takeUntil(this.disconnecting),
+  )}
+  @redirect=${() => area.push({
+    component: 'landing-page',
+    area: 'root',
+    historyStrategy: 'replace',
+  })}
+></schmancy-route>
+```
+
+- `guard` emits `true` → route renders.
+- `guard` emits `false` → Schmancy fires a `redirect` event on the route; handle it with `area.push(...)` using `historyStrategy: 'replace'` so the blocked route doesn't stay in history.
+
+## Rules
+
+1. `when="tag-name"` **must exactly match** `@customElement('tag-name')` on the component's class.
+2. Every route component should extend `$LitElement` and use `takeUntil(this.disconnecting)` in subscriptions.
+3. Route components are responsible for their own scroll/focus handling on mount.
+4. When calling `area.push` after auth guards or side-effectful redirects, use `historyStrategy: 'replace'`.
+5. Nested areas are not just allowed — they're the default for any app with a shell + sub-views.
+
+## Common recipes
+
+### Redirect after sign-in
+```typescript
+await signIn(email, password)
+area.push({ component: 'app-index', area: 'root', historyStrategy: 'replace' })
+```
+
+### Silent state swap (no history pollution)
+```typescript
+// e.g. swapping between auth screens without adding history
+area.push({ component: 'signup-form', area: 'sign', historyStrategy: 'silent' })
+```
+
+### Click-driven sub-nav
+```typescript
+<schmancy-list-item @click=${() => area.push({ area: 'aria', component: 'aria-agents-page' })}>
+  Agents
+</schmancy-list-item>
 ```
 
-**Critical:** `when="tag-name"` MUST exactly match `@customElement('tag-name')` on the component class.
+### Preload routes on hover
+```typescript
+const DashboardPage = lazy(() => import('./dashboard.page'))
+
+html`<a @mouseenter=${() => DashboardPage.preload()} @click=${() => area.push({ area: 'root', component: 'dashboard-page' })}>Dashboard</a>`
+```

package/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/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>
+```

package/ai/charts.md

@@ -0,0 +1,93 @@
+# Schmancy Charts
+
+> Canvas-rendered area chart and horizontal pill chart. Theme-aware, lazy-animated, with auto peak highlighting.
+
+## schmancy-area-chart
+
+> Smooth Catmull-Rom spline area chart with peak markers and hover tooltips.
+
+```html
+<schmancy-area-chart
+  .data=${[
+    { label: '9 AM', value: 12.4 },
+    { label: '10 AM', value: 18.9 },
+    { label: '11 AM', value: 42.1, metadata: { users: 320 } },
+    { label: '12 PM', value: 56.7 },
+  ]}
+  value-prefix="EUR "
+  value-decimals="2"
+  peak-count="2"
+  height="240"
+></schmancy-area-chart>
+```
+
+### Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `ChartDataPoint[]` | `[]` | `{ label, value, metadata? }[]` |
+| `height` | number | `200` | Chart height in px |
+| `showGrid` | boolean | `true` | Background grid lines |
+| `showLabels` | boolean | `true` | X-axis labels |
+| `showTooltip` | boolean | `true` | Hover tooltip |
+| `peakCount` | number | `3` | Top-N points highlighted larger |
+| `animationDuration` | number | `800` | Entrance animation ms |
+| `animated` | boolean | `true` | Animate on first visible |
+| `valuePrefix` | string | `''` | Display prefix (e.g. `"EUR "`) |
+| `valueSuffix` | string | `''` | Display suffix (e.g. `"%"`) |
+| `valueDecimals` | number | `2` | Decimal places |
+| `theme` | `Partial<ChartTheme>` | `{}` | Override colors, stroke, radii |
+
+### ChartTheme
+| Key | Default | Description |
+|-----|---------|-------------|
+| `primaryColor` | `--schmancy-sys-color-primary` | Line + fill gradient color |
+| `gradientOpacity` | `[0.4, 0.05]` | Top/bottom fill opacity |
+| `strokeWidth` | `2` | Line thickness |
+| `pointRadius` | `4` | Normal point radius |
+| `peakRadius` | `6` | Peak point radius |
+
+## schmancy-pills
+
+> Horizontal bar chart with optional stacked segments, medal ranks, and peak/low styling.
+
+```html
+<schmancy-pills
+  .data=${[
+    { label: 'Mon', value: 1240, rank: 1 },
+    { label: 'Tue', value: 980 },
+    { label: 'Wed', value: 1830, rank: 2, segments: [
+      { label: 'Pizza', value: 1200 },
+      { label: 'Drinks', value: 630 }
+    ]},
+  ]}
+></schmancy-pills>
+```
+
+### Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `PillDataPoint[]` | `[]` | Rows with optional stacked `segments` |
+| `valuePrefix` / `valueSuffix` / `valueDecimals` | — | — | Value formatting (same as area chart) |
+| `showMedals` | boolean | `true` | Show 🥇🥈🥉 for rank 1/2/3 |
+
+### PillDataPoint
+```typescript
+{
+  label: string
+  value: number
+  segments?: { label, value, color }[]  // stacked
+  isPeak?: boolean   // highlighted
+  isLow?: boolean    // muted
+  rank?: 1 | 2 | 3   // medal
+  metadata?: Record<string, unknown>
+}
+```
+
+## Behavior
+- Both charts use an IntersectionObserver to defer animation until visible.
+- Responsive — resize triggers a re-render.
+- Dark/light aware via theme CSS variables.
+
+## When to Use
+- Area chart: time-series or comparative trends.
+- Pills: ranked categorical data (leaderboards, top days, distribution).

package/ai/connectivity.md

@@ -0,0 +1,36 @@
+# schmancy-connectivity-status
+
+> App-wide online/offline banner. Mount once near the root and forget it.
+
+## Usage
+```html
+<!-- In your app shell -->
+<schmancy-connectivity-status></schmancy-connectivity-status>
+```
+
+## Properties
+None — it's entirely self-driven from `window` online/offline events.
+
+## Behavior
+- Listens to `window` `online` / `offline` events via RxJS `merge`.
+- `distinctUntilChanged` prevents duplicate banners.
+- Animated slide-down banner with spring-style easing when state changes.
+- Offline: error-colored banner with pulsing icon.
+- Online (after offline): success-colored banner with bouncing icon, auto-dismisses after a short timer.
+- Plays matching sounds from the `$sounds` audio service (skipped on initial load).
+- Respects `prefers-reduced-motion` implicitly via CSS.
+
+## Setup
+Place it once at the root — typically just inside your main `schmancy-theme` or app shell:
+
+```html
+<schmancy-theme>
+  <schmancy-connectivity-status></schmancy-connectivity-status>
+  <schmancy-page>
+    <!-- rest of app -->
+  </schmancy-page>
+</schmancy-theme>
+```
+
+## See Also
+- [audio.md](./audio.md) — the `$sounds` service used for feedback tones.

package/ai/date-range-inline.md

@@ -0,0 +1,44 @@
+# schmancy-date-range-inline
+
+> Smart inline from/to date picker with validation, auto-correction, and gap constraints. Simpler surface than the full `schmancy-date-range` popover.
+
+## Usage
+```html
+<schmancy-date-range-inline
+  .dateFrom=${{ label: 'Check-in', value: '2026-05-01' }}
+  .dateTo=${{ label: 'Check-out', value: '2026-05-05' }}
+  min-date="2026-01-01"
+  max-date="2026-12-31"
+  .minGap=${1}
+  .maxGap=${30}
+  @change=${e => this.handleRange(e.detail)}
+></schmancy-date-range-inline>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `'date' \| 'datetime-local'` | `'date'` | Underlying input type |
+| `dateFrom` | `{ label, value }` | `{ label: 'From', value: '' }` | From-date configuration |
+| `dateTo` | `{ label, value }` | `{ label: 'To', value: '' }` | To-date configuration |
+| `minDate` | string | — | Minimum selectable date (ISO string) |
+| `maxDate` | string | — | Maximum selectable date (ISO string) |
+| `compact` | boolean | `false` | Tighter UI spacing |
+| `autoCorrect` | boolean | `true` | Auto-fix invalid ranges (e.g. swap if from > to) |
+| `minGap` | number | `0` | Minimum days between from and to |
+| `maxGap` | number | — | Maximum days between from and to |
+| `defaultGap` | number | `1` | Default gap when seeding the second date |
+| `allowSameDate` | boolean | `false` | Permit from === to |
+
+## Events
+| Event | Detail | When |
+|-------|--------|------|
+| `change` | `{ dateFrom, dateTo, isValid }` | Either input changes |
+
+## Behavior
+- Extends `SchmancyFormField()` — integrates with `schmancy-form` validation.
+- Auto-correction: invalid ranges flip, or the second date shifts to respect `minGap`/`maxGap`.
+- Inline (not a popover) — always visible, good for filters and trip-planning UIs.
+
+## Prefer full picker
+For a popup calendar with presets and visual selection, use [`schmancy-date-range`](./date-range.md).

package/ai/delay.md

@@ -0,0 +1,50 @@
+# schmancy-delay
+
+> Defers rendering of children by a duration, with an entrance motion. Siblings auto-stagger without manual delay math.
+
+## Usage
+```html
+<schmancy-delay delay="200">
+  <h1>Appears after 200ms</h1>
+</schmancy-delay>
+
+<!-- Auto-staggered list: each child inherits + stacks its own delay -->
+<schmancy-delay delay="100">
+  <schmancy-delay delay="100"><div>Step 1</div></schmancy-delay>
+  <schmancy-delay delay="100"><div>Step 2</div></schmancy-delay>
+  <schmancy-delay delay="100"><div>Step 3</div></schmancy-delay>
+</schmancy-delay>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `delay` | number | `0` | Ms to wait before rendering this node |
+| `motion` | `'flyBelow' \| 'flyAbove' \| 'fadeIn'` | `'flyBelow'` | `@lit-labs/motion` entrance animation |
+| `once` | boolean | `true` | Skip delay on subsequent renders within the same session (keyed on content hash) |
+
+## Context
+- Consumes parent `delayContext` and adds its own delay.
+- Walks previous siblings that are also `schmancy-delay` and accumulates their delays.
+- Provides the resulting `effectiveDelay` down to descendants via context.
+
+Result: nested `schmancy-delay` nodes produce natural staggered entrances without manual math.
+
+## Session Caching
+- When `once=true`, the content is hashed on first render and cached in `sessionStorage`.
+- On subsequent component mounts (route revisits), the delay is skipped — content appears instantly.
+- Set `once=false` to always replay the delay.
+
+## Example — hero reveal
+```html
+<schmancy-delay delay="0" motion="fadeIn">
+  <schmancy-delay delay="300"><h1>Welcome</h1></schmancy-delay>
+  <schmancy-delay delay="200"><p>Subtitle…</p></schmancy-delay>
+  <schmancy-delay delay="200">
+    <schmancy-button variant="filled">Get started</schmancy-button>
+  </schmancy-delay>
+</schmancy-delay>
+```
+
+## See Also
+- Use [`gravity`](./directives.md#gravity--elements-fall-into-place-with-mass-based-bounce) directive for mass-based staggered reveal on lists — often simpler than nested `schmancy-delay`.

package/ai/discovery.md

@@ -0,0 +1,67 @@
+# Schmancy Discovery
+
+> Event-based component and element discovery across shadow DOM boundaries. No DOM traversal — just broadcast and race.
+
+## Why
+Web components hide inside shadow DOM. Traversing with `querySelector` + `shadowRoot` everywhere is fragile. Discovery broadcasts a "where are you?" event; components respond with themselves.
+
+## API
+```typescript
+import {
+  discover,
+  discoverComponent,
+  discoverAnyComponent,
+  discoverElement,
+  discoverAllElements,
+} from '@mhmo91/schmancy'
+```
+
+### `discover(query, timeout?)`
+Smart auto-detect. Routes to `discoverElement` for CSS selectors (`#`, `.`, `[`) and `discoverComponent` for tag names.
+```typescript
+discover<SchmancyNavigationRail>('schmancy-navigation-rail').subscribe(el => el?.select('home'))
+discover('#hero-card').subscribe(el => el?.focus())
+```
+
+### `discoverComponent(tag, timeout = 100)`
+Broadcasts `{tag}-where-are-you`; first responder wins.
+```typescript
+discoverComponent<SchmancyDialog>('schmancy-dialog')
+  .subscribe(dialog => dialog?.open())
+```
+
+### `discoverAnyComponent(...tags)`
+Race between multiple tags — first to respond wins.
+```typescript
+discoverAnyComponent('schmancy-navigation-rail', 'schmancy-navigation-bar')
+  .subscribe(nav => nav?.select(route))
+```
+
+### `discoverElement(selector, timeout = 150)`
+Finds any element by CSS selector across shadow DOM. Uses a request ID + universal `schmancy-discover` event. Every `$LitElement` responds if it finds a match in its shadow root.
+```typescript
+discoverElement('[data-section="pricing"]').subscribe(section => section?.scrollIntoView())
+```
+
+### `discoverAllElements(selector, timeout = 150)`
+Collects **all** matching responses within the timeout window.
+```typescript
+discoverAllElements('.flagged').subscribe(all => console.log(all.length))
+```
+
+## How the Handshake Works
+1. Caller creates a unique `requestId` and broadcasts `schmancy-discover` on `window` with `{ selector, requestId }`.
+2. Every `$LitElement` listens for this event (wired up in the base class).
+3. Any matching element dispatches `schmancy-discover-response` with `{ requestId, element }`.
+4. Caller collects responses for the timeout window and emits via RxJS.
+
+## Pattern in Base Class
+Every `$LitElement` inherits auto-response: `discover<T>(tag)` (method on the component) and `{tagName}-where-are-you`/`{tagName}-here-i-am` events. See [mixins.md](./mixins.md).
+
+## When to Use
+- Cross-shadow coordination between unrelated components.
+- Imperatively focusing or driving a far-away UI piece from a handler.
+
+## When NOT to Use
+- Same-tree data flow — use `@provide`/`@consume` (Lit context) or Schmancy [`store`](./store.md).
+- Parent-to-child directly — just use `this.renderRoot.querySelector()`.