@apollovisionlabs/guide-core 0.2.0 → 0.3.0

package/README.md

@@ -61,7 +61,7 @@ missing-target policy below from ever firing.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `labels` | `Partial<{ next, previous, finish, close }>` | `{ next: 'Next', previous: 'Back', finish: 'Finish', close: 'Close' }` | The popover's button labels. Defaults are English; override any subset. See "Translations". |
+| `labels` | `Partial<{ next, previous, finish, close, awaitingAction }>` | `{ next: 'Next', previous: 'Back', finish: 'Finish', close: 'Close', awaitingAction: 'Click the highlighted element to continue.' }` | The popover's button labels. Defaults are English; override any subset. See "Translations". |
 | `zIndex` | `number` | `theme.zIndex.modal` | Stacking level of the spotlight; the popover sits one above it. |
 | `padding` | `number` | `8` | Margin, in pixels, between the highlighted element and the edge of the spotlight hole. |
 | `radius` | `number` | `8` | Corner radius, in pixels, of the spotlight hole. |
@@ -113,8 +113,10 @@ interface GuideStorage {
 ```
 
 `GuideProvider` reads and writes tour progress under `tour:<id>`. `ChecklistProvider` reads and
-writes checklist progress under `checklist:<id>`. See [ADR 0016](docs/adr/0016-one-storage-contract-for-tours-and-checklists.md)
-for why the two share one interface.
+writes checklist progress under `checklist:<id>`. `HotspotProvider` reads and writes which
+hotspots have been opened under the single key `hotspots:seen`. See
+[ADR 0016](docs/adr/0016-one-storage-contract-for-tours-and-checklists.md) for why they share one
+interface.
 
 `@apollovisionlabs/guide-core` ships `createMemoryStorage()` for tests and `createBrowserStorage(namespace?)` for
 `localStorage`. Neither talks to a server. An implementation backed by your own API looks like
@@ -147,7 +149,8 @@ tour advances or completes. `ChecklistProvider` reads once on mount and writes w
 ticked, completed or the checklist is dismissed.
 
 A value read back from storage is validated before it is trusted (`isTourProgress`,
-`isChecklistProgress`, both exported from `@apollovisionlabs/guide-core`): a value that does not
+`isChecklistProgress`, `isHotspotsProgress`, all exported from `@apollovisionlabs/guide-core`): a
+value that does not
 match the expected shape, from a hand-edited store or an older version of this library, is treated
 the same as nothing stored, rather than crashing or resuming into a broken state.
 
@@ -170,8 +173,8 @@ and nothing English remains:
 
 ## Events
 
-`onEvent` on `GuideProvider` and on `ChecklistProvider` each receive their own lifecycle events, as
-a discriminated union of `GuideEvent`:
+`onEvent` on `GuideProvider`, `ChecklistProvider` and `HotspotProvider` each receive their own
+lifecycle events, as a discriminated union of `GuideEvent`:
 
 | Event | Payload | When |
 | --- | --- | --- |
@@ -183,6 +186,8 @@ a discriminated union of `GuideEvent`:
 | `checklist:item-complete` | `{ checklistId, itemId }` | An item is completed, by finishing its linked tour or by a manual tick. Not emitted for an item already complete. |
 | `checklist:complete` | `{ checklistId }` | The last incomplete item in a checklist is completed. Fires on every transition into the complete state, so unticking an item and reticking it emits a second time. Deduplicate downstream if you count completions. |
 | `checklist:dismiss` | `{ checklistId }` | `dismiss()` is called. |
+| `hotspot:show` | `{ hotspotId }` | A hotspot's marker is actually drawn on screen. Emitted once per hotspot per mount. |
+| `hotspot:open` | `{ hotspotId }` | The hotspot's bubble is opened, which also marks it seen. Not emitted again for a bubble that is already open. |
 
 ## Accessibility
 
@@ -206,6 +211,44 @@ happens: `'skip'` moves to the next step, `'error'` stops the tour, and `'wait'`
 pauses and resumes automatically if the target appears later, for instance after a slow async
 render.
 
+## Advancing on an action
+
+A step can declare `advanceOn: 'click'` instead of ending on the popover's button:
+
+```ts
+{
+  target: 'project.share',
+  title: 'Share it',
+  body: 'Click the button yourself, this step is interactive.',
+  advanceOn: 'click',
+}
+```
+
+The step advances when the user clicks the target, not the popover. `advanceOn` implies
+`interactive`: a step that waits for a click has to let the click through, so `GuideProvider`
+derives both `interactive` and `awaitsAction` on `ActiveStep` from `advanceOn`, rather than
+requiring both to be set by hand. Read `activeStep.interactive` / `activeStep.awaitsAction`, not
+`step.interactive`, which is left `undefined` on a step that only sets `advanceOn`. See
+[ADR 0017](docs/adr/0017-advancing-on-an-action-implies-an-interactive-step.md).
+
+`@apollovisionlabs/guide-mui`'s popover reflects `awaitsAction`: no primary button, and the
+`awaitingAction` label in its place (see the `labels` row above). `ArrowRight` is ignored while a
+step awaits its action, since letting it through would be a way around the very thing the step is
+asking for; `Escape` and `ArrowLeft` still work.
+
+The click listener is attached, in the bubble phase, to the element resolved when the step
+opened, without `preventDefault` or `stopPropagation`, so your own click handler on the target
+still runs.
+
+If your application replaces that DOM node afterward, for instance by re-rendering a list, the
+listener goes with it and the step stops advancing. Nothing notices: the target was found once,
+so the timeout was already cleared, no `target:missing` is emitted and no `wait`, `skip` or
+`error` policy runs. The tour simply sits on that step. The consequence is specific to
+`advanceOn`, even though the cause is not: an `advanceOn` step offers no primary button and
+ignores `ArrowRight`, so a replaced node leaves the tour with `Escape` as its only exit. If the
+element a step points at can be re-created under it, either give it a stable target that survives
+the re-render or use an ordinary step with a Next button.
+
 ## Checklist
 
 A checklist is a separate feature from the tour: a fixed list of items, each completed by
@@ -266,11 +309,16 @@ finishing a tour whose item is already ticked, does nothing and emits no event.
 
 ### `useChecklist(checklistId)`
 
-Returns `{ items, completedCount, total, isComplete, dismissed, activate, toggle, complete, dismiss, reset }`.
+Returns `{ items, completedCount, total, isComplete, dismissed, restored, activate, toggle, complete, dismiss, reset }`.
 `items` is `ResolvedChecklistItem[]`: `{ id, title, body, completed, tourId?, href? }`, with
 `title` / `body` already resolved through `translate`. `activate(itemId)` runs an item's default
 action (start its tour, navigate to its `href`, or toggle it if it has neither); `toggle` and
 `complete` change completion directly; `dismiss()` and `reset()` act on the whole checklist.
+`restored` is whether this checklist's own initial read from storage has settled: `true`
+immediately with no `storage` prop (there is nothing to wait for), and `true` once this
+checklist's own read has resolved or rejected. It settles independently per checklist, so a
+`ChecklistProvider` holding several checklists never lets a slow or hung read for one hold
+another one's `restored` false; each checklist's read runs concurrently with the others.
 
 ### `Checklist` and `ChecklistLauncher` (`@apollovisionlabs/guide-mui`)
 
@@ -288,6 +336,140 @@ import { Checklist, ChecklistLauncher } from '@apollovisionlabs/guide-mui'
 <ChecklistLauncher checklistId="onboarding" title="Get started" placement="bottom-right" />
 ```
 
+With a `storage` prop configured on `ChecklistProvider`, both `Checklist` and `ChecklistLauncher`
+wait for their own checklist's restore to settle (`useChecklist(checklistId).restored`) before
+drawing anything, rather than rendering their empty initial state (nothing completed, not
+dismissed) for one paint. The tradeoff: with a slow storage backend, a checklist now appears later
+than it used to, instead of appearing at once and then jumping. A slow or broken read for one
+checklist never holds a different checklist back; each restores on its own.
+
+## Hotspots
+
+A hotspot marks one element outside any tour: a small marker that opens a short explanation, and
+optionally a button that starts a tour. Unlike a tour step, a hotspot has no route and no order;
+it just sits at its target until opened. `HotspotProvider` nests inside `GuideProvider`, the same
+way `ChecklistProvider` does, so a hotspot naming a `tourId` can start it:
+
+```tsx
+import {
+  GuideProvider,
+  HotspotProvider,
+  type Hotspot,
+  type Tour,
+} from '@apollovisionlabs/guide-core'
+import { GuideTour, Hotspots } from '@apollovisionlabs/guide-mui'
+
+const welcomeTour: Tour = {
+  id: 'welcome',
+  steps: [
+    { target: 'projects.create', title: 'Create a project', body: 'Start here.' },
+    { target: 'project.share', title: 'Share it', body: 'Send a link to your team.' },
+  ],
+}
+
+const hotspots: Hotspot[] = [
+  {
+    id: 'create',
+    target: 'projects.create',
+    title: 'Start a project',
+    body: 'Everything else in here hangs off a project.',
+  },
+  {
+    id: 'share',
+    target: 'project.share',
+    title: 'Share a project',
+    body: 'Send a link to anyone on your team.',
+    // Named tours must exist on the GuideProvider above, or starting one warns and does nothing.
+    tourId: 'welcome',
+  },
+]
+
+function App() {
+  return (
+    <GuideProvider tours={[welcomeTour]}>
+      <HotspotProvider hotspots={hotspots}>
+        <YourApplication />
+        <GuideTour />
+        <Hotspots />
+      </HotspotProvider>
+    </GuideProvider>
+  )
+}
+```
+
+Without a `GuideProvider` above it, starting a hotspot's tour warns once in the console and does
+nothing.
+
+### `HotspotProvider` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `hotspots` | `Hotspot[]` | none | The hotspots to render. Ids must be unique. |
+| `children` | `ReactNode` | none | Your application. |
+| `storage` | `GuideStorage` | none | Persists which hotspots have been opened, under `hotspots:seen`. See "Persistence". |
+| `translate` | `(key: string) => string` | none | Resolves `titleKey` / `bodyKey` on hotspots. See "Translations". |
+| `onEvent` | `(event: GuideEvent) => void` | none | Called for `hotspot:show` and `hotspot:open`. See "Events". |
+
+### `useHotspots()`
+
+Returns `{ hotspots, restored, open, startTour, reset, notifyShown }`.
+
+- `hotspots` is `ResolvedHotspot[]`: every hotspot, each carrying its own `seen`, with `title` /
+  `body` already resolved through `translate`. It lists the seen ones too, rather than only the
+  unseen ones, because a renderer that keeps a marker mounted while its own bubble closes needs
+  the seen one as well; filtering to unseen-only is one line at the call site.
+- `restored` is whether the initial read from storage has settled: `true` immediately with no
+  `storage` prop (there is nothing to wait for), and `true` once the read resolves or rejects.
+  Wait for it before drawing any marker, or a hotspot already seen in storage can flash on screen
+  once before the restore lands.
+- `open(hotspotId)` marks a hotspot seen and emits `hotspot:open`.
+- `startTour(hotspotId)` starts the tour named by the hotspot's `tourId`, if it has one.
+- `reset()` clears the seen state for every hotspot.
+- `notifyShown(hotspotId)` is for renderers: call it once a marker is actually drawn on screen, so
+  `hotspot:show` fires once per hotspot per mount. `@apollovisionlabs/guide-mui`'s `Hotspots`
+  already calls it.
+
+### `Hotspots` (`@apollovisionlabs/guide-mui`)
+
+Renders a marker at each unseen hotspot's target; clicking it opens a bubble with the hotspot's
+title, body, and, when it names a `tourId`, a button that starts that tour.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `labels` | `Partial<{ marker, startTour, close }>` | see below | Wording. `marker` is a function of the hotspot's title, not a fixed string, because word order around a name varies by language. |
+| `placement` | `Placement` | `'bottom'` | Where the bubble opens relative to the marker. Overridable per hotspot through `Hotspot.placement`. |
+| `zIndex` | `number` | `theme.zIndex.drawer + 1` | Stacking level of the marker; the bubble sits one above it. |
+
+Default labels: `` { marker: (title) => `Show what is new: ${title}`, startTour: 'Show me', close: 'Close' } ``.
+
+No marker is drawn while a tour is running or paused. A hotspot is an ambient hint and must not
+compete with a guided flow the user is already in: a marker over the element a step points at
+would take the click meant for that step, and one over a non-interactive step would be drawn
+bright and pulsing yet inert behind the spotlight. The markers come back when the tour ends,
+unchanged: this suppresses them, it does not mark them seen. `Hotspots` reads the tour state
+through context and tolerates its absence, so hotspots work with no `GuideProvider` in the tree.
+
+`paused` counts, because a paused tour is waiting for its target rather than finished. Note what
+that implies at the edge: a tour paused on a target that never appears, the default `wait`
+policy, draws nothing itself and now hides every hotspot too, for as long as it stays paused,
+with `Escape` as the only way out and nothing on screen to suggest it. If your steps point at
+targets that may never mount, prefer the `skip` or `error` missing-target policy over `wait`.
+
+The default `zIndex` sits below `theme.zIndex.modal`, the level a running tour's spotlight uses,
+so a hotspot whose target lives inside your own modal dialog is covered by it. Raise `zIndex` on
+`Hotspots` to bring the marker above that dialog.
+
+A marker is drawn only for a target that has actual size on screen. An element that is in the DOM
+but not rendered, `display: none` for instance, measures an all-zero rectangle; that draws no
+marker and emits no `hotspot:show`, so a hotspot cannot be retired before the user has seen what
+it explains.
+
+Clicking a marker whose bubble is already open closes the bubble, and emits no second
+`hotspot:open`.
+
+With a `storage` prop configured on `HotspotProvider`, `Hotspots` waits for the initial restore to
+settle (`useHotspots().restored`) before drawing any marker.
+
 ## Compatibility
 
 | | Supported |

package/dist/index.cjs

@@ -25,11 +25,14 @@ __export(index_exports, {
   ChecklistProvider: () => ChecklistProvider,
   GuideContext: () => GuideContext,
   GuideProvider: () => GuideProvider,
+  HotspotContext: () => HotspotContext,
+  HotspotProvider: () => HotspotProvider,
   createBrowserStorage: () => createBrowserStorage,
   createMemoryStorage: () => createMemoryStorage,
   findMissingTargets: () => findMissingTargets,
   initialTourState: () => initialTourState,
   isChecklistProgress: () => isChecklistProgress,
+  isHotspotsProgress: () => isHotspotsProgress,
   isLiteralRoute: () => isLiteralRoute,
   isTourProgress: () => isTourProgress,
   matchRoute: () => matchRoute,
@@ -40,6 +43,7 @@ __export(index_exports, {
   useElementRect: () => useElementRect,
   useFocusTrap: () => useFocusTrap,
   useGuideStep: () => useGuideStep,
+  useHotspots: () => useHotspots,
   usePrefersReducedMotion: () => usePrefersReducedMotion,
   useTargetElement: () => useTargetElement,
   useTour: () => useTour
@@ -90,6 +94,11 @@ function isChecklistProgress(value) {
   const candidate = value;
   return Array.isArray(candidate.completed) && candidate.completed.every((entry) => typeof entry === "string") && typeof candidate.dismissed === "boolean";
 }
+function isHotspotsProgress(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return Array.isArray(candidate.seen) && candidate.seen.every((entry) => typeof entry === "string");
+}
 
 // src/matchRoute.ts
 function segments(value) {
@@ -321,6 +330,24 @@ function resolveText(value, key, translate) {
 // src/GuideProvider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var GuideContext = (0, import_react4.createContext)(null);
+function focusFallback(element) {
+  const needsTabIndex = !element.hasAttribute("tabindex") && element.tabIndex < 0;
+  if (!needsTabIndex) {
+    element.focus();
+    return;
+  }
+  element.setAttribute("tabindex", "-1");
+  element.focus();
+  if (document.activeElement !== element) {
+    element.removeAttribute("tabindex");
+    return;
+  }
+  const onBlur = () => {
+    element.removeAttribute("tabindex");
+    element.removeEventListener("blur", onBlur);
+  };
+  element.addEventListener("blur", onBlur);
+}
 function GuideProvider({
   tours,
   children,
@@ -345,6 +372,7 @@ function GuideProvider({
   const [state, dispatch] = (0, import_react4.useReducer)(tourReducer, initialTourState);
   const announce = useAnnouncer();
   const focusOriginRef = (0, import_react4.useRef)(null);
+  const lastElementRef = (0, import_react4.useRef)(null);
   const storageWarnedRef = (0, import_react4.useRef)(false);
   const warnStorageFailure = (0, import_react4.useCallback)((error) => {
     if (storageWarnedRef.current) return;
@@ -380,6 +408,14 @@ function GuideProvider({
     dispatch({ type: "NEXT", stepCount: tour.steps.length });
     if (isLast) emit({ type: "tour:complete", tourId: tour.id });
   }, [tour, state.stepIndex, emit]);
+  const nextRef = (0, import_react4.useRef)(next);
+  nextRef.current = next;
+  (0, import_react4.useEffect)(() => {
+    if (state.status !== "running" || !element || step?.advanceOn !== "click") return;
+    const onClick = () => nextRef.current();
+    element.addEventListener("click", onClick);
+    return () => element.removeEventListener("click", onClick);
+  }, [state.status, element, step?.advanceOn]);
   const previous = (0, import_react4.useCallback)(() => dispatch({ type: "PREVIOUS" }), []);
   const stop = (0, import_react4.useCallback)(() => {
     if (tour) emit({ type: "tour:stop", tourId: tour.id, stepIndex: state.stepIndex });
@@ -478,12 +514,23 @@ function GuideProvider({
       warnStorageFailure(error);
     }
   }, [storage, state.tourId, state.status, state.stepIndex, warnStorageFailure]);
+  (0, import_react4.useEffect)(() => {
+    if (element) lastElementRef.current = element;
+  }, [element]);
   (0, import_react4.useEffect)(() => {
     if (state.status !== "idle" && state.status !== "completed") return;
     const origin = focusOriginRef.current;
-    if (!origin) return;
+    const fallback = lastElementRef.current;
     focusOriginRef.current = null;
-    if (typeof document !== "undefined" && document.contains(origin)) origin.focus();
+    lastElementRef.current = null;
+    if (typeof document === "undefined") return;
+    if (origin && document.contains(origin)) {
+      origin.focus();
+      return;
+    }
+    if (document.activeElement !== document.body) return;
+    if (!fallback || !document.contains(fallback)) return;
+    focusFallback(fallback);
   }, [state.status]);
   const activeStep = (0, import_react4.useMemo)(() => {
     if (!tour || !step || !isActive) return null;
@@ -494,6 +541,8 @@ function GuideProvider({
       stepCount: tour.steps.length,
       element,
       rect,
+      interactive: step.interactive === true || step.advanceOn !== void 0,
+      awaitsAction: step.advanceOn !== void 0,
       title: resolveText(step.title, step.titleKey, translate),
       body: resolveText(step.body, step.bodyKey, translate),
       isFirst: state.stepIndex === 0,
@@ -562,6 +611,11 @@ function ChecklistProvider({
     return initial;
   });
   const progressRef = (0, import_react7.useRef)(progress);
+  const [restoredById, setRestoredById] = (0, import_react7.useState)(() => {
+    const initial = {};
+    for (const candidate of checklists) initial[candidate.id] = !storage;
+    return initial;
+  });
   const guide = (0, import_react7.useContext)(GuideContext);
   const storageWarnedRef = (0, import_react7.useRef)(false);
   const warnStorageFailure = (0, import_react7.useCallback)((error) => {
@@ -593,31 +647,33 @@ function ChecklistProvider({
   (0, import_react7.useEffect)(() => {
     if (!storage) return;
     let cancelled = false;
-    void (async () => {
-      const restored = {};
-      for (const candidate of checklists) {
+    for (const candidate of checklists) {
+      void (async () => {
         try {
           const stored = await storage.read(`checklist:${candidate.id}`);
-          if (isChecklistProgress(stored)) restored[candidate.id] = stored;
+          if (!cancelled && isChecklistProgress(stored)) {
+            const live = progressRef.current[candidate.id] ?? emptyProgress;
+            const merged = {
+              ...progressRef.current,
+              [candidate.id]: {
+                completed: live.completed.concat(
+                  stored.completed.filter((id) => !live.completed.includes(id))
+                ),
+                dismissed: live.dismissed || stored.dismissed
+              }
+            };
+            progressRef.current = merged;
+            setProgress(merged);
+          }
         } catch (error) {
           warnStorageFailure(error);
+        } finally {
+          if (!cancelled) {
+            setRestoredById((current) => ({ ...current, [candidate.id]: true }));
+          }
         }
-      }
-      if (!cancelled && Object.keys(restored).length > 0) {
-        const merged = { ...progressRef.current };
-        for (const [checklistId, stored] of Object.entries(restored)) {
-          const live = merged[checklistId] ?? emptyProgress;
-          merged[checklistId] = {
-            completed: live.completed.concat(
-              stored.completed.filter((id) => !live.completed.includes(id))
-            ),
-            dismissed: live.dismissed || stored.dismissed
-          };
-        }
-        progressRef.current = merged;
-        setProgress(merged);
-      }
-    })();
+      })();
+    }
     return () => {
       cancelled = true;
     };
@@ -755,8 +811,18 @@ function ChecklistProvider({
     [resolveItem, guide, navigate, toggle, warnNoGuide, warnNoNavigate, warnTourStartFailure]
   );
   const value = (0, import_react7.useMemo)(
-    () => ({ checklists, progress, translate, activate, toggle, complete, dismiss, reset }),
-    [checklists, progress, translate, activate, toggle, complete, dismiss, reset]
+    () => ({
+      checklists,
+      progress,
+      translate,
+      restored: restoredById,
+      activate,
+      toggle,
+      complete,
+      dismiss,
+      reset
+    }),
+    [checklists, progress, translate, restoredById, activate, toggle, complete, dismiss, reset]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(ChecklistContext.Provider, { value, children });
 }
@@ -773,6 +839,7 @@ function useChecklist(checklistId) {
   const completed = progress?.completed ?? [];
   const dismissed = progress?.dismissed ?? false;
   const translate = context.translate;
+  const restored = context.restored[checklistId] ?? true;
   const items = (0, import_react8.useMemo)(
     () => checklist.items.map((item) => ({
       id: item.id,
@@ -795,6 +862,7 @@ function useChecklist(checklistId) {
       total,
       isComplete,
       dismissed,
+      restored,
       activate: (itemId) => activate(checklistId, itemId),
       toggle: (itemId) => toggle(checklistId, itemId),
       complete: (itemId) => complete(checklistId, itemId),
@@ -807,6 +875,7 @@ function useChecklist(checklistId) {
       total,
       isComplete,
       dismissed,
+      restored,
       activate,
       toggle,
       complete,
@@ -816,17 +885,182 @@ function useChecklist(checklistId) {
     ]
   );
 }
+
+// src/HotspotProvider.tsx
+var import_react9 = require("react");
+var import_jsx_runtime3 = require("react/jsx-runtime");
+var STORAGE_KEY = "hotspots:seen";
+var HotspotContext = (0, import_react9.createContext)(null);
+function HotspotProvider({
+  hotspots,
+  children,
+  storage,
+  translate,
+  onEvent
+}) {
+  const hotspotsById = (0, import_react9.useMemo)(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const candidate of hotspots) {
+      if (map.has(candidate.id)) {
+        throw new Error(`[guide] duplicate hotspot id: ${candidate.id}`);
+      }
+      map.set(candidate.id, candidate);
+    }
+    return map;
+  }, [hotspots]);
+  const [seen, setSeen] = (0, import_react9.useState)([]);
+  const [restored, setRestored] = (0, import_react9.useState)(() => !storage);
+  const seenRef = (0, import_react9.useRef)(seen);
+  const guide = (0, import_react9.useContext)(GuideContext);
+  const storageWarnedRef = (0, import_react9.useRef)(false);
+  const warnStorageFailure = (0, import_react9.useCallback)((error) => {
+    if (storageWarnedRef.current) return;
+    storageWarnedRef.current = true;
+    console.warn("[guide] storage failed; hotspot state will not be persisted", error);
+  }, []);
+  const noGuideWarnedRef = (0, import_react9.useRef)(false);
+  const warnNoGuide = (0, import_react9.useCallback)(() => {
+    if (noGuideWarnedRef.current) return;
+    noGuideWarnedRef.current = true;
+    console.warn("[guide] a hotspot needs a GuideProvider to launch a tour");
+  }, []);
+  const tourStartFailedWarnedRef = (0, import_react9.useRef)(false);
+  const warnTourStartFailure = (0, import_react9.useCallback)((error) => {
+    if (tourStartFailedWarnedRef.current) return;
+    tourStartFailedWarnedRef.current = true;
+    console.warn("[guide] starting a tour for a hotspot failed", error);
+  }, []);
+  const onEventRef = (0, import_react9.useRef)(onEvent);
+  onEventRef.current = onEvent;
+  const emit = (0, import_react9.useCallback)((event) => onEventRef.current?.(event), []);
+  (0, import_react9.useEffect)(() => {
+    if (!storage) return;
+    let cancelled = false;
+    void (async () => {
+      let stored = null;
+      try {
+        stored = await storage.read(STORAGE_KEY);
+      } catch (error) {
+        warnStorageFailure(error);
+        if (!cancelled) setRestored(true);
+        return;
+      }
+      if (cancelled) return;
+      if (isHotspotsProgress(stored)) {
+        const merged = seenRef.current.concat(
+          stored.seen.filter((id) => !seenRef.current.includes(id))
+        );
+        seenRef.current = merged;
+        setSeen(merged);
+      }
+      setRestored(true);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [storage, warnStorageFailure]);
+  const applySeen = (0, import_react9.useCallback)(
+    (next) => {
+      seenRef.current = next;
+      setSeen(next);
+      if (!storage) return;
+      try {
+        void Promise.resolve(storage.write(STORAGE_KEY, { seen: next })).catch(
+          warnStorageFailure
+        );
+      } catch (error) {
+        warnStorageFailure(error);
+      }
+    },
+    [storage, warnStorageFailure]
+  );
+  const resolve = (0, import_react9.useCallback)(
+    (hotspotId) => {
+      const hotspot = hotspotsById.get(hotspotId);
+      if (!hotspot) {
+        console.warn(`[guide] unknown hotspot "${hotspotId}"`);
+        return null;
+      }
+      return hotspot;
+    },
+    [hotspotsById]
+  );
+  const open = (0, import_react9.useCallback)(
+    (hotspotId) => {
+      if (!resolve(hotspotId)) return;
+      emit({ type: "hotspot:open", hotspotId });
+      if (seenRef.current.includes(hotspotId)) return;
+      applySeen([...seenRef.current, hotspotId]);
+    },
+    [resolve, applySeen, emit]
+  );
+  const startTour = (0, import_react9.useCallback)(
+    (hotspotId) => {
+      const hotspot = resolve(hotspotId);
+      if (!hotspot?.tourId) return;
+      if (!guide) {
+        warnNoGuide();
+        return;
+      }
+      void guide.start(hotspot.tourId).catch(warnTourStartFailure);
+    },
+    [resolve, guide, warnNoGuide, warnTourStartFailure]
+  );
+  const reset = (0, import_react9.useCallback)(() => applySeen([]), [applySeen]);
+  const shownRef = (0, import_react9.useRef)(/* @__PURE__ */ new Set());
+  const notifyShown = (0, import_react9.useCallback)(
+    (hotspotId) => {
+      if (shownRef.current.has(hotspotId)) return;
+      shownRef.current.add(hotspotId);
+      emit({ type: "hotspot:show", hotspotId });
+    },
+    [emit]
+  );
+  const value = (0, import_react9.useMemo)(
+    () => ({ hotspots, seen, translate, restored, open, startTour, reset, notifyShown }),
+    [hotspots, seen, translate, restored, open, startTour, reset, notifyShown]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(HotspotContext.Provider, { value, children });
+}
+
+// src/useHotspots.ts
+var import_react10 = require("react");
+function useHotspots() {
+  const context = (0, import_react10.useContext)(HotspotContext);
+  if (!context)
+    throw new Error("[guide] useHotspots must be used inside a HotspotProvider");
+  const { seen, translate, restored, open, startTour, reset, notifyShown } = context;
+  const hotspots = (0, import_react10.useMemo)(
+    () => context.hotspots.map((hotspot) => ({
+      id: hotspot.id,
+      target: hotspot.target,
+      title: resolveText(hotspot.title, hotspot.titleKey, translate),
+      body: resolveText(hotspot.body, hotspot.bodyKey, translate),
+      seen: seen.includes(hotspot.id),
+      tourId: hotspot.tourId,
+      placement: hotspot.placement
+    })),
+    [context.hotspots, seen, translate]
+  );
+  return (0, import_react10.useMemo)(
+    () => ({ hotspots, restored, open, startTour, reset, notifyShown }),
+    [hotspots, restored, open, startTour, reset, notifyShown]
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ChecklistContext,
   ChecklistProvider,
   GuideContext,
   GuideProvider,
+  HotspotContext,
+  HotspotProvider,
   createBrowserStorage,
   createMemoryStorage,
   findMissingTargets,
   initialTourState,
   isChecklistProgress,
+  isHotspotsProgress,
   isLiteralRoute,
   isTourProgress,
   matchRoute,
@@ -837,6 +1071,7 @@ function useChecklist(checklistId) {
   useElementRect,
   useFocusTrap,
   useGuideStep,
+  useHotspots,
   usePrefersReducedMotion,
   useTargetElement,
   useTour