@vielzeug/codex 26.10.15 → 26.10.17

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug: Full Documentation
 
-> Complete documentation for 42 packages. Version: 26.10.14
+> Complete documentation for 43 packages. Version: 26.10.16
 
 ---
 
@@ -1296,8 +1296,11 @@ database or schema failures. It never writes, sends email or probes the catalog.
 Operator authority is the session token's optional `roles` claim carrying
 `ARCHIVE_OPERATOR_ROLE` (`'archive-operator'`) — minted by your issuer, verified with
 the same signature, audience and issuer checks as any session, and never a separate
-credential. Moderation routes additionally require a registered publisher row: one
-accountable identity per action.
+credential. Mint operator sessions with a lifetime of at most
+`OPERATOR_SESSION_MAX_AGE_SECONDS` (3600 seconds): the catalog rejects any token
+carrying the operator role whose signed lifetime or age exceeds it, so reusing the
+ordinary long session expiry 401s operator sessions immediately. Moderation routes
+additionally require a registered publisher row: one accountable identity per action.
 
 - **Report** — any registered publisher reports a visible entry with a bounded
   free-text reason (`reportReasonChars`). Idempotent per (entry, reporter): the same
@@ -2669,6 +2672,741 @@ use the flat tree for DOM algorithms; this helper is for test code that needs eq
 
 ---
 
