---

## GuideBeacon
**Stability:** beta — the API shape is settled and documented; behaviour-level fixes may still land as breaking changes in a minor.
A waiting, pulsing hotspot that invites the user into an opt-in guided tour
— the gentlest tour entry point, the opposite of an auto-starting tour. A real `<button>` the
consumer positions (inline, or absolutely over a feature corner); on activation it starts the
given `tour` and/or calls `onActivate`. Hides itself once that tour has been seen. The pulse
halts under `prefers-reduced-motion` (static dot). Renders inert without a `GuideProvider`.

**Import:** `import { GuideBeacon } from '@urbicon-ui/blocks';`

### Examples
```svelte
<span class="relative">
  New feature
  <GuideBeacon class="absolute -right-3 -top-1" {tour} />
</span>
```

### Variants
- size: md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLButtonAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'class' | 'children') |
| class | `string` | no |  | Additional classes on the beacon button (use for absolute positioning over a target). In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| label | `string` | no | i18n `guide.startTour` | Accessible label for the button. An `aria-label` is used when this is unset. |
| onActivate | `() => void` | no |  | Called on activation (click / Enter / Space), after `tour` is started when both are set. |
| once | `boolean` | no | true | Hide the beacon once its `tour` has been seen (and while that tour is running). Needs `tour`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideBeacon: {...} }}>`. |
| size | `GuideBeaconVariants['size']` | no | 'md' | Visual size of the hotspot. |
| slotClasses | `Partial<Record<GuideBeaconSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| tour | `GuideTour` | no |  | The tour to start when the beacon is activated. When set, the beacon also hides itself once the tour has been seen (subject to `once`). Omit to drive everything from `onActivate`. |
| unstyled | `boolean` | no | false | Strip all default styles. |

Inherited from:
- Omit<HTMLButtonAttributes, 'class' | 'children'> (omit-pattern)

### Types
```ts
class GuideController {
  constructor(options: GuideControllerOptions = {});
  registerTarget(id: string, element: HTMLElement, meta: GuideTopicMeta = {}): () => void;
  unregisterTarget(id: string, element: HTMLElement): void;
  target(id: string, meta?: GuideTopicMeta): Attachment;
  resolveTarget(id: string): HTMLElement | null;
  getTopicMeta(id: string): GuideTopicMeta | undefined;
  resolveDirection(id: string, override?: GuideDirection): GuideDirection;
  get activeTour(): GuideTour | null;
  get isTourActive(): boolean;
  get stepIndex(): number;
  get currentStep(): GuideStep | null;
  get stepCount(): number;
  get isFirstStep(): boolean;
  get isLastStep(): boolean;
  get paused(): boolean;
  get overlayDepth(): number;
  startTour(tour: GuideTour): boolean;
  next(): void;
  prev(): void;
  skip(): void;
  finish(): void;
  stopTour(): void;
  reapplyStepHighlight(): void;
  get highlightedId(): string | null;
  highlight(id: string, options?: { scroll?: boolean }): void;
  clearHighlight(): void;
  get panelOpen(): boolean;
  get activeArticle(): string | null;
  openPanel(article?: string): void;
  closePanel(): void;
  setArticle(article: string | null): void;
  get panelId(): string | null;
  registerPanel(id: string): () => void;
  hasSeen(id: string): boolean;
  markSeen(id: string): void;
  resetSeen(id?: string): void;
  get seenIds(): string[];
}
```

```ts
type GuideDirection = 'to-guide' | 'to-ui' | 'both'
```

```ts
interface GuideStorageAdapter {
/**
   * Returns the persisted set of seen/completed ids. Return a `string[]`
   * synchronously (localStorage, the default) or a `Promise<string[]>` for a
   * DB-/remote-backed store. While an async load is pending the seen set starts
   * empty and is merged (union) with the resolved ids once they arrive — so a
   * tour may briefly be startable before the store answers.
   */
  load(): string[] | Promise<string[]>;
  /** Persists the full set of seen/completed ids. */
  save(ids: string[]): void;
}
```

