@sunboard/react 0.9.0 → 1.1.0

package/dist/index.d.mts

@@ -1,348 +1,958 @@
 import { ReactNode } from "react";
-import { RuntimeBootstrapRequest, RuntimeBootstrapResponse, RuntimeExperience, RuntimeProgress, RuntimeTrackRequest, RuntimeTrackResponse, SunboardRuntimeApiError, SunboardRuntimeClient, SunboardRuntimeClientOptions, TooltipDismissVia } from "@sunboard/core/runtime-api";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
-import { NormalizedSunboardSpec, SunboardHotspot, SunboardPlacement, SunboardStep, SunboardTooltip, SunboardTourStep, SurveyQuestionType, TrackEventName } from "@sunboard/core";
-
-//#region src/adapters/navigation.d.ts
-type NavigateCallback = (url: string) => void | Promise<void>;
-//#endregion
-//#region src/lib/detect-identities.d.ts
+//#region ../core/src/guides.d.ts
+type GuideType = "tour" | "tooltip" | "announcement" | "banner";
+type StepPrimitive = "pin" | "modal" | "popover";
 /**
- * Best-effort probe of analytics providers on the host page, returning the id
- * each one files the current visitor under (e.g. PostHog's distinct_id). These
- * ride the bootstrap request so the server can join Sunboard's funnel data to
- * the customer's analytics; they are inert until the project connects the
- * provider in Sunboard.
- *
- * Everything here is defensive by construction: a broken or half-loaded
- * analytics snippet on the customer's page must never break onboarding, so
- * every probe is wrapped and failures return nothing.
+ * Where a pin dot sits ON its element: a 9-point grid over the element's box.
+ * Distinct from StepPlacement, which says which side a CARD opens on.
  */
+type PinPosition = "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right";
 /**
- * The `identities` prop accepted by SunboardProvider:
- * - omitted: providers are auto-detected on each bootstrap
- * - object: explicit ids, merged over (and winning against) detected ones
- * - `false`: detection disabled entirely, nothing is sent
+ * Which side of the anchor the card attaches to (floating-ui's placement
+ * vocabulary). Authored placement is a preference, not a promise: the overlay
+ * still flips/shifts it when the viewport runs out of room.
  */
