@mhmo91/schmancy 0.9.2 → 0.9.3

package/dist/ai/option.md

@@ -0,0 +1,43 @@
+# schmancy-option
+
+> Selectable item for `schmancy-select`, `schmancy-autocomplete`, and `schmancy-menu`. Lightweight and a11y-ready.
+
+## Usage
+```html
+<schmancy-select label="Country">
+  <schmancy-option value="us">United States</schmancy-option>
+  <schmancy-option value="de">Germany</schmancy-option>
+  <schmancy-option value="jp" disabled>Japan</schmancy-option>
+</schmancy-select>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | string | `''` | Value reported when this option is selected |
+| `label` | string | auto | Display label (falls back to text content) |
+| `selected` | boolean | `false` | Reflects selected state |
+| `disabled` | boolean | `false` | Disables interaction |
+| `group` | string | `''` | Grouping identifier for grouped lists |
+| `icon` | string | `''` | Material icon name before the label |
+
+## Events
+| Event | Payload | When |
+|-------|---------|------|
+| `click` | — | Standard click event |
+| `option-select` | `CustomEvent<{ value, label }>` | Dispatched on activation |
+
+## Behavior
+- Auto-generates `id` for ARIA wiring if not set.
+- Infers `label` from text content when omitted.
+- Keyboard focusable with a visible focus ring via `:focus-visible`.
+- Parent select/autocomplete coordinates selection state via slot query.
+
+## Example — grouped options
+```html
+<schmancy-select label="Framework">
+  <schmancy-option value="lit" group="web" icon="bolt">Lit</schmancy-option>
+  <schmancy-option value="react" group="web">React</schmancy-option>
+  <schmancy-option value="swift" group="mobile">Swift</schmancy-option>
+</schmancy-select>
+```

package/dist/ai/page.md

@@ -0,0 +1,42 @@
+# schmancy-page
+
+> Native mobile-like page container. Fills remaining viewport height, prevents rubber-banding, pull-to-refresh, and double-tap zoom.
+
+## Usage
+```html
+<schmancy-page rows="auto_1fr_auto">
+  <header>App bar</header>
+  <main>Scrollable content</main>
+  <footer>Bottom nav</footer>
+</schmancy-page>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `rows` | string | `'auto_1fr_auto'` | Grid template rows — underscores become spaces (e.g. `'1fr_2fr_auto'`) |
+| `show-scrollbar` | boolean | `false` | Display scrollbar on scrollable area |
+| `no-select` | boolean | `false` | Disable text selection |
+
+## Behavior
+- Listens to `visualViewport` resize/scroll + `orientationchange` + keyboard focus events to recompute height.
+- Accounts for theme bottom offset (iOS safe area, home indicator).
+- Auto-assigns semantic elements (`header`, `main`, `footer`) to slots.
+- Inner scroll area uses `schmancy-scroll` for momentum-preserving scroll.
+
+## When to Use
+- Root of a mobile view or panel that should feel like a native page.
+- Any container where viewport-aware height + scroll containment matters.
+
+## Example — 3-row app shell
+```html
+<schmancy-page rows="auto_1fr_auto">
+  <schmancy-surface type="solid" rounded="none">
+    <schmancy-typography type="title">My App</schmancy-typography>
+  </schmancy-surface>
+
+  <div class="p-4">…scrollable content…</div>
+
+  <schmancy-navigation-bar></schmancy-navigation-bar>
+</schmancy-page>
+```

package/dist/ai/qr-scanner.md