```ts
interface GuideTour {
/** Unique id — used for "seen" persistence. */
  id: string;
  /** Ordered steps. */
  steps: GuideStep[];
  /** Skip automatically once completed/dismissed. @default true */
  once?: boolean;
  /**
   * Fired when a step becomes active — once on `startTour` (`via: 'start'`) and again on
   * every `next`/`prev`. This is where most onboarding analytics live (the step-by-step
   * funnel). A throw here is swallowed (DEV-warned) so analytics can't corrupt tour state.
   */
  onStep?: (event: GuideStepEvent) => void;
  /** Fired when the tour is completed — via `finish()`, or `next()` on the last step. */
  onComplete?: (event: GuideEndEvent) => void;
  /**
   * Fired when the tour is dismissed before completing — via `skip()`, Escape, or a foreign
   * overlay closing it. `event.index` is where the user dropped off. Deliberately **not** fired
   * by `stopTour()` (programmatic teardown such as a route change), which stays analytics-silent.
   */
  onSkip?: (event: GuideEndEvent) => void;
}
```

```ts
type Placement = Side | `${Side}-${Alignment}`
```

```ts
interface GuideControllerOptions {
/** Persistence adapter. @default localStorage-backed adapter */
  storage?: GuideStorageAdapter;
  /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
  overlayStack?: GuideOverlayStackLike;
  /**
   * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
   * current location, the controller calls this to navigate there before spotlighting the step.
   * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
   * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
   * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
   */
  navigate?: (route: string) => void | Promise<void>;
  /**
   * Source for the current path + navigation events, used to decide whether a step's `route`
   * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
   * tour). @default a browser source reading `window.location.pathname` and listening via the
   * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
   * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
   * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
   * detection, or to handle a configured base path / custom router.
   */
  navigationSource?: GuideNavigationSource;
  /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
  dev?: boolean;
}
```

```ts
interface GuideTopicMeta {
/** Human-readable label, e.g. "Save button". */
  label?: string;
  /** Article id this topic links to (Direction A: Marker → Panel). */
  article?: string;
  /** Enabled link directions. @default 'both' */
  direction?: GuideDirection;
}
```

```ts
interface GuideStep {
/** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
  target?: string;
  /**
   * Optional route this step lives on — declarative cross-route touring. When set and different
   * from the current location, the controller calls its injected `navigate` hook to go there
   * **before** the spotlight, then re-anchors once the target appears on the new page (via the
   * renderer's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
   * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
   * against `window.location.pathname` by default, so use a normalized path (no query/hash);
   * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
   * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
   * @see GuideControllerOptions.navigate
   */
  route?: string;
  /** Step heading. */
  title?: string;
  /** Step body text. */
  body?: string;
  /** Preferred bubble placement relative to the target (Phase 6). */
  placement?: Placement;
  /** Whether the highlighted element stays interactive during a spotlight step (Phase 6). */
  interactive?: boolean;
  /**
   * How the step advances. `'user'` — the footer's Next button (and ArrowRight) work as
   * usual. `'action'` — learning-by-doing: Next is rendered disabled (`aria-disabled`,
   * with a screen-reader hint) and ArrowRight is inert; the app advances imperatively via
   * `controller.next()` once the user performed the real action (usually combined with
   * `interactive: true` so the spotlit target stays usable). Back and Skip stay available.
   * The gate lives purely in the `Guide` renderer — the engine's `next()` is never blocked.
   * @default 'user'
   */
  advance?: 'user' | 'action';
}
```

```ts
interface GuideStepEvent {
/** The tour the step belongs to (handy for a shared handler keyed by `tour.id`). */
  tour: GuideTour;
  /** Zero-based index of the now-active step. */
  index: number;
  /** The now-active step. */
  step: GuideStep;
  /** Total number of steps in the tour. */
  total: number;
  /** How the step became active: initial `startTour`, or a `next`/`prev` navigation. */
  via: 'start' | 'next' | 'prev';
}
```

```ts
interface GuideEndEvent {
/** The tour that ended. */
  tour: GuideTour;
  /** Index of the step that was active when the tour ended. */
  index: number;
  /** The step active at the end (`null` only for an empty tour, which never starts). */
  step: GuideStep | null;
  /** Total number of steps in the tour. */
  total: number;
}
```

```ts
type Side = 'top' | 'right' | 'bottom' | 'left'
```

```ts
type Alignment = 'start' | 'end'
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

```ts
interface GuideOverlayStackLike {
register(id: string, close: () => void): () => void;
  isTop(id: string): boolean;
  /** Number of modal overlays currently open — drives the non-modal hide (GUIDE.md §6). */
  readonly depth: number;
}
```

```ts
interface GuideNavigationSource {
/** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
  current(): string;
  /**
   * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
   * controller subscribes only while a tour with at least one `route` step is active, so a tour
   * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
   * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
   * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
   * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
   */
  subscribe(onNavigate: (path: string) => void): () => void;
}
```

### Slots (slotClasses keys)
`beacon`, `ping`, `dot`