+## @vielzeug/beacon
+
+**Category:** ui-interaction
+
+### Overview
+
+## Why Beacon?
+
+Product tours rot fast: hand-wired step sequences hard-code positioning, persistence, and target waiting into application code, and break the first time the UI moves. Beacon is the headless half of a tour — it owns step order, target waiting, resumable progress, and events — while your markup (or `@vielzeug/refine`'s `ore-tour` components) decides what a step looks like.
+
+```ts
+// Before: step logic tangled with rendering and storage
+let step = Number(localStorage.getItem('tour-step') ?? 0);
+function showStep() {
+  const el = document.querySelector(steps[step].selector);
+  card.style.top = `${el.getBoundingClientRect().bottom + 8}px`; // breaks on scroll
+  card.innerHTML = steps[step].html;
+}
+
+// After: the engine owns order, persistence, and the anchor rect
+import { createTour } from '@vielzeug/beacon';
+
+const tour = createTour({ id: 'welcome', steps, storage });
+tour.current.subscribe(() => renderCard(tour.current.value)); // rect is the live anchor
+tour.start();
+```
+
+| Feature | Beacon | Shepherd.js | Intro.js |
+| --- | --- | --- | --- |
+| Bundle size |  | ~50 kB | ~25 kB |
+| External dependencies |  (none) |  |  |
+| Headless (you own the UI) |  |  |  |
+| Resumable persisted progress |  |  |  |
+| Versioned re-offers |  |  |  |
+| Coachmarks (single hints) |  |  |  |
+
+**Use Beacon when** tours must survive UI changes: steps anchor to your real DOM, progress persists and resumes, and the card markup is yours (or refine's ready-made `ore-tour`).
+
+**Consider Shepherd or Intro.js when** you want a fully-rendered, opinionated tour widget you never style yourself and can accept their DOM and CSS.
+
+## Installation
+
+```sh [pnpm]
+pnpm add @vielzeug/beacon
+```
+
+```sh [npm]
+npm install @vielzeug/beacon
+```
+
+```sh [yarn]
+yarn add @vielzeug/beacon
+```
+
+## Quick Start
+
+Define the tour as data, run it, and render the current step wherever you like. The handle is disposable, so component teardown cleans everything up.
+
+```ts
+import { createTour, type BeaconTourConfig } from '@vielzeug/beacon';
+
+const config = {
+  id: 'getting-started',
+  steps: [
+    { id: 'welcome', title: 'Welcome', description: 'A two-minute look around.' },
+    { id: 'nav', target: '[data-tour="nav"]', title: 'Navigation', placement: 'bottom-start' },
+  ],
+} satisfies BeaconTourConfig;
+
+const tour = createTour(config);
+
+// Render from the live snapshot: rect is the anchor, null centers the card.
+const unsubscribe = tour.current.subscribe(() => {
+  const { presentation, rect, step } = tour.current.value;
+  console.log({ presentation, rect, step }); // drive your card from this
+});
+
+tour.start();
+
+// On teardown:
+unsubscribe();
+tour.dispose();
+```
+
+## Features
+
+- `createTour()` runs a sequential, resumable walkthrough over your own DOM.
+- `createCoachmark()` shows a single contextual hint once per user per version.
+- `current` is a live `Readable` snapshot: step, index, placement, presentation, and resolved anchor rect, kept fresh on scroll, resize, and layout changes.
+- `target` accepts a selector, `Element`, rect, or lazy resolver, and beacon waits for lazily-mounted targets before showing the step.
+- `storage` persists progress through any `BeaconStorage` bridge (localStorage, IndexedDB via `@vielzeug/vault`, a server API).
+- `version` re-offers a finished tour when the product changes underneath it.
+- `tap()` subscribes to lifecycle events (`step:start`, `tour:complete`, `target-missing`, ...) with `AbortSignal` support.
+- `resolveTarget()` turns any target into a viewport rect compatible with `@vielzeug/orbit` positioners.
+- `ore-tour`'s `bind()` in `@vielzeug/refine` renders a handle and routes its actions with zero glue code.
+
+## Documentation
+
+- [Usage Guide](./usage.md)
+- [API Reference](./api.md)
+- [Examples](./examples.md)
+- [Migration Guide](./migration.md)
+
+## See Also
+
+- [Refine](/refine/): ships `ore-tour` and `ore-spotlight`, the ready-made dialog/popover/bottom-sheet presentation layer for a beacon handle.
+- [Orbit](/orbit/): compute exact popover coordinates from `current.rect` when you build a custom presentation.
+- [Vault](/vault/): durable storage backends that plug into `BeaconStorage` with a six-line bridge.
+- [Ripple](/ripple/): the `Readable` signals every beacon handle exposes come from here.
+
+### API Reference
+
+## API Overview
+
+| Symbol | Purpose | Execution mode | Common gotcha |
+| --- | --- | --- | --- |
+| `createTour(config)` | Runs a sequential, resumable walkthrough over the app's DOM | Sync (storage reads may be async) | `start()` is a no-op when the stored record says the tour is completed |
+| `createCoachmark(config)` | Shows a single contextual hint anchored to one target | Sync (storage reads may be async) | `show()` is a no-op after `dismiss()` until `reset()` or a `version` bump |
+| `resolveTarget(target)` | Resolves any target to a viewport-space rect or `null` | Sync | Call it per position update; a scrolled target's rect changes |
+| `BeaconError` | Base class for all beacon-originated errors | — | Catch this to catch any beacon error |
+| `BeaconConfigError` | Invalid tour/coachmark configuration | Thrown at creation | Empty `steps` or duplicate step ids fail at `createTour()` |
+| `BeaconDisposedError` | Handle used after `dispose()` | Thrown on call | `dispose()` is idempotent; later method calls throw |
+
+## Package Entry Point
+
+| Import | Purpose |
+| --- | --- |
+| `@vielzeug/beacon` | Complete public Beacon API |
+
+---
+
+## Core Functions
+
+### createTour
+
+```ts
+function createTour(config: BeaconTourConfig): BeaconTourHandle
+```
+
+Returns a live handle for one guided tour. Throws `BeaconConfigError` when `id` is empty, `steps` is empty, or step ids are duplicated.
+
+Parameters: see [`BeaconTourConfig`](#beacontourconfig).
+
+**Returns:** a [`BeaconTourHandle`](#beacontourhandle) that is also `Disposable`.
+
+**Example:**
+
+```ts
+import { createTour } from '@vielzeug/beacon';
+
+const tour = createTour({
+  id: 'release-tour',
+  steps: [{ id: 'intro', title: 'What changed' }],
+  autoStart: true,
+});
+
+tour.status.subscribe(() => console.log(tour.status.value));
+```
+
+Handle methods:
+
+| Member | Behavior |
+| --- | --- |
+| `start()` | Begin or resume the tour. No-op when completed; throws after dispose. |
+| `next()` | Advance; past the last step, finishes the tour. |
+| `back()` | Return to the previous step. No-op on the first step. |
+| `goto(step)` | Jump to a step by index or id. Unknown values warn and no-op. |
+| `pause()` | Stop showing, keep progress so `start()` resumes it. |
+| `skip()` | End from a "Skip" control. Persisted as dismissed, reported with reason `'skip'`. |
+| `finish()` | Mark finished and stop showing. |
+| `dismiss()` | End by closing (Escape, backdrop). Persisted as dismissed. |
+| `reset()` | Discard persisted progress; the tour is eligible again. |
+| `tap(handler, options?)` | Observe [`BeaconTourEvent`](#beacontourentype)s; returns an unsubscribe, honors `options.signal`. |
+| `dispose()` / `[Symbol.dispose]()` | Release all listeners and observers. Idempotent. |
+Handle properties:
+
+| Member | Type | Notes |
+| --- | --- | --- |
+| `current` | `Readable` | The snapshot to render; `step` is `null` while closed. Beacon re-publishes the rect on scroll, resize, and target layout changes while a step is active. |
+| `status` | `Readable` | Lifecycle, persisted on every change. |
+| `eligible` | `Readable` | Whether the tour should be offered to this user. |
+| `steps` | `readonly BeaconStep[]` | The configured steps, in order. |
+| `id` | `string` | The configured id (also the storage key suffix). |
+| `disposed` | `boolean` | Whether `dispose()` has run. |
+| `disposalSignal` | `AbortSignal` | Aborted on dispose; pass it to your own listeners. |
+
+---
+
+### createCoachmark
+
+```ts
+function createCoachmark(config: BeaconCoachmarkConfig): BeaconCoachmarkHandle
+```
+
+Returns a handle for one contextual hint. Throws `BeaconConfigError` when `id` is empty.
+
+Parameters: see [`BeaconCoachmarkConfig`](#beaconcoachmarkconfig).
+
+**Returns:** a [`BeaconCoachmarkHandle`](#beaconcoachmarkhandle) that is also `Disposable`.
+
+**Example:**
+
+```ts
+import { createCoachmark } from '@vielzeug/beacon';
+
+const hint = createCoachmark({
+  id: 'share-hint',
+  target: '[data-tour="share"]',
+  title: 'Share this board',
+});
+
+hint.show(); // waits for the target to mount if it is not on screen yet
+```
+
+Handle members:
+
+| Member | Behavior |
+| --- | --- |
+| `show()` | Show the hint. No-op once dismissed without a newer version. |
+| `hide()` | Hide without recording it as seen; it can show again. |
+| `dismiss()` | Hide and record as seen permanently (until `reset()`/`version`). |
+| `reset()` | Discard the persisted record; the hint is eligible again. |
+| `tap(handler, options?)` | Observe `coachmark:show`, `coachmark:dismiss`, and common events. |
+| `current` | `Readable` — the hint as a single-step snapshot: `step` is the hint while visible, `null` while hidden. The rect stays live on scroll, resize, and target layout changes. |
+| `eligible` | `Readable` — never seen, or superseded by a newer version. |
+
+---
+
+### resolveTarget
+
+```ts
+function resolveTarget(target: BeaconTarget): BeaconRect | null
+```
+
+Resolves a target to a viewport-space rect, or `null` when it is not available yet. Strings resolve through `document.querySelector`; functions are called and their result normalized.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `target` | `BeaconTarget` | Selector, `Element`, rect, or lazy resolver. |
+
+**Returns:** `BeaconRect | null` — shape-compatible with `getBoundingClientRect()` and `@vielzeug/orbit`'s `Rect`.
+
+**Example:**
+
+```ts
+import { resolveTarget } from '@vielzeug/beacon';
+
+const rect = resolveTarget('[data-tour="share"]');
+// Anchor an orbit positioner from a virtual reference:
+const reference = { getBoundingClientRect: () => resolveTarget('[data-tour="share"]') ?? ZERO_RECT };
+```
+
+---
+
+## Types
+
+### BeaconTourConfig
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | required | Unique identity; used as the storage key. |
+| `steps` | `readonly BeaconStep[]` | required | Every step, in order. At least one. |
+| `autoScroll` | `boolean` | `true` | Scroll each anchored step's target into view when it activates. |
+| `autoStart` | `boolean` | `false` | Start on the next microtask when eligible. |
+| `placement` | `BeaconPlacement` | `'auto'` | Default placement handed to the presentation layer. |
+| `presentation` | `BeaconPresentation` | `'auto'` | Default presentation handed to the presentation layer. |
+| `scrollOffset` | `number \| (() => number)` | `0` | Pixels kept clear at the viewport top for a sticky header, read at scroll time. |
+| `storage` | `BeaconStorage` | memory-only | Progress persistence. |
+| `targetTimeoutMs` | `number` | `Infinity` | How long to wait for a step's target before skipping that step. `0` publishes immediately with a `null` rect. |
+| `version` | `number` | `1` | Bump to re-show a finished tour. |
+
+### BeaconCoachmarkConfig
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | required | Unique identity; used as the storage key. |
+| `target` | `BeaconTarget` | required | Where the hint points. |
+| `autoShow` | `boolean` | `true` | Show automatically when not yet seen. |
+| `data` | `unknown` | — | Free-form data for the presentation layer. |
+| `description` | `string` | — | Supporting copy. |
+| `placement` | `BeaconPlacement` | `'auto'` | Preferred side. |
+| `presentation` | `BeaconPresentation` | `'auto'` | Preferred presentation. |
+| `storage` | `BeaconStorage` | memory-only | Seen-record persistence. |
+| `title` | `string` | — | Headline copy. |
+| `version` | `number` | `1` | Bump to re-show a seen coachmark. |
+
+### BeaconStep
+
+```ts
+interface BeaconStep {
+  readonly data?: unknown;
+  readonly description?: string;
+  readonly id: string;
+  readonly placement?: BeaconPlacement;
+  readonly presentation?: BeaconPresentation;
+  readonly target?: BeaconTarget;
+  readonly title?: string;
+}
+```
+
+One stop in a tour. `id` is stable and persisted — renaming it resets progress for that step. Omit `target` for a centered intro/outro step. `placement`/`presentation` override the tour-level defaults.
+
+### BeaconTarget
+
+```ts
+type BeaconTarget = BeaconTargetResolver | BeaconRect | Element | string;
+```
+
+What a step points at. Selectors and elements anchor to real DOM; rects (or resolvers returning one) anchor to element-less geometry such as a canvas region.
+
+### BeaconTargetResolver
+
+```ts
+type BeaconTargetResolver = () => Element | BeaconRect | null;
+```
+
+Resolves a target lazily; `null` means "not available yet".
+
+### BeaconRect
+
+```ts
+interface BeaconRect {
+  readonly height: number;
+  readonly width: number;
+  readonly x: number;
+  readonly y: number;
+}
+```
+
+A viewport-space rectangle in CSS pixels. Matches `@vielzeug/orbit`'s `Rect` shape.
+
+### BeaconPlacement
+
+```ts
+type BeaconPlacement =
+  | 'auto'
+  | 'bottom' | 'bottom-end' | 'bottom-start'
+  | 'left' | 'left-end' | 'left-start'
+  | 'right' | 'right-end' | 'right-start'
+  | 'top' | 'top-end' | 'top-start';
+```
+
+Preferred side for an anchored presentation; `'auto'` asks the positioning layer to choose.
+
+### BeaconPresentation
+
+```ts
+type BeaconPresentation = 'auto' | 'bottom-sheet' | 'modal' | 'popover';
+```
+
+How a step should be presented. `'auto'` lets the presentation layer pick by available space.
+
+### BeaconStatus
+
+```ts
+type BeaconStatus = 'active' | 'completed' | 'dismissed' | 'idle' | 'paused';
+```
+
+Tour lifecycle, persisted across visits. `'idle'` means never started.
+
+### BeaconProgress
+
+```ts
+interface BeaconProgress {
+  readonly status: BeaconStatus;
+  readonly stepIndex: number;
+  readonly version: number;
+}
+```
+
+The persisted record for one tour or coachmark. `stepIndex` is `-1` before the first step. Records are validated on read; invalid records fall back to a fresh tour.
+
+### BeaconStorage
+
+```ts
+interface BeaconStorage {
+  get(key: string): Promise | BeaconProgress | null | undefined;
+  remove(key: string): Promise | unknown;
+  set(key: string, value: BeaconProgress): Promise | unknown;
+}
+```
+
+Minimal storage contract; sync or async. Values are JSON. Keys arrive namespaced (`@vielzeug/beacon:`). A `@vielzeug/vault` store plugs in with:
+
+```ts
+const storage: BeaconStorage = {
+  get: (key) => store.get('progress', key),
+  remove: (key) => store.delete('progress', key),
+  set: (key, value) => store.put('progress', { id: key, ...value }),
+};
+```
+
+### BeaconCurrentStep
+
+```ts
+interface BeaconCurrentStep {
+  readonly placement: BeaconPlacement;
+  readonly presentation: BeaconPresentation;
+  readonly rect: BeaconRect | null;
+  readonly step: BeaconStep | null;
+  readonly stepIndex: number;
+  readonly totalSteps: number;
+}
+```
+
+The snapshot a presentation layer renders from. `step` is `null` before start and after the tour ends; `rect` is `null` for centered steps and unresolved targets. While a step is active, Beacon keeps `rect` fresh on scroll, resize, and target layout changes — no app-side refresh call is needed.
+
+### BeaconTourEvent
+
+```ts
+type BeaconTourEvent =
+  | { readonly index: number; readonly step: BeaconStep; readonly type: 'step:start' }
+  | { readonly index: number; readonly step: BeaconStep; readonly type: 'step:complete' }
+  | { readonly reason: 'finish' | 'skip'; readonly type: 'tour:complete' }
+  | { readonly type: 'tour:dismiss' }
+  | { readonly status: BeaconStatus; readonly type: 'status-change' }
+  | { readonly message: string; readonly type: 'target-missing' }
+  | { readonly index: number; readonly message: string; readonly step: BeaconStep; readonly type: 'target-waiting' }
+  | { readonly error: unknown; readonly message: string; readonly type: 'warning' }
+  | { readonly type: 'dispose' };
+```
+
+Notable moments a tour reports through `tap()`. `target-missing` means a step was skipped because its target did not appear in time; `target-waiting` fires when a step begins waiting for its target to mount; `warning` carries storage or handler failures.
+
+### BeaconCoachmarkEvent
+
+```ts
+type BeaconCoachmarkEvent =
+  | { readonly type: 'coachmark:show' }
+  | { readonly type: 'coachmark:dismiss' }
+  | { readonly type: 'target-waiting' }
+  | { readonly error: unknown; readonly message: string; readonly type: 'warning' }
+  | { readonly type: 'dispose' };
+```
+
+Notable moments a coachmark reports through `tap()`.
+
+### BeaconTourHandle / BeaconCoachmarkHandle
+
+The objects returned by `createTour()` and `createCoachmark()`, documented in [Core Functions](#core-functions). Both expose `disposalSignal`, `disposed`, `tap()`, `dispose()`, and `[Symbol.dispose]()`.
+
+## Errors
+
+| Error | Triggered by | Notes |
+| --- | --- | --- |
+| `BeaconError` | Base for all beacon errors | `name` is the subclass name; `cause` supported via `ErrorOptions`. |
+| `BeaconConfigError` | Empty `id`, empty `steps`, missing/duplicate step ids | Thrown synchronously from `createTour()`/`createCoachmark()`. |
+| `BeaconDisposedError` | Calling handle methods after `dispose()` | `dispose()` itself never throws. |
+
+### Usage Guide
+
+## Basic Usage
+
+A tour is a config object plus a handle you drive from your own UI. The handle never renders anything: it publishes a `current` snapshot, and your card (or refine's `ore-tour`) renders it.
+
+```ts
+import { createTour } from '@vielzeug/beacon';
+
+const tour = createTour({
+  id: 'product-tour',
+  steps: [
+    { id: 'welcome', title: 'Welcome', description: 'See what changed in this release.' },
+    { id: 'nav', target: '[data-tour="nav"]', title: 'Find everything', placement: 'bottom-start' },
+    { id: 'share', target: '[data-tour="share"]', title: 'Share the board', placement: 'bottom-end' },
+  ],
+  autoStart: true,
+});
+
+// Readable from @vielzeug/ripple: the listener takes no arguments;
+// read .value inside it.
+const unsubscribe = tour.current.subscribe(() => {
+  const current = tour.current.value;
+  if (!current.step) {
+    hideCard();
+    return;
+  }
+  renderCard({
+    anchor: current.rect, // viewport rect of the target, null for centered steps
+    index: current.stepIndex,
+    placement: current.placement,
+    presentation: current.presentation,
+    title: current.step.title,
+    total: current.totalSteps,
+  });
+});
+
+// Wire your card's controls back to the handle.
+cardEl.addEventListener('next', () => tour.next());
+cardEl.addEventListener('back', () => tour.back());
+cardEl.addEventListener('skip', () => tour.skip());
+
+// On teardown:
+unsubscribe();
+tour.dispose();
+```
+
+`start()` is a no-op when the stored record says this user already completed the tour, so calling it on every page load is safe.
+
+## Steps and Targets
+
+A step without a `target` centers (intro/outro copy). A step with one anchors, and beacon waits for the target to exist before publishing the step — a tour can walk through lazily-mounted routes without any coordination code.
+
+```ts
+const tour = createTour({
+  id: 'deep-tour',
+  steps: [
+    // Selector: resolved with document.querySelector on activation.
+    { id: 'sidebar', target: '[data-tour="sidebar"]', title: 'Your libraries' },
+    // Element: a ref your framework already holds.
+    { id: 'editor', target: editorEl, title: 'The editor' },
+    // Rect: geometry with no element, such as a canvas region.
+    { id: 'chart', target: { height: 120, width: 240, x: 400, y: 300 }, title: 'This trend' },
+    // Resolver: computed on every activation, and on scroll/resize while the step is active.
+    { id: 'selection', target: () => window.getSelection()?.getRangeAt(0).getBoundingClientRect() ?? null, title: 'Your selection' },
+  ],
+  // Give up waiting after 4s and skip the step instead of hanging the tour.
+  targetTimeoutMs: 4000,
+});
+```
+
+With the default `targetTimeoutMs: Infinity`, a step whose target never mounts simply waits: the tour resumes the moment the user navigates to it. Set `0` to publish immediately with a `null` rect instead of waiting.
+
+## Persisting Progress
+
+Without `storage`, progress lives in memory for the handle's lifetime only. Any object matching `BeaconStorage` makes it durable — values are JSON, keys are namespaced under `@vielzeug/beacon:`.
+
+```ts
+import type { BeaconStorage } from '@vielzeug/beacon';
+
+const storage: BeaconStorage = {
+  get: (key) => JSON.parse(localStorage.getItem(key) ?? 'null'),
+  remove: (key) => localStorage.removeItem(key),
+  set: (key, value) => localStorage.setItem(key, JSON.stringify(value)),
+};
+
+const tour = createTour({ id: 'product-tour', steps, storage });
+```
+
+Async storage works too: `get` may return a promise, and the tour boots as soon as it resolves. A `set` that rejects is reported through `tap()` as a `warning` event, never thrown.
+
+Records are validated on read, so a hand-edited or stale record falls back to a fresh tour instead of crashing.
+
+### Re-offering a finished tour
+
+Bump `version` when the product changes and every user who finished the old tour becomes eligible again — users mid-tour on the old version keep their progress.
+
+```ts
+const tour = createTour({
+  id: 'product-tour',
+  steps: newSteps,
+  version: 2, // stored records at version 1 no longer block the tour
+});
+```
+
+`reset()` clears the persisted record for the current user, which is what a "Replay tour" or "Reset onboarding" control should call before `start()`.
+
+## Driving a Refine Presentation
+
+`@vielzeug/refine` ships `ore-tour` (a dialog with step footer, progress, and focus handling) and `ore-spotlight` (a decorative cutout that dims everything but the target). A beacon handle satisfies `ore-tour`'s `TourController` shape, so one call wires both directions:
+
+```ts
+import type { OreTourElement } from '@vielzeug/refine/tour';
+
+const card = document.querySelector('#tour-card');
+
+const tour = createTour({ id: 'product-tour', presentation: 'auto', steps });
+
+// bind() renders `current` into the card's props and routes the card's
+// next/back/skip/finish/dismiss actions back into the handle.
+const unbind = card.bind(tour);
+
+tour.start();
+
+// On teardown:
+unbind();
+tour.dispose();
+```
+
+`presentation: 'auto'` maps to a popover on wide viewports and a bottom sheet on narrow ones; ore-tour makes that switch itself and freezes the choice while the card is open, so a mid-step resize never rebuilds the card. Beacon keeps `current.rect` fresh on scroll, resize, and layout changes, so the anchored card follows the layout with no app-side listeners.
+
+Apps that render their own markup read `current` directly instead (see [Basic Usage](#basic-usage)).
+
+## Coachmarks
+
+A coachmark is one hint anchored to one target, shown the first time the target appears and dismissed permanently after. Use it for the "explain this button once" moment a tour would be too heavy for — or as the follow-up a tour hands off to.
+
+```ts
+import { createCoachmark } from '@vielzeug/beacon';
+
+const share = createCoachmark({
+  id: 'share-hint',
+  target: '[data-tour="share"]',
+  title: 'Share this board',
+  description: 'Send a link that opens straight into this view.',
+  storage,
+});
+
+// Render from `current` — the same single-step snapshot a tour publishes.
+share.current.subscribe(() => console.log(share.current.value.step !== null, share.current.value.rect));
+
+// The target may never appear on this page; show() waits for it.
+share.show();
+
+// "Got it" button:
+share.dismiss(); // records it as seen; never shows again for this version
+```
+
+`hide()` closes the hint without recording it, so it can appear again later; `dismiss()` is permanent until `reset()` or a `version` bump.
+
+## Events and Analytics
+
+`tap()` observes everything the engine considers notable. It returns an unsubscribe function and accepts an `AbortSignal`, so one controller can tear down every subscription.
+
+```ts
+const controller = new AbortController();
+
+tour.tap((event) => {
+  switch (event.type) {
+    case 'step:start':
+      analytics.track('tour_step', { id: tour.id, step: event.step.id });
+      break;
+    case 'tour:complete':
+      analytics.track('tour_complete', { id: tour.id, reason: event.reason });
+      break;
+    case 'target-missing':
+      // A step's target never mounted: your selector drifted from the DOM.
+      console.warn(event.message);
+      break;
+    case 'warning':
+      console.warn(event.message, event.error);
+      break;
+  }
+}, { signal: controller.signal });
+```
+
+`target-missing` is the event to alert on: it means a step was skipped because its target did not appear within `targetTimeoutMs`, which is exactly how stale tours announce themselves.
+
+## Testing
+
+Beacon runs without a rendering layer, so plain DOM tests are enough. The default in-memory storage keeps each handle's progress isolated, and `jsdom`'s `getBoundingClientRect()` returns zero-sized rects, which is fine for step-order assertions.
+
+```ts
+import { createTour } from '@vielzeug/beacon';
+import { expect, test } from 'vitest';
+
+test('walks steps in order and completes', () => {
+  const tour = createTour({
+    id: 'test-tour',
+    steps: [{ id: 'a' }, { id: 'b' }],
+    targetTimeoutMs: 0, // publish immediately even without targets
+  });
+
+  tour.start();
+  expect(tour.current.value.step?.id).toBe('a');
+
+  tour.next();
+  expect(tour.current.value.step?.id).toBe('b');
+
+  tour.next(); // past the last step finishes
+  expect(tour.status.value).toBe('completed');
+});
+```
+
+For persistence assertions, pass a `Map`-backed `BeaconStorage` and a second handle with the same `id` to check it resumes where the first stopped.
+
+## Framework Integration
+
+Beacon is framework-neutral: bridge the `Readable` snapshot with whatever primitive your framework already has.
+
+```tsx [React]
+import { useEffect, useState } from 'react';
+import { createTour } from '@vielzeug/beacon';
+
+function useTourState(tour: ReturnType) {
+  const [current, setCurrent] = useState(tour.current.value);
+  useEffect(() => tour.current.subscribe(() => setCurrent(tour.current.value)), [tour]);
+  return current;
+}
+```
+
+```vue [Vue 3]
+
+import { onScopeDispose, shallowRef } from 'vue';
+import { createTour } from '@vielzeug/beacon';
+
+const current = shallowRef(tour.current.value);
+const unsubscribe = tour.current.subscribe(() => (current.value = tour.current.value));
+onScopeDispose(unsubscribe);
+
+```
+
+```svelte [Svelte]
+
+  import { onDestroy } from 'svelte';
+  import { readable } from 'svelte/store';
+
+  const current = readable(tour.current.value, (set) => {
+    set(tour.current.value);
+    return tour.current.subscribe(() => set(tour.current.value));
+  });
+  onDestroy(() => tour.dispose());
+
+```
+
+## Working with Other Vielzeug Libraries
+
+- **Refine**: `ore-tour` and `ore-spotlight` are the intended presentation layer; see [Driving a Refine Presentation](#driving-a-refine-presentation).
+- **Orbit**: `current.rect` matches orbit's `Rect` shape, so a custom card positions with `computePosition({ getBoundingClientRect: () => current.rect ?? ZERO_RECT }, floatingEl, middleware)`.
+- **Vault**: any vault store becomes a `BeaconStorage` with a six-line bridge (see the `BeaconStorage` docs in [API Reference](./api.md)).
+- **Ripple**: every handle exposes ripple `Readable`s; `createRipple().isBatchingObservable` semantics apply when you subscribe from effects.
+
+## Best Practices
+
+- Give every tour and coachmark a stable `id` — it is the storage key; treat renames as data migrations.
+- Keep tour configs in their own modules as plain data checked with `satisfies BeaconTourConfig`, so steps stay reviewable data, not component code.
+- Prefer `data-tour="..."` attributes as target selectors: they survive class renames and read as intent.
+- Set a finite `targetTimeoutMs` in production and alert on `target-missing` to catch stale selectors.
+- Call `reset()` before `start()` for replay controls; never delete storage keys by hand.
+- Bump `version` when a tour's meaning changes, not when its copy is typo-fixed.
+- Dispose handles on teardown; `tap()` subscriptions with a shared `AbortSignal` clean up in one call.
+
+### Examples
+
+## Examples
+
+- [Getting Started](./examples/getting-started.md)
+
+### REPL Examples
+
+- Coachmark - Show Once, Dismiss, Reset (id: `coachmark`)
+- Persist Progress - Resume, Finish, Replay (id: `persist-progress`)
+- Tour Basics - Steps, Rects, Completion (id: `tour-basics`)
+
+---
+
 ## @vielzeug/clockwork
 
 **Category:** state
@@ -20917,7 +21655,7 @@ Component registration happens through side-effect imports such as `@vielzeug/re
 
 **Layout:** `ore-box`, `ore-grid`, `ore-grid-item`, `ore-navbar`, `ore-sidebar`
 
-**Overlay:** `ore-command-palette`, `ore-command-palette-item`, `ore-dialog`, `ore-drawer`, `ore-menu`, `ore-popover`, `ore-tooltip`
+**Overlay:** `ore-command-palette`, `ore-command-palette-item`, `ore-dialog`, `ore-drawer`, `ore-menu`, `ore-popover`, `ore-spotlight`, `ore-tooltip`, `ore-tour`
 
 ## Component portfolio