@@ -0,0 +1,51 @@
+# schmancy-qr-scanner
+
+> Camera-based QR code scanner using `jsQR`. Requests rear-camera access, decodes frames in real time, deduplicates reads.
+
+## Usage
+```html
+<schmancy-qr-scanner
+  continuous
+  @scan-result=${e => this.handleScan(e.detail.data)}
+></schmancy-qr-scanner>
+```
+
+```typescript
+handleScan(data: string) {
+  console.log('QR decoded:', data)
+}
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `continuous` | boolean | `true` | Keep scanning after a successful read (dedupe repeated reads) |
+
+## Events
+| Event | Detail | When |
+|-------|--------|------|
+| `scan-result` | `{ data: string, timestamp: number }` | QR code successfully decoded |
+
+## Behavior
+- Requests `getUserMedia` with `facingMode: 'environment'` (rear camera) at 1280×720.
+- Decodes via `jsQR` on `animationFrames` stream with `throttleTime` to avoid CPU thrashing.
+- `distinctUntilChanged` prevents duplicate emissions for the same code.
+- Brief success flash on each valid read.
+- Stops camera + tears down subscriptions on disconnect.
+- Displays an error state if camera permission is denied.
+
+## Requires
+- HTTPS (or `localhost`) for camera access.
+- User permission to the camera.
+
+## Example
+```html
+<schmancy-surface type="glass" rounded="all">
+  <schmancy-qr-scanner
+    @scan-result=${(e: CustomEvent<{ data: string }>) => {
+      $notify.success(`Scanned: ${e.detail.data}`)
+      this.scannedCode = e.detail.data
+    }}
+  ></schmancy-qr-scanner>
+</schmancy-surface>
+```

package/dist/ai/range.md

@@ -0,0 +1,47 @@
+# schmancy-range
+
+> Numeric slider input with theme-driven track gradient and focus halo.
+
+## Usage
+```html
+<schmancy-range
+  label="Volume"
+  min="0"
+  max="100"
+  step="1"
+  .value=${50}
+  @change=${e => this.volume = e.detail.value}
+></schmancy-range>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `min` | number | `0` | Minimum value |
+| `max` | number | `1` | Maximum value |
+| `step` | number | `0.01` | Increment per tick |
+| `value` | number | `0` | Current value |
+| `label` | string | — | Optional label (current value displays on the right) |
+| `disabled` | boolean | `false` | Disabled state (38% opacity) |
+
+## Events
+| Event | Payload | When |
+|-------|---------|------|
+| `change` | `{ value: number }` | On input change |
+
+## Visual
+- Primary-colored track gradient (filled portion = primary, empty = 30% primary).
+- Circular thumb with hover halo (8px primary glow at 12% opacity).
+- Disabled state: 38% opacity, not-allowed cursor.
+
+## Example — precise float control
+```html
+<schmancy-range
+  label="Mass"
+  min="0.5"
+  max="2.0"
+  step="0.05"
+  .value=${this.mass}
+  @change=${(e: CustomEvent<{ value: number }>) => this.mass = e.detail.value}
+></schmancy-range>
+```

package/dist/ai/rxjs-utils.md

@@ -0,0 +1,60 @@
+# Schmancy RxJS Utils
+
+> RxJS-wrapped DOM observation helpers. Use when you need to react to elements appearing, disappearing, or changing across the document.
+
+## Imports
+```typescript
+import {
+  mutationObserver,
+  waitForElement,
+  waitForElementAll,
+  waitForElements,
+  waitForElementsAll,
+  waitUntil,
+} from '@mhmo91/schmancy'
+```
+
+## `mutationObserver(target, options?)`
+RxJS wrapper around `MutationObserver`.
+```typescript
+mutationObserver(document.body, { childList: true, subtree: true })
+  .pipe(takeUntil(this.disconnecting))
+  .subscribe(mutations => { /* react */ })
+```
+
+## `waitForElement(selector, timeout = 5000)`
+Emits the first matching element once it exists in the DOM. Throws on timeout. Pass `undefined` to wait forever.
+```typescript
+waitForElement('#auth-banner').subscribe(el => el.focus())
+waitForElement('.lazy-panel', 10000).subscribe(el => el.click())
+```
+
+## `waitForElementAll(selector, timeout?)`
+Emits whenever the matching set changes (all current matches).
+```typescript
+waitForElementAll('.live-tile').subscribe(tiles => {
+  tiles.forEach(t => observe(t))
+})
+```
+
+## `waitForElements([sel1, sel2, ...], timeout?)` / `waitForElementsAll`
+Multi-selector variants — resolve once *any*/`every` selector is present.
+
+## `waitUntil([selectors], timeout = 5000)`
+Emits once when **all** selectors have matches. Throws on timeout.
+```typescript
+waitUntil(['header', 'main', 'footer'])
+  .subscribe(() => console.log('Page shell ready'))
+```
+
+## How It Works
+All helpers share `mutationObserver(document.body)` with `childList: true, subtree: true` and `.startWith(document.body)` so they check once immediately and re-check on every DOM mutation.
+
+## When to Use
+- Integrating third-party scripts that inject DOM late.
+- Coordinating with slot-projected children that may mount asynchronously.
+- Awaiting app-shell elements before attaching shortcuts.
+
+## When NOT to Use
+- Inside your own component — use `firstUpdated()` or `queryAssignedElements`.
+- For cross-shadow discovery — use [discovery](./discovery.md) instead.

package/dist/ai/slider.md