-type IdentitiesProp = Record<string, string> | false;
-//#endregion
-//#region src/hooks/sunboard-context.d.ts
-type SunboardUser = {
+type StepPlacement = "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end";
+interface GuideStep {
+  /** Unique within its guide and kept through edits. */
   id: string;
-  email?: string | null;
-  group?: string | null;
-  properties?: Record<string, unknown>;
-};
-type TrackProperties = Record<string, unknown>;
-type TrackResult = {
-  ok: true;
-} | {
-  ok: false;
-  reason: "not-ready" | "missing-user" | "network-error";
-};
-type SurveyResult = {
-  ok: true;
-} | {
-  ok: false;
-  reason: "not-ready" | "missing-user" | "not-survey" | "network-error";
-};
-type TourResult = {
-  ok: true;
-} | {
-  ok: false;
-  reason: "not-ready" | "missing-user" | "missing-tour";
-};
-type StepResult = {
-  ok: true;
-} | {
-  ok: false;
-  reason: "not-ready" | "missing-user" | "missing-step" | "not-manual" | "network-error";
-};
-type TooltipResult = {
-  ok: true;
-} | {
-  ok: false;
-  reason: "not-ready" | "missing-user" | "missing-tooltip";
-};
-type VisibleSunboardTooltip = {
+  /** Pathname the step lives on, e.g. "/settings". May contain :params. Absent for route-independent modal steps. */
+  route?: string;
+  /** Absent for modal steps (nothing to point at). */
+  anchor?: Anchor;
+  primitive: StepPrimitive;
+  /** Anchored steps only. Default DEFAULT_PLACEMENT. */
+  placement?: StepPlacement;
+  /** Pin steps only: where the dot sits on the element. Default "top-right". */
+  pinPosition?: PinPosition;
+  title: string;
+  body: string;
+  /** Image/video URL carried from the article, only when it shows what the live UI cannot. */
+  media?: string;
+  /** Heading of the article section this step came from (article-level provenance). */
+  sourceSection?: string;
+  /** Position in the plan's grounding record of the grounded step this step was written from. */
+  groundedIndex?: number;
+}
+interface GuideContent {
+  /** kebab-case identifier, unique per workspace. */
   key: string;
-  tooltip: SunboardTooltip;
+  type: GuideType;
+  title: string;
+  steps: GuideStep[];
   /**
-   * True when the user asked for this tooltip (a checklist step's
-   * `openTooltip` action), false when it is showing proactively. A requested
-   * tooltip shows even if it was dismissed before — the user explicitly asked
-   * to be shown where the action happens.
+   * Tooltip only: the tour its card's action starts ("Show me"). The pin+card
+   * is the one ambient launch surface, so a tour started "from a pin" is a
+   * tooltip that launches it. Curated in the dashboard, never generated (the
+   * write stage sees one article at a time and cannot know other tours).
    */
-  requested: boolean;
-};
-type ActiveSunboardTour = {
-  key: string;
+  launches?: string;
+  /**
+   * Stamped by the server at bootstrap, not authored: the guide's current
+   * revision, echoed back on every event so a regenerated guide's funnel
+   * never mixes two different step sequences.
+   */
+  revision?: number;
+}
+//#endregion
+//#region ../core/src/pages.d.ts
+interface AppPage {
+  /** The route pattern, e.g. "/invoices/:id". */
+  path: string;
+  /** What the page is called, or null when nothing has named it yet. */
+  title: string | null;
+}
+//#endregion
+//#region ../core/src/settings.d.ts
+interface ComponentSettings {
+  launcher: {
+    showBranding: boolean;
+    supportUrl: string | null;
+  };
+  tour: {
+    showStepCount: boolean;
+    showBackButton: boolean;
+  };
+  banner: {
+    dismissible: boolean;
+  };
+  cards: {
+    /** The main button on a tour step, announcement or tooltip: a filled accent button, or accent text alone. */
+    primaryButton: "filled" | "text";
+  };
+}
+//#endregion
+//#region ../core/src/theme.d.ts
+type ThemeMode = "light" | "dark";
+/** A color that carries an opacity (0-100). */
+interface AlphaColor {
+  hex: string;
+  alpha: number;
+}
+interface Palette {
+  accent: {
+    color: string;
+    textOn: string;
+  };
+  content: {
+    primary: string;
+    secondary: string;
+  };
+  background: {
+    primary: string;
+    primaryHover: string;
+    overlay: AlphaColor;
+  };
+  border: {
+    primary: string;
+    primaryHover: string;
+  };
+  focusRing: AlphaColor;
+  cardShadowColor: AlphaColor;
+}
+interface WidgetDims {
+  width: number;
+  maxHeight?: number;
+}
+interface Theme {
   name: string;
-  step: SunboardTourStep;
-  stepIndex: number;
-  totalSteps: number;
+  light: Palette;
+  dark: Palette;
+  typography: {
+    family: string;
+    size: {
+      sm: number;
+      base: number;
+      lg: number;
+    };
+    weight: {
+      regular: number;
+      medium: number;
+      semibold: number;
+    };
+    lineHeight: {
+      snug: number;
+      normal: number;
+    };
+  };
+  /** Every button and input, in the launcher panel and on the cards alike. */
+  formControls: {
+    height: number;
+    radius: number;
+    padding: number;
+    gap: number;
+    focusRingWidth: number;
+  };
+  cards: {
+    radius: number;
+    padding: number;
+    shadow: string;
+  };
+  widgets: {
+    announcement: WidgetDims;
+    tour: WidgetDims;
+    tooltip: WidgetDims;
+    launcher: WidgetDims;
+  };
+}
+//#endregion
+//#region ../core/src/runtime.d.ts
+interface UserState {
+  /** Tooltips this user has opened once; their pins are not shown again. */
+  openedTooltipKeys: string[];
+}
+interface BootstrapData {
+  /** Live guides (plus paused ones on preview sessions). */
+  guides: GuideContent[];
+  pages: AppPage[];
+  productName: string;
+  userState: UserState;
+  /**
+   * Dashboard-configured appearance. Null until the workspace configures it;
+   * when present, it wins over any client-side prop so dashboard edits reach
+   * the app without a deploy.
+   */
+  settings: ComponentSettings | null;
+  theme: Theme | null;
+  /**
+   * The steps with an open miss, so the widget says when it finds one. Absent
+   * from an API older than the field.
+   */
+  missedSteps?: StepRef[];
+  /**
+   * The anchored steps of the guides waiting to be seen, minus the steps seen
+   * at their revision, oldest guides first and at most 300. The widget looks
+   * for the ones on its page and shows nothing.
+   */
+  checks: StepCheck[];
+}
+/** What bootstrap answers when the workspace's organization has no plan. The SDK shows nothing. */
+interface BootstrapOff {
+  off: true;
+}
+type BootstrapAnswer = BootstrapData | BootstrapOff;
+export declare function isBootstrapOff(answer: BootstrapAnswer): answer is BootstrapOff;
+interface StepRef {
+  guideKey: string;
+  stepId: string;
+}
+type StateAction = {
+  action: "open-tooltip";
+  key: string;
 };
-type SunboardContextValue = {
-  spec?: NormalizedSunboardSpec | null;
-  user?: SunboardUser | null;
-  loading: boolean;
+interface AnchorMissReport extends Anchor {
+  guideKey: string;
+  /**
+   * The revision the SDK was serving when it missed, echoed like on events:
+   * health surfaces only count misses at the guide's current revision, so a
+   * regeneration clears them.
+   */
+  guideRevision?: number;
+  stepId: string;
   route?: string;
-  completedStepKeys: ReadonlySet<string>;
-  completedTourKeys: ReadonlySet<string>;
-  completedCount: number;
-  totalSteps: number;
-  activeTour: ActiveSunboardTour | null;
-  track: (eventName: TrackEventName, properties?: TrackProperties) => Promise<TrackResult>;
-  /**
-   * Submit survey answers for the active survey experience. On success the
-   * runtime re-bootstraps so the freshly collected attributes route the user
-   * into the next experience in-session.
-   */
-  submitSurvey: (answers: Record<string, unknown>) => Promise<SurveyResult>;
-  startTour: (tourKey: string) => Promise<TourResult>;
-  /**
-   * Close the active tour. User-initiated dismissals are reported to the
-   * runtime API as a negative signal ("the user bailed at this step");
-   * pass `silent: true` for programmatic closes (e.g. a missing tour
-   * target) that say nothing about the user's intent.
-   */
-  dismissTour: (options?: {
-    silent?: boolean;
-  }) => Promise<TourResult>;
-  advanceTour: () => Promise<TourResult>;
-  navigateToStep: (step: SunboardStep) => Promise<void>;
-  startChecklistStep: (step: SunboardStep) => Promise<TourResult | TooltipResult | void>;
-  /**
-   * Complete a checklist step because the user checked it off. Only steps the
-   * spec allows (`manual` not set to false) accept it; the completion is
-   * recorded with a "manual" source, distinct from event/tour completions.
-   */
-  completeChecklistStep: (stepKey: string) => Promise<StepResult>;
-  visibleHotspots: Array<{
-    key: string;
-    hotspot: SunboardHotspot;
-  }>;
-  dismissedTooltipKeys: ReadonlySet<string>;
-  /**
-   * Tooltips that qualify for the current route, requested-first. Renderers
-   * show ONE at a time: the first entry whose target resolves.
-   */
-  visibleTooltips: VisibleSunboardTooltip[];
-  /**
-   * Open a tooltip on demand (the checklist's openTooltip action). Navigates
-   * are the caller's job; this just marks the tooltip requested so it renders
-   * once its route matches and its target is present, dismissal or not.
-   */
-  openTooltip: (tooltipKey: string) => Promise<TooltipResult>;
-  /**
-   * Never show this tooltip again. `via: "close"` is the negative signal (the
-   * default); `via: "action"` records that the user took the tooltip's action;
-   * `via: "target"` records that the user clicked the tooltip's target element.
-   */
-  dismissTooltip: (tooltipKey: string, options?: {
-    via?: TooltipDismissVia;
-  }) => Promise<TooltipResult>;
-  /** Report that a tooltip actually reached the user's eyes (deduped per session). */
-  markTooltipSeen: (tooltipKey: string) => void;
-};
-//#endregion
-//#region src/components/SunboardProvider.d.ts
-type SunboardProviderProps = {
-  spec?: NormalizedSunboardSpec | null;
-  user?: SunboardUser | null;
-  loading?: boolean;
+  /**
+   * How many elements the selector alone matched, inside the box when the
+   * anchor names one. Zero means the selector is wrong, or the box is not on
+   * the page; more than zero means the text filter removed every one of them.
+   */
+  selectorMatches: number;
+  /**
+   * Elements that held the step's text, at most 5, looked for inside the box
+   * when the anchor names one, and across the page when that box is not on it.
+   */
+  seen: SeenElement[];
+}
+interface AnchorFoundReport {
+  guideKey: string;
+  guideRevision: number;
+  stepId: string;
+}
+/** One step of a guide waiting to be seen, for the widget to look for on its page. */
+interface StepCheck {
+  guideKey: string;
+  guideRevision: number;
+  stepId: string;
+  /**
+   * The page the step is on: its own route, or the route of the step before
+   * it that has one. Absent when no step up to it has a route.
+   */
   route?: string;
-  navigate?: NavigateCallback;
+  anchor: Anchor;
+}
+type MissEvidence = Pick<AnchorMissReport, "selectorMatches" | "seen">;
+/** Found, or not found after the wait with what the page held instead. */
+type StepCheckReport = AnchorFoundReport & ({
+  found: true;
+} | ({
+  found: false;
+} & MissEvidence));
+declare const CONTAINERS: readonly ["dialog", "[role=\"dialog\"]", "[role=\"alertdialog\"]", "form", "fieldset", "section", "nav", "main", "aside", "tr", "[role=\"row\"]"];
+type ContainerSelector = (typeof CONTAINERS)[number];
+type SeenContainer = {
+  /** Its role when the role is one of `CONTAINERS`, else its tag. */
+  selector: ContainerSelector;
+  /**
+   * From `aria-labelledby`, `aria-label`, a fieldset's legend, a row's table
+   * caption, or its first heading. At most 80 characters.
+   */
+  name?: string;
+};
+/** From `getBoundingClientRect`, rounded to whole pixels. */
+type SeenBox = {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+};
+/** One element on the page as the widget saw it: a candidate for a missed step, or a line of a census. */
+type SeenElement = {
+  /** Lower case. */
+  tag: string;
+  role?: string;
+  id?: string;
+  /** Its `data-testid`. */
+  testId?: string;
+  ariaLabel?: string;
+  /** An input's `type`. */
+  type?: string;
   /**
-   * Override the runtime API host. Dev-only — leave unset in production so the
-   * SDK targets the hosted Sunboard runtime API. Defaults to
-   * `DEFAULT_RUNTIME_API_URL`.
+   * From `aria-labelledby`, `aria-label`, a form control's labels, a button
+   * input's value, a placeholder, or a title. At most 80 characters.
    */
-  apiUrl?: string;
-  publishableKey?: string;
+  name?: string;
+  /** At most 3. */
+  classes: string[];
   /**
-   * Analytics-provider ids for joining Sunboard's funnel data to your product
-   * analytics. Omit it and installed providers (PostHog) are detected
-   * automatically, on each bootstrap and for a few seconds after, so a
-   * provider that initializes late is still captured. Pass explicit ids to
-   * override detection; pass `false` to disable capture entirely. Captured ids
-   * are inert until the provider is connected to the project in Sunboard.
+   * Text with whitespace collapsed to single spaces, at most 80
+   * characters. Empty for a field, a select, or anything else that shows what
+   * a person typed or chose.
    */
-  identities?: IdentitiesProp;
-  onTrack?: (eventName: TrackEventName, properties?: TrackProperties) => void | Promise<void>;
-  children: ReactNode;
+  text: string;
+  within?: SeenContainer;
+  /** A link's path on this site, without its query or hash. */
+  href?: string;
+  /** Absent when the element has no size. */
+  box?: SeenBox;
 };
-declare function SunboardProvider({
-  spec: specProp,
-  user,
-  loading: loadingProp,
-  route,
-  navigate,
-  apiUrl,
-  publishableKey,
-  identities: identitiesProp,
-  onTrack,
-  children
-}: SunboardProviderProps): react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/components/SunboardHotspots.d.ts
-declare function SunboardHotspots(): react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/components/SunboardTooltips.d.ts
 /**
- * Renders at most one tooltip: the first visible candidate whose target
- * resolves. A candidate whose selector never appears is skipped for the rest
- * of the session (without recording a dismissal — the user rejected nothing),
- * so one stale selector can't block the tooltips behind it.
+ * The interactive elements on one page, or inside the dialog open on it.
+ * Structure and labels only, never what a person typed.
  */
-declare function SunboardTooltips(): react_jsx_runtime0.JSX.Element | null;
-//#endregion
-//#region src/components/SunboardTour.d.ts
-declare function SunboardTour(): react_jsx_runtime0.JSX.Element | null;
+interface PageReport {
+  pathname: string;
+  /** Every element listed sits inside an open dialog, so the page behind it is covered. */
+  dialog: boolean;
+  /** One per fingerprint, in document order, at most 300. */
+  elements: SeenElement[];
+  /** `pageHash(elements, dialog)`. */
+  hash: string;
+}
+/**
+ * What end users did with the guide layer. Behaviour only: which guide, which
+ * step, when. Never anything about the page itself. `preview` and `origin` are
+ * stamped by the server from request headers, so they are absent here.
+ */
+type GuideEventType = "LAUNCHER_OPENED" | "GUIDE_PICKED" | "TOUR_STARTED" | "TOUR_STEP_SEEN" | "TOUR_COMPLETED" | "TOUR_DISMISSED" | "TOUR_RATED" | "TOOLTIP_OPENED" | "TOOLTIP_ACTED" | "ANNOUNCEMENT_SHOWN" | "ANNOUNCEMENT_DISMISSED" | "ANNOUNCEMENT_ACTED" | "BANNER_SHOWN" | "BANNER_DISMISSED";
+/** The stars a visitor gives a tour they finished. */
+type TourRating = 1 | 2 | 3 | 4 | 5;
+/** A rating comes with TOUR_RATED and with nothing else. */
+type GuideEventReport = {
+  guideKey?: string;
+  guideRevision?: number;
+  stepId?: string;
+  route?: string;
+  /** ISO timestamp of when it happened, since events are batched before send. */
+  occurredAt?: string;
+} & ({
+  type: Exclude<GuideEventType, "TOUR_RATED">;
+  rating?: never;
+} | {
+  type: "TOUR_RATED";
+  rating: TourRating;
+});
+/**
+ * ANSWERED is an answer written from the docs and checked against them.
+ * UNSUPPORTED is one the check did not back twice, so the visitor gets the
+ * not-covered reply. NONE found nothing to answer with.
+ * GUIDE offers a tour, with an answer when one was written and backed.
+ */
+type AskOutcome = "GUIDE" | "ANSWERED" | "UNSUPPORTED" | "NONE";
+/** `id` is the stored question's id. `answer` is the whole text to show. */
+interface AskReply {
+  id: string;
+  /** Sent back with the next question so it is read as a follow-up. */
+  conversationId: string;
+  /** This question opened its conversation, so the widget greets the visitor. */
+  firstTurn: boolean;
+  outcome: AskOutcome;
+  /**
+   * Plain text with blank lines between paragraphs, `1.` and `-` lists, and
+   * `**bold**`. Empty when a guide is offered with nothing written.
+   */
+  answer: string;
+  guideKey?: string;
+  /** Set when the answer is the not-covered sentence and the project has a support link. */
+  supportUrl?: string;
+}
+/** What the server is doing while the visitor waits, in this order. */
+type AskStage = "searching" | "writing" | "checking";
 //#endregion
-//#region src/components/Sunboard.d.ts
-declare function SunboardChecklist(): react_jsx_runtime0.JSX.Element | null;
-declare function SunboardSurvey(): react_jsx_runtime0.JSX.Element | null;
-declare const Sunboard: typeof SunboardChecklist & {
-  Checklist: typeof SunboardChecklist;
-  Survey: typeof SunboardSurvey;
-  Hotspots: typeof SunboardHotspots;
-  Tooltips: typeof SunboardTooltips;
-  Tour: typeof SunboardTour;
+//#region ../core/src/anchors.d.ts
+type AnchorPart = {
+  selector: string;
+  /**
+   * Case-sensitive substring match with whitespace ignored, on the element's
+   * text, or on its accessible name when no candidate's text holds it.
+   */
+  text?: string;
+};
+type Anchor = AnchorPart & {
+  within?: AnchorPart;
 };
 //#endregion
-//#region src/hooks/useSunboard.d.ts
-declare function useSunboard(): SunboardContextValue;
+//#region ../core/src/labels.d.ts
+interface Labels {
+  launcher: {
+    /** The pill's text. */
+    open: string;
+    openAria: string;
+    panelAria: string;
+    /** The question box's own label, which the design hides visually. */
+    boxLabel: string;
+    /** In the box before the first question, and once the thread has one. */
+    placeholderFirst: string;
+    placeholderAgain: string;
+    /** Over the suggestions while nothing has been asked. */
+    emptyTitle: string;
+    /** The header button that clears the thread, and the box that asks first. */
+    startOver: string;
+    startOverTitle: string;
+    startOverBody: string;
+    cancel: string;
+    /** The button inside the box. */
+    send: string;
+    /** The pill that scrolls back down to the newest message. */
+    latest: string;
+    /** Over the first answer of a conversation. `name` is the connection's `user.firstName`. */
+    greeting: (name?: string) => string;
+    /** Under an answer that offers a guide, above Show me how. */
+    guideClosing: string;
+    /** The lines the thread gets when a tour it started ends. */
+    tourFinishedAsk: string;
+    tourStopped: (step: number, total: number) => string;
+    /** The stars under a finished tour, and each star's name. */
+    rateTour: string;
+    stars: (count: number) => string;
+    /** The line once the visitor picked a star. */
+    ratingThanks: string;
+    /** The thread's own name, for a screen reader. */
+    conversation: string;
+    /** Said once to a screen reader while a question is out. */
+    writingStatus: string;
+    /** While the question is out, one for each stage the server reports. */
+    stages: {
+      searching: (product: string) => string;
+      writing: string;
+      checking: string;
+      /** After six seconds of waiting. */
+      slow: string;
+    };
+    /** Over the guides listed before the first question, this page's first. */
+    commonQuestions: string;
+    /** The one button under an answer that has a guide behind it. */
+    showMeHow: string;
+    /** Said after a link that opens a new tab, for a screen reader. */
+    newTab: string;
+    /** Over the support link, when there is nothing else to offer. */
+    supportOffer: string;
+    contactSupport: string;
+    rateLimited: string;
+    askAgainIn: (minutes: number) => string;
+    askAgainAt: (time: string) => string;
+    /** No reply at all: the request never landed. The panel puts lostBody under it. */
+    lost: string;
+    lostBody: string;
+    tryAgain: string;
+    /**
+     * What the server answers when there is nothing to show: no guide and no
+     * section, or no guide and an answer the check did not back twice.
+     */
+    notCovered: (product: string) => string;
+    closeAria: string;
+    poweredBy: string;
+  };
+  tour: {
+    back: string;
+    next: string;
+    done: string;
+    closeAria: string;
+    stepCount: (current: number, total: number) => string;
+    /** On the pill that stands in for the launcher while a tour runs. */
+    progress: (current: number, total: number) => string;
+    stop: string;
+  };
+  tooltip: {
+    openAria: (title: string) => string;
+    closeAria: string;
+    showMe: string;
+  };
+  announcement: {
+    remindMe: string;
+    showMe: string;
+    gotIt: string;
+    closeAria: string;
+  };
+  banner: {
+    dismissAria: string;
+  };
+}
+export declare const enLabels: Labels;
+/** Any subset of the labels, group by group. The rest stay English. */
+type LabelOverrides = { [Group in keyof Labels]?: Partial<Labels[Group]>; };
 //#endregion
-//#region src/hooks/useChecklist.d.ts
-type ChecklistViewStep = {
+//#region ../core/src/launcher.d.ts
+interface LauncherGroups {
+  /** Listed guides whose page matches the pathname, by title. */
+  onThisPage: GuideContent[];
+  /** Every other listed guide, by title. A guide with no page lands here. */
+  elsewhere: GuideContent[];
+}
+//#endregion
+//#region src/active-tour.d.ts
+interface ActiveTour {
+  key: string;
+  stepIndex: number;
+}
+type TourEnding = "completed" | "dismissed";
+/** A tour that just ended: how, and the step it was on (1-based) of how many. */
+interface TourEnd {
   key: string;
   title: string;
-  description?: string;
-  badge?: string;
-  actionLabel?: string;
+  ending: TourEnding;
+  step: number;
+  total: number;
+}
+//#endregion
+//#region src/mode.d.ts
+type ThemeModeSetting = ThemeMode | "auto";
+/** The host app's current mode: its own theme marker first, then the OS. */
+export declare function detectThemeMode(): ThemeMode;
+/**
+ * Resolve a mode setting to a concrete mode, live: "auto" tracks host theme
+ * switches (class/attribute flips) and OS preference changes as they happen.
+ * SSR renders light; the first client effect corrects it before anything
+ * user-visible depends on the difference.
+ */
+export declare function useThemeMode(setting: ThemeModeSetting): ThemeMode;
+//#endregion
+//#region src/transport.d.ts
+interface AskQuestion {
+  question: string;
+  pathname: string;
+  /** The conversation the last reply named; left out on the first question. */
+  conversationId?: string;
+}
+/**
+ * What one question got. A refusal (the question was too long, or too many
+ * came from this visitor) is a sentence the visitor reads, not a failure, so
+ * it is a value here rather than a thrown error. `retryAt` comes with the
+ * refusal the cap produces: the time the visitor is free to ask again.
+ */
+type AskResult = {
+  kind: "answer";
+  reply: AskReply;
+} | {
+  kind: "refused";
+  message: string;
+  retryAt?: string;
+};
+interface GuidesTransport {
   /**
-   * True when the user can complete this step by checking it off (the spec
-   * default). False (`manual: false` in the spec) means the step completes
-   * only through its instrumented rule; render its checkbox non-interactive.
+   * The identity a cached bootstrap belongs to. Undefined means this
+   * transport's data is never cached.
    */
-  manuallyCompletable: boolean;
-};
-type ChecklistCompletion = {
-  title: string;
-  subtitle?: string;
-  message?: string;
-  dismissAfterMs?: number;
+  readonly cacheKey?: string;
+  /** The visitor's details from the connection. Never sent anywhere. */
+  readonly user?: VisitorDetails;
+  bootstrap(): Promise<BootstrapAnswer>;
+  /** Persist a user-state mutation; the provider applies it optimistically. */
+  mutate(action: StateAction): Promise<void>;
+  reportAnchorMiss(report: AnchorMissReport): Promise<void>;
+  reportAnchorFound(report: AnchorFoundReport): Promise<void>;
+  /** Whether a step of a guide waiting to be seen was on the page the visitor is on. */
+  stepCheck(report: StepCheckReport): Promise<void>;
+  /**
+   * Usage telemetry, batched by the provider. Fire-and-forget by contract:
+   * analytics must never delay or fail anything the user is doing.
+   */
+  recordEvents(events: GuideEventReport[]): Promise<void>;
+  /**
+   * Ask one question about the page the visitor is on. Optional because a
+   * MemoryTransport with no script has none, which is how the appearance
+   * canvas gets a panel with a box that does nothing. `HttpTransport` always
+   * has it. `onStage` hears each stage the server starts, in order, before
+   * the result settles.
+   */
+  ask?(question: AskQuestion, signal: AbortSignal, onStage: (stage: AskStage) => void): Promise<AskResult>;
+  /**
+   * What is on the page the visitor is looking at. Optional: without it the
+   * provider never looks at the page.
+   */
+  reportPage?(report: PageReport): Promise<void>;
+}
+/**
+ * A scripted reply. The transport's own conversation id fills in when it names
+ * none, and `firstTurn` is true when the question named no conversation.
+ */
+type ScriptedReply = Omit<AskReply, "conversationId" | "firstTurn"> & {
+  conversationId?: string;
+  firstTurn?: boolean;
 };
-type UseChecklistResult = {
-  visible: boolean;
-  title?: string;
-  subtitle?: string;
-  steps: ChecklistViewStep[];
-  completedStepKeys: ReadonlySet<string>;
-  completedCount: number;
-  totalSteps: number;
-  remainingCount: number;
-  progress: number;
-  isCompleted: (key: string) => boolean;
-  hasAction: (step: ChecklistViewStep) => boolean;
-  startStep: (step: ChecklistViewStep) => void;
-  /**
-   * Mark the step complete because the user checked it off. A no-op for
-   * steps that are not manually completable or already complete.
-   */
-  completeStep: (step: ChecklistViewStep) => void;
-  completion?: ChecklistCompletion;
-  dismissCompletion: () => void;
+/**
+ * What a MemoryTransport answers with. Throwing from it stands for a server
+ * that could not be reached at all. `stagesMs` is the wait after each stage,
+ * `gapMs` when it is left out.
+ */
+type AskScript = (asked: AskQuestion) => {
+  reply: ScriptedReply;
+  stagesMs?: number;
+} | {
+  refused: string;
+  retryAt?: string;
 };
-declare function useChecklist(): UseChecklistResult;
+interface MemoryTransportOptions {
+  cacheKey?: string;
+  user?: VisitorDetails;
+  /** Opt in to the question box. Without a script there is no `ask` at all. */
+  ask?: AskScript;
+  /** Opt in to page reports. Without it there is no `reportPage`, and nothing looks at the page. */
+  census?: boolean;
+  /**
+   * The wait before a refusal, and after each stage of a reply unless the
+   * script names its own, so every stage of the waiting can be looked at.
+   */
+  gapMs?: number;
+}
+export declare class MemoryTransport implements GuidesTransport {
+  private readonly data;
+  readonly misses: AnchorMissReport[];
+  readonly found: AnchorFoundReport[];
+  readonly stepChecks: StepCheckReport[];
+  readonly mutations: StateAction[];
+  readonly events: GuideEventReport[];
+  readonly questions: AskQuestion[];
+  readonly pages: PageReport[];
+  readonly cacheKey: string | undefined;
+  readonly user: VisitorDetails | undefined;
+  readonly ask?: GuidesTransport["ask"];
+  readonly reportPage?: GuidesTransport["reportPage"];
+  constructor(data: BootstrapData, options?: MemoryTransportOptions);
+  bootstrap(): Promise<BootstrapData>;
+  mutate(action: StateAction): Promise<void>;
+  reportAnchorMiss(report: AnchorMissReport): Promise<void>;
+  reportAnchorFound(report: AnchorFoundReport): Promise<void>;
+  stepCheck(report: StepCheckReport): Promise<void>;
+  recordEvents(events: GuideEventReport[]): Promise<void>;
+}
+/** The hosted runtime API. Overridden only for self-hosting or local dev. */
+export declare const DEFAULT_SUNBOARD_API_URL = "https://api.sunboardhq.com";
+/**
+ * Zero-code dark preview. The dashboard links the admin to their own app with
+ * `?sunboardPreview=<key>`; the SDK stores the key, strips the param from the
+ * URL, and sends the key on every runtime request from then on, so drafts stay
+ * visible in that browser until `?sunboardPreview=off` or the key is rotated.
+ * Nothing about preview ever enters the customer's source.
+ */
+export declare const PREVIEW_PARAM = "sunboardPreview";
+export declare const PREVIEW_KEY_STORAGE = "sunboard:preview-key";
+export declare const PREVIEW_EXPIRY_STORAGE = "sunboard:preview-until";
+/** The visitor's details. They stay in the browser: none of them is sent to Sunboard. */
+interface VisitorDetails {
+  /** The visitor's first name, as you want the assistant to greet them ("Hey Sam,"). */
+  firstName?: string;
+}
+interface HttpTransportConfig {
+  /** The workspace's publishable key. Safe in client bundles. */
+  publishableKey: string;
+  /** Customer-supplied end-user id. */
+  userId: string;
+  /** The visitor's details, kept in the browser. */
+  user?: VisitorDetails;
+  /** Origin of the runtime API. Defaults to the hosted API. */
+  baseUrl?: string;
+  /**
+   * Admin-only: unlocks paused guides for preview. Normally NOT set in code:
+   * the preview bookmarklet delivers it via localStorage instead (see
+   * PREVIEW_KEY_STORAGE). The prop exists for tests and unusual setups.
+   */
+  previewKey?: string;
+}
+export declare class HttpTransport implements GuidesTransport {
+  private readonly config;
+  private readonly baseUrl;
+  private readonly previewKey;
+  readonly cacheKey: string | undefined;
+  readonly user: VisitorDetails | undefined;
+  constructor(config: HttpTransportConfig);
+  private headers;
+  private request;
+  bootstrap(): Promise<BootstrapAnswer>;
+  mutate(action: StateAction): Promise<void>;
+  reportAnchorMiss(report: AnchorMissReport): Promise<void>;
+  reportAnchorFound(report: AnchorFoundReport): Promise<void>;
+  stepCheck(report: StepCheckReport): Promise<void>;
+  recordEvents(events: GuideEventReport[]): Promise<void>;
+  reportPage(report: PageReport): Promise<void>;
+  ask(asked: AskQuestion, signal: AbortSignal, onStage: (stage: AskStage) => void): Promise<AskResult>;
+}
 //#endregion
-//#region src/hooks/useSurvey.d.ts
-type SurveyViewOption = {
-  value: string;
-  label: string;
-};
-type SurveyViewQuestion = {
-  key: string;
-  prompt: string;
-  type: SurveyQuestionType;
-  required: boolean;
-  options: SurveyViewOption[];
-};
-type SurveyViewStep = {
-  title?: string;
-  subtitle?: string;
-  questions: SurveyViewQuestion[];
-};
-type UseSurveyResult = {
-  visible: boolean;
-  title?: string;
-  subtitle?: string;
-  /** Every question across all steps — for all-at-once renderers (the built-in modal). */
-  questions: SurveyViewQuestion[];
-  /** The authored step grouping (one question per step by default). */
-  steps: SurveyViewStep[];
-  /** Hook-owned navigation. */
-  stepIndex: number;
-  totalSteps: number;
-  currentStep?: SurveyViewStep;
-  progress: number;
-  isFirstStep: boolean;
-  isLastStep: boolean;
-  /** True when the current step's required questions are answered. */
-  canAdvance: boolean;
-  /** Advance to the next step, or submit on the last step. */
-  next: () => void;
-  back: () => void;
-  answers: Record<string, unknown>;
-  setAnswer: (key: string, value: string) => void;
-  toggleAnswer: (key: string, value: string) => void;
-  isAnswered: (key: string) => boolean;
-  /** True when every required question (across all steps) is answered. */
-  canSubmit: boolean;
-  submitting: boolean;
+//#region src/provider.d.ts
+interface GuidesApi {
+  ready: boolean;
+  /** The workspace's organization has no plan, so nothing renders. */
+  off: boolean;
   error: string | null;
-  submit: () => Promise<void>;
-};
-declare function useSurvey(): UseSurveyResult;
+  getGuide: (key: string) => GuideContent | undefined;
+  /** Every bootstrapped guide; the politeness layer arbitrates push types from it. */
+  allGuides: () => GuideContent[];
+  productName: string;
+  /** A tooltip's pin shows until the user opens it once. */
+  hasOpenedTooltip: (guideKey: string) => boolean;
+  markTooltipOpened: (guideKey: string) => void;
+  /** Ignored for a guide with no steps: there would be nothing to show. */
+  launchTour: (guideKey: string, stepIndex?: number) => void;
+  activeTour: ActiveTour | null;
+  /** Show another step of the running tour. Ignored when none is running. */
+  setTourStep: (stepIndex: number) => void;
+  /** End the running tour. The event that says how it ended goes with it. */
+  endTour: (ending: TourEnding) => void;
+  /** Hear each tour end, however it ended. Returns the call that stops listening. */
+  onTourEnd: (listener: (ended: TourEnd) => void) => () => void;
+  /**
+   * The identity anything kept in the browser belongs to: the transport's
+   * `cacheKey`. Undefined for a preview session, which keeps nothing.
+   */
+  cacheKey: string | undefined;
+  /** The visitor's first name from the connection, for the assistant's greeting. */
+  firstName: string | undefined;
+  reportAnchorMiss: GuidesTransport["reportAnchorMiss"];
+  /** Sent only for a step that missed before, once per step and revision per page load. */
+  reportAnchorFound: (report: AnchorFoundReport) => void;
+  /**
+   * Ask one question. Undefined when the transport has none or Sunboard is
+   * off, which is how `useLauncher` knows whether to offer the box at all. `HttpTransport`
+   * always has it; a `MemoryTransport` needs a script.
+   */
+  ask: GuidesTransport["ask"];
+  /** Record a usage event. Batched, fire-and-forget, never awaited. */
+  track: (event: GuideEventReport) => void;
+  /**
+   * Navigate the host app. Uses the customer's `navigate` prop (e.g.
+   * router.push) and falls back to a full page load. Tours use it to reach a
+   * step's route.
+   */
+  navigate: (path: string) => void;
+}
+interface SunboardProviderProps {
+  children: ReactNode;
+  /** Connection to the runtime API; or pass a transport directly (tests, demos). */
+  connection?: HttpTransportConfig;
+  transport?: GuidesTransport;
+  /**
+   * How the SDK navigates your app (e.g. Next: `(path) => router.push(path)`).
+   * Without it, cross-route tour steps fall back to a full page load; tours
+   * survive that via sessionStorage, but SPA navigation is smoother.
+   */
+  navigate?: (path: string) => void | Promise<void>;
+  /**
+   * Labels are client-side by design: any subset overrides the English
+   * defaults. The customer owns per-user language policy; the server never
+   * sends strings.
+   */
+  labels?: LabelOverrides;
+  /**
+   * Fallbacks only. Theme and settings are configured in the Sunboard
+   * dashboard and delivered by the API; when the server sends a value, it
+   * wins, so dashboard edits reach the app without a deploy. These props
+   * cover demos and workspaces that have not configured appearance yet.
+   */
+  settings?: ComponentSettings;
+  theme?: Theme;
+  /**
+   * Light/dark selection. Default "auto": follow the host app's own theme
+   * marker (a `dark`/`light` class or data attribute on <html>/<body>, the
+   * Tailwind/next-themes idiom), falling back to the OS preference, and track
+   * changes live. Pass "light" or "dark" to wire the SDK to your own theme
+   * state instead.
+   */
+  mode?: ThemeModeSetting;
+  /**
+   * Say what the SDK is doing in the browser console: what bootstrap
+   * delivered, each tour step and what it waits for, whether an anchor
+   * matched, and why a tour ended. For wiring up and debugging; off by
+   * default and silent. `?sunboardDebug=1` on the page URL turns it on for
+   * that page load.
+   */
+  debug?: boolean;
+}
+export declare function SunboardProvider(props: SunboardProviderProps): import("react").JSX.Element;
 //#endregion
-//#region src/hooks/useTooltips.d.ts
-type TooltipView = {
-  key: string;
+//#region src/thread.d.ts
+/** Why a question has no reply. Each takes the reply's place in the thread. */
+type AskFailure = {
+  kind: "lost";
+} | {
+  kind: "rateLimited";
+  retryAt: string;
+} | {
+  kind: "refused";
+  message: string;
+};
+/**
+ * One entry in the thread. A question is always followed by the one thing it
+ * got (`waiting`, `reply` or `error`), which names it in `questionId`. A
+ * `tour` line follows the reply whose Show me how started that tour, and
+ * keeps the stars the visitor gave it once they finished it.
+ */
+type Message = {
+  kind: "question";
+  id: string;
+  text: string;
+} | {
+  kind: "waiting";
+  id: string;
+  questionId: string;
+  stage: AskStage | null;
+  since: number;
+} | {
+  kind: "reply";
+  id: string;
+  questionId: string;
+  reply: AskReply;
+  toured: boolean;
+} | {
+  kind: "error";
+  id: string;
+  questionId: string;
+  failure: AskFailure;
+} | {
+  kind: "tour";
+  id: string;
+  guideKey: string;
   title: string;
-  body?: string;
-  /** CSS selector of the element the tooltip points at. */
-  target: string;
-  placement: SunboardPlacement;
-  /** True when a tour action is attached; `engage` starts it. */
-  hasAction: boolean;
-  actionLabel?: string;
-  /** True when the user asked for this tooltip via a checklist step. */
-  requested: boolean;
+  ending: TourEnding;
+  step: number;
+  total: number;
+  rating?: TourRating;
 };
-type UseTooltipsResult = {
+//#endregion
+//#region src/hooks.d.ts
+export declare function useGuidesApi(): GuidesApi;
+interface LauncherOptions {
+  /**
+   * Keep the thread in session storage for the rest of the visit. On by
+   * default; nothing is kept for a preview session either way.
+   */
+  remember?: boolean;
+}
+interface LauncherList extends LauncherGroups {
+  ready: boolean;
+  tourRunning: boolean;
+  /** New functions on every render, so call them from an event handler. */
+  opened: () => void;
+  /**
+   * Start a listed guide's tour. Pass the id of the reply that offered it,
+   * and the thread gets a line after that reply when the tour ends.
+   */
+  start: (guideKey: string, replyId?: string) => void;
+  /** The thread, oldest first. Each hook instance holds its own. */
+  messages: readonly Message[];
+  /** A question is out and its reply has not come back yet. */
+  waiting: boolean;
+  /** When the visitor may ask again, while the newest question was capped. */
+  rateLimitedUntil: string | undefined;
+  /**
+   * A tour this thread started is running. It turns false when that tour
+   * ends, the moment a panel would come back.
+   */
+  handedOff: boolean;
   /**
-   * Tooltips that qualify for the current route (undismissed, or explicitly
-   * requested). Render ONE at a time — the first whose target you can anchor.
+   * Ask a question, as a follow-up when the thread has one. Undefined on a
+   * transport with no `ask` and while Sunboard is off. Ignored when blank,
+   * while waiting, and while capped.
    */
-  tooltips: TooltipView[];
-  /** Report that a tooltip is actually on screen (deduped per session). */
-  markSeen: (key: string) => void;
-  /** Close without acting — the tooltip never shows again. */
-  dismiss: (key: string) => void;
-  /** Take the tooltip's action: starts its tour and retires the tooltip. */
-  engage: (key: string) => void;
+  ask: ((question: string) => void) | undefined;
+  /** Ask the newest question again when nothing came back for it. */
+  retry: () => void;
+  /** Clear the thread, its stored copy and its conversation. */
+  startOver: () => void;
   /**
-   * Report that the user clicked the tooltip's target element: the nudge
-   * worked, so this retires the tooltip and records the engagement.
+   * Give a finished tour's line its stars and send them as `TOUR_RATED`.
+   * Ignored for a stopped tour and for a line already rated.
    */
-  markTargetClicked: (key: string) => void;
+  rate: (lineId: string, rating: TourRating) => void;
+}
+export declare function useLauncher({ remember }?: LauncherOptions): LauncherList;
+/** One guide's content plus launchTour; call with no key for launch-only. */
+export declare function useGuide(key?: string): {
+  guide: GuideContent | undefined;
+  launchTour: (guideKey: string) => void;
+};
+/**
+ * Record a usage event. Public so a customer's own UI built on these hooks
+ * reports the same numbers the prebuilt components do.
+ */
+export declare function useTrack(): GuidesApi["track"];
+/** Structure toggles for prebuilt components; custom UIs may ignore them. */
+export declare function useComponentSettings(): ComponentSettings;
+/** Built-in UI strings; override via SunboardProvider. */
+export declare function useLabels(): Labels;
+/** Theme + mode + ready-to-apply CSS variables (--sb-*). */
+export declare function useTheme(): {
+  theme: Theme;
+  mode: ThemeMode;
+  cssVars: Record<string, string>;
+};
+//#endregion
+//#region src/anchors.d.ts
+type TieBreak = "open dialog" | "previous step's box" | "document order";
+type AnchorMatch = {
+  element: null;
+  matchCount: 0;
+} | {
+  /** Any element, so an anchor on an icon (an <svg>) resolves like one on a button. */
+  element: Element;
+  /** How many separate elements matched; >1 means the anchor is ambiguous. */
+  matchCount: number;
+  chosenBy: TieBreak;
 };
+interface Preference {
+  dialog: boolean;
+  near: Element | null;
+}
 /**
- * Headless counterpart of `<SunboardTooltips>`: the same visibility, seen,
- * dismissal, and engagement semantics with rendering left to the host.
+ * Resolve an anchor against the live DOM: its boxes first, then the element
+ * inside them. When several elements match an anchor with no box, the first
+ * rule that keeps any of them picks, in document order.
  */
-declare function useTooltips(): UseTooltipsResult;
+export declare function resolveAnchor(anchor: Anchor, root?: ParentNode, prefer?: Preference): AnchorMatch;
+interface AnchorElementState {
+  element: Element | null;
+  timedOut: boolean;
+}
+/**
+ * Wait for an anchor's element (UIs render late; routes change), and keep
+ * watching it: when the host replaces the node, the state moves to the new
+ * one. Ported from v1 useTargetElement, extended with the text predicate and
+ * an onMiss hook.
+ */
+export declare function useAnchorElement(anchor: Anchor | null, enabled: boolean, options?: {
+  timeoutMs?: number;
+  onMiss?: (anchor: Anchor, evidence: MissEvidence) => void;
+  prefer?: Preference;
+}): AnchorElementState;
+//#endregion
+//#region src/theme.d.ts
+/** The only bridge between theme config and styling. */
+export declare function themeToCssVars(theme: Theme, mode: ThemeMode): Record<string, string>;
+//#endregion
+//#region src/url-params.d.ts
+export declare const LAUNCH_PARAM = "sunboardLaunch";
+//#endregion
+//#region src/routes.d.ts
+/** The host app's current pathname, updating on SPA navigation. */
+export declare function useCurrentPathname(): string;
+//#endregion
+//#region src/politeness.d.ts
+export declare function hasSeen(guideKey: string): boolean;
+export declare function markSeen(guideKey: string): void;
+export declare function cooldownActive(now?: number): boolean;
+/** Any dismissal of a push surface quiets all push surfaces for a while. */
+export declare function recordDismissal(cooldownMs?: number, now?: number): void;
+/**
+ * Choose the single push surface allowed right now, or null. `tourRunning`
+ * suppresses all push surfaces (one thing on screen at a time).
+ */
+export declare function pickPushGuide(guides: GuideContent[], options?: {
+  tourRunning: boolean;
+  now?: number;
+}): GuideContent | null;
+//#endregion
+//#region src/components/SunboardOverlay.d.ts
+interface SunboardOverlayProps {
+  /** Mount the prebuilt pill. Pass false when your own UI is built on useLauncher. */
+  launcher?: boolean;
+}
+export declare function SunboardOverlay({ launcher }?: SunboardOverlayProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/Launcher.d.ts
+interface LauncherProps {
+  /**
+   * Render the panel open and in normal flow, never hidden: the appearance
+   * canvas in the Sunboard app. Nothing is kept in storage.
+   */
+  inline?: boolean;
+}
+export declare function Launcher({ inline }?: LauncherProps): import("react").JSX.Element | null;
 //#endregion
-export { type ChecklistViewStep, type RuntimeBootstrapRequest, type RuntimeBootstrapResponse, type RuntimeExperience, type RuntimeProgress, type RuntimeTrackRequest, type RuntimeTrackResponse, type StepResult, Sunboard, SunboardChecklist, type SunboardContextValue, SunboardHotspots, SunboardProvider, type SunboardProviderProps, SunboardRuntimeApiError, SunboardRuntimeClient, type SunboardRuntimeClientOptions, SunboardSurvey, SunboardTooltips, SunboardTour, type SunboardUser, type SurveyResult, type SurveyViewOption, type SurveyViewQuestion, type SurveyViewStep, type TooltipResult, type TooltipView, type TourResult, type TrackProperties, type TrackResult, type UseChecklistResult, type UseSurveyResult, type UseTooltipsResult, type VisibleSunboardTooltip, useChecklist, useSunboard, useSurvey, useTooltips };
-//# sourceMappingURL=index.d.mts.map
+export type { ActiveTour, Anchor, AnchorElementState, AnchorMatch, AskFailure, AskOutcome, AskQuestion, AskReply, AskResult, AskScript, AskStage, BootstrapAnswer, BootstrapData, BootstrapOff, ComponentSettings, GuideContent, GuideStep, GuideType, GuidesApi, GuidesTransport, HttpTransportConfig, LabelOverrides, Labels, LauncherList, LauncherOptions, LauncherProps, MemoryTransportOptions, Message, Palette, PinPosition, ScriptedReply, StepPlacement, StepPrimitive, SunboardOverlayProps, SunboardProviderProps, Theme, ThemeMode, ThemeModeSetting, TourEnd, TourEnding, UserState, VisitorDetails };