@@ -0,0 +1,43 @@
+# schmancy-slider / schmancy-slide
+
+> Horizontal snap-scrolling carousel with optional arrow controls.
+
+## Usage
+```html
+<schmancy-slider show-arrows>
+  <schmancy-slide>
+    <img src="a.jpg" />
+  </schmancy-slide>
+  <schmancy-slide>
+    <div class="p-8">Second slide</div>
+  </schmancy-slide>
+  <schmancy-slide>
+    <div class="p-8">Third slide</div>
+  </schmancy-slide>
+</schmancy-slider>
+```
+
+## schmancy-slider Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `showArrows` | boolean | `true` | Render prev/next navigation buttons |
+
+## Events
+| Event | Payload | When |
+|-------|---------|------|
+| `slide-changed` | `{ index: number }` | Centered slide changes after scroll settles |
+
+## Behavior
+- Each `schmancy-slide` is sized to `flex: 0 0 100%` of the slider.
+- `scroll-snap-type: x mandatory` — scroll always lands on a slide.
+- Scrollbars hidden across browsers.
+- Scroll events throttled to 100ms for stable index tracking.
+- Arrow buttons scroll to previous/next slide when `show-arrows` is true.
+
+## Example — programmatic control
+```typescript
+const slider = this.renderRoot.querySelector('schmancy-slider')
+slider?.addEventListener('slide-changed', (e: CustomEvent<{ index: number }>) => {
+  this.activeIndex = e.detail.index
+})
+```

package/dist/ai/store.md

@@ -1,83 +1,192 @@
-# Schmancy Store (Context System)
+# Store — State Foundation
 
-> Reactive state management with `createContext`, `@select` decorator, and persistent storage.
+> **Not a utility. The state backbone of a Schmancy app.**
+> `createContext` + `@select` replaces Redux, Zustand, and a route-scoped cache without ceremony.
+
+A real app runs *many* small contexts — not one monolith. Typical production apps sit around 8–10:
+
+```
+userContext          ('local')      — signed-in user (persists across sessions)
+organizationContext  ('local')      — current org
+appStateContext      ('local')      — core app state (lists, selections, flags)
+agentsContext        ('memory')     — fetched data (re-fetched on reload)
+contactsContext      ('memory')     — Map<id, Contact> — mass data
+templatesContext     ('memory')     — list fetched from server
+currentTemplateIdCtx ('local')      — small pointer ref that persists
+composeContext       ('local')      — draft form state
+draftCtx             ('session')    — per-thread chat input (tab-scoped)
+strictCtx            ('session')    — per-thread toggles (tab-scoped)
+```
+
+**Split by persistence tier + lifetime**, not by feature area. Per-component ephemeral state → `session`. Cached fetches → `memory`. User-saved preferences → `local`. Large cached data → `indexeddb`.
+
+## Creating a context
 
-## Creating a Context
 ```typescript
 import { createContext } from '@mhmo91/schmancy'
 
-// Object store
-const userContext = createContext({ name: '', email: '' }, 'local', 'user')
+// Object store — persisted to localStorage
+export const userContext = createContext<User>(new User(), 'local', 'user')
 
-// Collection store (Map-based)
-const itemsContext = createContext(new Map<string, Item>(), 'indexeddb', 'items')
+// Collection store — Map keyed by id
+export const contactsContext = createContext<Map<string, Contact>>(new Map(), 'memory', 'contacts')
 
-// Array store
-const tagsContext = createContext<string>([], 'memory', 'tags')
+// Array store — ordered list
+export const tagsContext = createContext<string[]>([], 'memory', 'tags')
+
+// Session-scoped (per browser tab)
+export const draftContext = createContext<{ text: string }>({ text: '' }, 'session', 'compose-draft')
 ```
 
-## Storage Types
-| Type | Description |
-|------|-------------|
-| `'memory'` | In-memory only (lost on refresh) |
-| `'local'` | localStorage (persistent) |
-| `'session'` | sessionStorage (per tab) |
-| `'indexeddb'` | IndexedDB (large data, persistent) |
+### Storage tiers
+
+| Mode | Backing | Survives refresh? | Survives tab close? | Size |
+|------|---------|-------------------|---------------------|------|
+| `'memory'` | JS heap | ❌ | ❌ | small |
+| `'session'` | `sessionStorage` | ✅ | ❌ (per-tab) | ~5 MB |
+| `'local'` | `localStorage` | ✅ | ✅ | ~5 MB |
+| `'indexeddb'` | IndexedDB | ✅ | ✅ | GB |
+
+Rule of thumb:
+- **User session data, prefs, drafts meant to persist** → `'local'`
+- **Per-tab ephemeral data** (wizard progress, per-thread drafts) → `'session'`
+- **Fetched from API, regenerable** → `'memory'`
+- **Large arrays, file-like data, offline-first** → `'indexeddb'`
+
+## Reading with `@select`
 
-## Reading State with @select
 ```typescript
 import { select } from '@mhmo91/schmancy'
 
-@customElement('my-component')
-class MyComponent extends $LitElement() {
-  // Auto-subscribes to context changes, triggers re-render
-  @select(userContext)
-  user!: { name: string; email: string }
+@customElement('user-card')
+class UserCard extends $LitElement() {
+  // Auto-subscribes, re-renders on change
+  @select(userContext) user!: User
 
-  // With selector function
-  @select(itemsContext, (items) => items.size)
-  itemCount!: number
+  // Selector function narrows the dependency
+  @select(contactsContext, m => m.size) contactCount!: number
 
-  // Collection as Map
-  @select(itemsContext)
-  items!: Map<string, Item>
+  // Collection → stays as Map
+  @select(contactsContext) contacts!: Map<string, Contact>
 }
 ```
 
-## Writing State
+`@select` options:
+- `required` (default `true`) — wait for context `.ready` before `connectedCallback` completes.
+- `updateOnly` — only call `requestUpdate`, don't assign. Use when you read the value imperatively.
+- `deepClone` — `structuredClone` the value to prevent accidental mutation.
+- `debug` — log every emission.
+
+### Pick one item from a collection
+```typescript
+@selectItem(contactsContext, component => component.contactId)
+contact!: Contact | undefined
+```
+
+Use this on components that carry the key as a property (e.g. `this.contactId`) — avoids reading the whole map.
+
+## Writing state
+
+### Object store
 ```typescript
-// Object store
 userContext.set({ name: 'Alice', email: 'alice@test.com' })
+userContext.set({ ...userContext.value, name: 'Bob' })  // partial update pattern
+```
 
-// Collection store
-itemsContext.set('item-1', { name: 'Widget' })
-itemsContext.delete('item-1')
-itemsContext.replace(new Map([...]))
+### Collection (Map) store
+```typescript
+contactsContext.set('id-1', { id: 'id-1', name: 'Alice' })
+contactsContext.delete('id-1')
+contactsContext.replace(new Map([/* fresh batch */]))
+```
 
-// Array store
+### Array store
+```typescript
 tagsContext.push('new-tag')
 tagsContext.replace(['a', 'b', 'c'])
 ```
 
 ## Observable API
+
 ```typescript
-// Subscribe to changes
-userContext.$.pipe(
-  takeUntil(this.disconnecting)
-).subscribe(user => { ... })
+connectedCallback() {
+  super.connectedCallback()
+
+  userContext.$.pipe(
+    filter(() => userContext.ready),               // gate on initialization
+    distinctUntilChanged((a, b) => a.id === b.id), // ignore unrelated writes
+    switchMap(user => this.loadForUser(user)),     // cascade load
+    takeUntil(this.disconnecting),                 // cleanup
+  ).subscribe(data => this.data = data)
+}
+```
 
-// Current value (synchronous)
-const current = userContext.value
+- **`ctx.$`** — a `BehaviorSubject`. Use for chained transforms.
+- **`ctx.value`** — synchronous snapshot.
+- **`ctx.ready`** — boolean; becomes `true` after the backing store has loaded.
 
-// Ready state
-if (userContext.ready) { ... }
-```
+### The gating pattern
+Every non-trivial subscription starts with `filter(() => ctx.ready)`. When your context is backed by `indexeddb` or re-hydrated from `localStorage`, the initial default value is emitted before the real stored value lands. Gate on `.ready` to skip the default.
 
-## @select Options
-`required` (default true): wait for value before connectedCallback. `updateOnly`: only requestUpdate. `deepClone`: structuredClone. `debug`: log activity.
+## Dynamic contexts (per-instance)
+
+For per-component ephemeral state that still benefits from persistence, instantiate the context **inside** `connectedCallback` with an instance-specific key:
 
-## selectItem (Collection Helper)
 ```typescript
-@selectItem(itemsContext, (component) => component.itemId)
-selectedItem!: Item | undefined
+import { createContext, IStore } from '@mhmo91/schmancy'
+
+@customElement('chat-input')
+class ChatInput extends $LitElement() {
+  @property() draftKey?: string
+
+  private draftCtx: IStore<{ text: string }> | null = null
+
+  connectedCallback() {
+    super.connectedCallback()
+
+    if (this.draftKey) {
+      this.draftCtx = createContext<{ text: string }>(
+        { text: '' },
+        'session',
+        this.draftKey,          // e.g. `chat-draft-${threadId}`
+      )
+
+      // Hydrate once
+      this.draftCtx.$.pipe(
+        filter(() => this.draftCtx!.ready),
+        take(1),
+        tap(v => { this.text = v.text }),
+      ).subscribe()
+    }
+  }
+
+  private onInput(v: string) {
+    this.text = v
+    this.draftCtx?.set({ text: v })
+  }
+}
 ```
+
+This is the pattern for *every* "draft that persists until sent" input.
+
+## Architectural rules
+
+1. **Declare contexts at module scope**, not inside classes — except dynamic per-instance ones.
+2. **Name the storage key** even for `'memory'` contexts — it helps debugging.
+3. **Keep each context small and single-purpose**. 9 small contexts beat 1 god context.
+4. **Subscribe with `takeUntil(this.disconnecting)`** — every time, no exceptions.
+5. **Gate on `.ready`** before any async cascading work.
+6. **Only the owning component writes**. Everyone else reads via `@select`.
+7. **Don't put functions, observables, or class instances into context** — only plain serializable data (for `'local'` / `'session'` / `'indexeddb'`).
+
+## Anti-patterns
+
+- ❌ Storing Promises in context. Use `memory` contexts for cached fetch *results*, not the in-flight Promise.
+- ❌ Cross-writing: component A writes to context X which is "owned" by component B. Centralize writes.
+- ❌ One monolithic `appContext` holding everything. You lose `distinctUntilChanged` granularity.
+- ❌ Forgetting `.ready` — causes double-fires on load with stale default values.
+- ❌ Using `'local'` for large blobs — hits quota, blocks the main thread on stringify/parse.
+
+## See also
+- [mixins](./mixins.md) — `$LitElement` provides `disconnecting` for every subscription.
+- [area](./area.md) — routing + contexts compose naturally (guards read context state).

package/dist/ai/teleport.md

@@ -0,0 +1,55 @@
+# schmancy-teleport
+
+> Move DOM between locations with a FLIP-animated transition. Two instances sharing an `id` handshake via broadcast events — when one mounts, it finds the other and flies the content between them.
+
+## Usage
+```html
+<!-- Start position -->
+<schmancy-teleport id="hero-image">
+  <img src="portrait.jpg" alt="" />
+</schmancy-teleport>
+
+<!-- Later, in a different view -->
+<schmancy-teleport id="hero-image"></schmancy-teleport>
+```
+
+When the second instance mounts, the image smoothly animates from its old bounding rect to the new one.
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `id` | string | **required** | Shared identifier between source and target |
+| `uuid` | number | auto | Instance UUID for disambiguation (read-only) |
+| `delay` | number | `0` | Delay before teleporting (ms) |
+
+## Discovery Events
+The service broadcasts on `window`:
+- `FINDING_MORTIES` — "is anyone mounted with id X?"
+- `HERE_RICKY` — instances reply with self reference
+- `WhereAreYouRicky` / `HereMorty` — instance-to-instance handshake
+
+Uses RxJS with a race/throwIfEmpty pattern to handle missing counterparts gracefully.
+
+## Typical Pattern — route transitions
+```html
+<!-- List view -->
+${repeat(items, item => item.id, item => html`
+  <schmancy-teleport id=${`card-${item.id}`}>
+    <schmancy-card @click=${() => router.push(`/item/${item.id}`)}>
+      <img src=${item.thumbnail} />
+    </schmancy-card>
+  </schmancy-teleport>
+`)}
+
+<!-- Detail view -->
+<schmancy-teleport id=${`card-${this.params.id}`}></schmancy-teleport>
+```
+
+## Notes
+- Uses `watchElementRect` (ResizeObserver + scroll tracking) to keep source/target in sync.
+- Animation uses the FLIP technique: capture first rect, invert on mount, play to final.
+- All subscriptions clean up via `takeUntil(this.disconnecting)`.
+- Each teleport pair must share a unique `id` string.
+
+## See Also
+- For programmatic teleportation from JS: import `teleportationService` from `@mhmo91/schmancy/teleport`.

package/dist/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/dist/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.