@guidelytech/react-native 0.0.0-stage → 0.4.1

package/dist/index.d.cts

@@ -0,0 +1,718 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { SelectorStrategy, MessengerConfig, MessengerMessage, MessengerConversation, SdkArticlesResponse, ResourceCenterArticle, PublishedGuide, ProjectTheme, GuideStep, SdkConfigResponse, ChecklistTask, SdkEvent, TargetingContext, StepButton, ResourceCenterConfig, Placement } from '@guidelytech/shared';
+export { GuideStep, PublishedGuide, SdkConfigResponse } from '@guidelytech/shared';
+import { KeyValueStore, ChecklistProgressState, GuidelyEnvironment, ConsentState, GuidelyUser, GuidelyAccount, GuideLocalState, SessionState } from '@guidelytech/sdk-core/headless';
+export { ChecklistProgressState, ConsentState, GuidelyAccount, GuidelyEnvironment, GuidelyUser } from '@guidelytech/sdk-core/headless';
+import { ViewProps, StyleProp, ViewStyle, View, GestureResponderEvent } from 'react-native';
+
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A mounted `<GuidelyTarget>`; `measure` returns its frame in window coordinates. */
+interface TargetHandle {
+    measure(): Promise<Rect | null>;
+    /**
+     * Screen the view lives on (from `GuidelyScreenScope`). Navigators keep inactive screens mounted
+     * and laid out, so a target on another screen would otherwise measure as visible.
+     */
+    screen?: string | null;
+}
+/**
+ * The Guidely ids a step target can match on mobile, in order: `guidely-id` and `id` strategies
+ * by value, CSS / data-attribute strategies when they name a single id (`#x`, `[data-guidely-id=x]`).
+ */
+declare function targetIdsFor(selectors: SelectorStrategy[]): string[];
+/** Registry of mounted targets. One per client; `<GuidelyTarget>` registers itself on mount. */
+declare class TargetRegistry {
+    private readonly targets;
+    private readonly changeListeners;
+    private readonly tapListeners;
+    private viewport;
+    private screen;
+    register(id: string, handle: TargetHandle): () => void;
+    /** Window size used for the on-screen check. */
+    setViewport(width: number, height: number): void;
+    /** The current screen; targets scoped to other screens are treated as hidden. */
+    setScreen(name: string | null): void;
+    has(id: string): boolean;
+    ids(): string[];
+    /** Call when a target's layout may have changed (onLayout, scroll). */
+    changed(): void;
+    onChange(cb: () => void): () => void;
+    tapped(id: string): void;
+    onTap(cb: (id: string) => void): () => void;
+    /** Frame of a visible target (the most recently mounted visible one when an id is used twice), else null. */
+    measure(id: string): Promise<Rect | null>;
+    private measureHandle;
+    /** First of `ids` that is mounted and visible. */
+    resolve(ids: string[]): Promise<{
+        id: string;
+        rect: Rect;
+    } | null>;
+    /** Resolves when one of `ids` is visible; `timeoutMs` 0 waits forever. Re-checks on registry changes and every 300ms. */
+    waitFor(ids: string[], options: {
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        id: string;
+        rect: Rect;
+    }>;
+}
+
+type GuideStatus = "idle" | "running" | "waiting_url" | "waiting_target" | "ended";
+
+/**
+ * Scout messenger for React Native: the transport of `@guidelytech/sdk-core`'s messenger-api plus
+ * the conversation state the web widget keeps, as a headless store the overlay renders.
+ */
+type MessengerTab = "home" | "messages" | "help";
+type MessengerView = {
+    kind: "tab";
+    tab: MessengerTab;
+} | {
+    kind: "thread";
+    conversationId: string | null;
+} | {
+    kind: "article";
+    articleId: string;
+    from: MessengerView;
+};
+interface MessengerThread {
+    conversation: MessengerConversation | null;
+    messages: MessengerMessage[];
+    /** Reply text streamed so far, by message id (before the final `done` message arrives). */
+    streaming: Record<string, string>;
+    sending: boolean;
+    error: string | null;
+    /** Text to pre-fill in the composer (`showNewMessage(text)`). */
+    draft: string;
+}
+interface MessengerSnapshot {
+    config: MessengerConfig;
+    open: boolean;
+    view: MessengerView;
+    conversations: MessengerConversation[];
+    thread: MessengerThread | null;
+    /** Conversations with unread replies. */
+    unread: number;
+    articles: SdkArticlesResponse | null;
+    article: ResourceCenterArticle | null;
+}
+/** Incremental `text/event-stream` parser: `event:` + single-line JSON `data:`, `:` comments ignored. */
+declare function createSseParser(onEvent: (event: string, data: unknown) => void): {
+    feed(chunk: string): void;
+    end(): void;
+};
+interface HttpResult {
+    status: number;
+    /** JSON body when the server answered with JSON. */
+    json: unknown;
+}
+/**
+ * POST that streams server-sent events as they arrive. React Native's `fetch` cannot read a body
+ * incrementally, but its `XMLHttpRequest` reports partial `responseText` on progress events.
+ */
+type StreamPost = (url: string, headers: Record<string, string>, body: unknown, onChunk: (text: string) => void) => Promise<HttpResult & {
+    streamed: boolean;
+}>;
+interface MessengerDeps {
+    baseUrl: string;
+    publicKey: string;
+    store: KeyValueStore;
+    fetch: typeof fetch;
+    streamPost: StreamPost;
+    anonymousId: () => string;
+    userId: () => string | null;
+    /** Screen path to attach to new conversations (omitted when URL collection is off). */
+    pageUrl: () => string | undefined;
+    onOpen: () => void;
+    onMessage: (message: MessengerMessage, conversation: MessengerConversation) => void;
+    onStartGuide: (key: string) => void;
+    onError: (err: unknown) => void;
+    /** Poll intervals (ms): open thread, and unread badge otherwise. */
+    pollMs?: {
+        thread: number;
+        background: number;
+    };
+}
+declare class Messenger {
+    private readonly deps;
+    private snapshot;
+    private readonly listeners;
+    private threadTimer;
+    private backgroundTimer;
+    private foreground;
+    private destroyed;
+    private readonly poll;
+    constructor(config: MessengerConfig, deps: MessengerDeps);
+    getSnapshot(): MessengerSnapshot;
+    subscribe(cb: () => void): () => void;
+    private set;
+    private setThread;
+    updateConfig(config: MessengerConfig): void;
+    private stored;
+    private remember;
+    private tokenFor;
+    /** Forgets every conversation (logout). */
+    forgetAll(): void;
+    private url;
+    private headers;
+    private request;
+    open(tab?: MessengerTab): void;
+    close(): void;
+    setTab(tab: MessengerTab): void;
+    private onView;
+    /** Opens a new thread (optionally pre-filling the composer). */
+    showNewMessage(text?: string): void;
+    openConversation(id: string): Promise<void>;
+    back(): void;
+    private upsertConversation;
+    private markRead;
+    refreshConversations(): Promise<void>;
+    /** Sends the composer text: starts a conversation or posts to the open one. Streams Scout's reply. */
+    send(text: string): Promise<void>;
+    private addMessage;
+    handoff(): Promise<void>;
+    rate(rating: number): Promise<void>;
+    startGuide(key: string): void;
+    loadArticles(): Promise<void>;
+    openArticle(id: string): Promise<void>;
+    search(q: string): Promise<ResourceCenterArticle[]>;
+    /** Called with app foreground/background changes; polling only runs in the foreground. */
+    setForeground(active: boolean): void;
+    private startBackgroundPolling;
+    private scheduleThreadPoll;
+    private stopThreadPolling;
+    private pollThread;
+    destroy(): void;
+}
+
+/**
+ * AsyncStorage-compatible key/value storage (`@react-native-async-storage/async-storage`,
+ * `expo-secure-store` wrappers, MMKV adapters…). Synchronous implementations work too.
+ */
+interface GuidelyStorage {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem(key: string): Promise<void> | void;
+}
+/** Device facts the engine needs. The provider fills these in from React Native APIs. */
+interface DeviceEnvironment {
+    platform: "ios" | "android";
+    deviceType: "mobile" | "tablet";
+    locale?: string;
+    appVersion?: string;
+}
+interface GuidelyOptions {
+    /** Environment public key, e.g. `pk_dev_…`. Not a secret. */
+    projectId: string;
+    environment?: GuidelyEnvironment;
+    /** Base URL of your Guidely deployment, e.g. `https://guidelytech.com`. */
+    apiUrl?: string;
+    /**
+     * Where identity, cached config and queued events are persisted. Pass AsyncStorage
+     * (`@react-native-async-storage/async-storage`); without it state lasts only for the app session.
+     */
+    storage?: GuidelyStorage;
+    debug?: boolean;
+    /** Send analytics events (default `true`). Guides still render when disabled. */
+    analytics?: boolean;
+    consent?: ConsentState;
+    /** Host app version for `app.version` targeting rules. */
+    appVersion?: string;
+    /** How often to refresh the published config (default 5 minutes). */
+    configRefreshMs?: number;
+    /** Overrides for the project theme. */
+    theme?: Partial<ProjectTheme>;
+    /** Identify this user as soon as the client initialises. */
+    user?: GuidelyUser;
+    /** Handles relative and custom-scheme URLs from buttons, links and tasks (deep links, in-app routes). Return `true` when handled. */
+    onNavigate?: (url: string) => boolean | void;
+    onError?: (error: Error) => void;
+    /** Custom fetch (tests / polyfills). */
+    fetch?: typeof fetch;
+    /** Show the floating checklist launcher (default `true`). */
+    showChecklistLauncher?: boolean;
+    /** Show a floating resource-center launcher (default `false`; call `openResourceCenter()` instead). */
+    showResourceCenterLauncher?: boolean;
+    /** Show the Scout chat bubble when the messenger is on for this platform (default `true`). */
+    showMessengerLauncher?: boolean;
+}
+interface GuideStepInfo {
+    guide: PublishedGuide;
+    stepId: string;
+    stepIndex: number;
+}
+interface GuidelyEvents {
+    ready: (config: SdkConfigResponse) => void;
+    config: (config: SdkConfigResponse) => void;
+    "guide:start": (guide: PublishedGuide) => void;
+    "guide:step": (info: GuideStepInfo) => void;
+    "guide:complete": (guide: PublishedGuide) => void;
+    "guide:dismiss": (guide: PublishedGuide) => void;
+    "guide:skip": (guide: PublishedGuide) => void;
+    "checklist:task": (info: {
+        guide: PublishedGuide;
+        task: ChecklistTask;
+        progress: ChecklistProgressState;
+    }) => void;
+    "checklist:complete": (guide: PublishedGuide) => void;
+    "survey:submit": (info: {
+        guide: PublishedGuide;
+        answers: Record<string, unknown>;
+        responseId: string;
+    }) => void;
+    "resource-center:open": () => void;
+    /** The Scout messenger opened. */
+    "messenger:open": () => void;
+    /** Scout or a teammate replied in a conversation. */
+    "conversation:message": (info: {
+        message: MessengerMessage;
+        conversation: MessengerConversation;
+    }) => void;
+    error: (error: Error) => void;
+    track: (event: SdkEvent) => void;
+    identify: (info: {
+        userId: string | null;
+        anonymousId: string;
+    }) => void;
+}
+type GuidelyEventName = keyof GuidelyEvents;
+/** A rendered step, as the overlay sees it. */
+interface StepView {
+    /** Stable per rendered step; changes when the step changes. */
+    key: string;
+    guide: PublishedGuide;
+    step: GuideStep;
+    index: number;
+    total: number;
+    canGoBack: boolean;
+    /** Guidely id of the resolved target, or null for unanchored / fallback-to-modal steps. */
+    targetId: string | null;
+    asModal: boolean;
+    /** Hotspots render collapsed until tapped. */
+    expanded: boolean;
+}
+interface ChecklistView {
+    guide: PublishedGuide;
+    progress: ChecklistProgressState;
+    open: boolean;
+}
+interface SurveyView {
+    key: string;
+    guide: PublishedGuide;
+    submitted: boolean;
+}
+/** Everything the overlay renders. Immutable snapshots; a new object on every change. */
+interface UiState {
+    steps: StepView[];
+    checklists: ChecklistView[];
+    survey: SurveyView | null;
+    resourceCenterOpen: boolean;
+    theme: Partial<ProjectTheme>;
+    /** Scout is on for this platform; the overlay renders the messenger (see `client.getMessenger()`). */
+    messenger: boolean;
+}
+
+declare const SDK_NAME = "@guidelytech/react-native";
+declare const SDK_VERSION = "0.4.1";
+declare const DEFAULT_API_URL = "https://guidelytech.com";
+/** Host-platform services the engine needs; the provider supplies React Native implementations. */
+interface PlatformBridge {
+    device: DeviceEnvironment;
+    /** Opens an external URL (React Native `Linking.openURL`). */
+    openExternal(url: string): void;
+}
+/** Mobile sessions persist across launches and expire after the configured inactivity timeout. */
+interface MobileSession extends SessionState {
+    lastActiveAt: string;
+}
+/**
+ * The React Native Guidely client: the web SDK's engine (config, identity, events, triggers,
+ * frequency, checklists, surveys) with screens instead of URLs and `<GuidelyTarget>` views instead
+ * of DOM elements. The overlay renders whatever {@link getUiState} describes.
+ */
+declare class GuidelyClient {
+    readonly options: Readonly<GuidelyOptions & {
+        environment: NonNullable<GuidelyOptions["environment"]>;
+        apiUrl: string;
+        analytics: boolean;
+        configRefreshMs: number;
+        debug: boolean;
+    }>;
+    readonly targets: TargetRegistry;
+    private readonly bridge;
+    private readonly api;
+    private readonly store;
+    private readonly emitter;
+    private queue;
+    private config;
+    private configFetchedAt;
+    private etag;
+    private anonymousId;
+    private user;
+    private state;
+    private session;
+    private consent;
+    private readyPromise;
+    private hydrated;
+    private pending;
+    private isReady;
+    private destroyed;
+    private active;
+    private activeSurvey;
+    private queued;
+    private flows;
+    private checklists;
+    private expanded;
+    private surveyView;
+    private resourceCenterOpen;
+    private cleanups;
+    private timers;
+    private visibilityWatchers;
+    private firedDelays;
+    private firstVisit;
+    private screenName;
+    private lastAudiences;
+    private backgroundedAt;
+    private messenger;
+    private ui;
+    private uiListeners;
+    private readonly customListeners;
+    private readonly eventBus;
+    constructor(options: GuidelyOptions, bridge: PlatformBridge);
+    /** Loads persisted state and config, identifies the stored user and evaluates triggers. Idempotent. */
+    init(): Promise<void>;
+    ready(): Promise<void>;
+    private bootstrap;
+    private whenHydrated;
+    private fetchConfig;
+    private wireTimers;
+    /** Re-fetches the published config and re-evaluates triggers. */
+    refresh(): Promise<void>;
+    /** Called by the provider with React Native `AppState` changes. */
+    setAppState(state: "active" | "background" | "inactive" | string): void;
+    private sessionExpired;
+    /** Tears everything down. Create a new client to start again. */
+    destroy(): void;
+    /** Identifies the end user and loads server-held state (audiences, guide history, checklist progress). */
+    identify(userId: string, traits?: Record<string, unknown>, account?: GuidelyAccount): Promise<void>;
+    private syncIdentify;
+    private mergeServerState;
+    /** Sets or replaces the account (company / organisation) for the current user. */
+    setAccount(account: GuidelyAccount): Promise<void>;
+    /** Merges additional traits into the current user. */
+    updateTraits(traits: Record<string, unknown>): Promise<void>;
+    /** Forgets the user (call on logout): new anonymous id, cleared guide/checklist state, new session. */
+    reset(): void;
+    /** Updates consent at runtime (`granted` flushes buffered events; `denied` drops them). */
+    setConsent(consent: ConsentState): void;
+    private analyticsEnabled;
+    private collectUrls;
+    private currentUrl;
+    private enqueue;
+    /** Tracks a custom event. Events drive `event` triggers, `advanceOn: "event"` steps and checklist tasks. */
+    track(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * Records a screen view (the mobile equivalent of a page view) and re-evaluates triggers. URL
+     * patterns, `url_match` triggers, multi-screen steps and `url_visited` tasks match `/<name>`.
+     */
+    screen(name: string, properties?: Record<string, unknown>): void;
+    /** The current screen name (last value passed to `screen()`). */
+    getScreen(): string;
+    private handleTap;
+    /** Builds the targeting context for the current moment. */
+    getContext(): TargetingContext;
+    private isTargeted;
+    private isEligible;
+    private triggerFires;
+    private evaluate;
+    private armVisibility;
+    private setTimer;
+    private isShowing;
+    private hasExclusive;
+    private tryShow;
+    private drainQueue;
+    private findGuide;
+    private guideState;
+    private recordImpression;
+    private recordEnd;
+    private syncGuideState;
+    private show;
+    private showFlow;
+    private showChecklist;
+    private showSurvey;
+    private finishSurvey;
+    /** Theme for a guide: project theme ← app overrides ← guide appearance. */
+    themeFor(guide?: PublishedGuide): Partial<ProjectTheme> & {
+        dark?: "light" | "dark" | "auto";
+        overlayOpacity?: number;
+    };
+    /**
+     * Opens a URL from a button, link or task: the app's `onNavigate` handler first (deep links and
+     * in-app routes), then http(s) and custom-scheme URLs through the OS.
+     */
+    navigate(url: string): void;
+    getUiState(): UiState;
+    subscribeUi(cb: () => void): () => void;
+    private notify;
+    private flowFor;
+    /** A step button was pressed in the overlay. */
+    pressButton(guideId: string, button: StepButton): void;
+    /** The close (×) button of a step. */
+    closeStep(guideId: string): void;
+    /** The dimmed backdrop behind a step was tapped. */
+    backdropPressed(guideId: string): void;
+    /** Hotspot dot tapped: show (or hide) its card. */
+    toggleHotspot(guideId: string): void;
+    setChecklistOpen(guideId: string, open: boolean): void;
+    checklistTaskPressed(guideId: string, taskId: string): void;
+    dismissChecklist(guideId: string): void;
+    submitSurvey(guideId: string, answers: Record<string, unknown>): void;
+    closeSurvey(guideId: string): void;
+    getResourceCenter(): ResourceCenterConfig | null;
+    searchResourceCenter(q: string): Promise<ResourceCenterArticle[]>;
+    articleViewed(article: ResourceCenterArticle): void;
+    getChecklistProgress(idOrKey: string): ChecklistProgressState;
+    completeChecklistTask(idOrKey: string, taskId: string): void;
+    private markTaskDone;
+    private completeChecklistTasksBy;
+    openChecklist(idOrKey: string): void;
+    closeChecklist(idOrKey: string): void;
+    /** Starts a guide by id or key, bypassing targeting and frequency rules. */
+    startGuide(idOrKey: string, options?: {
+        stepId?: string;
+    }): boolean;
+    /** Stops the active guide silently (no dismiss event). */
+    stopGuide(): void;
+    /** Dismisses the active guide (records a dismissal). */
+    dismissGuide(): void;
+    getActiveGuide(): PublishedGuide | null;
+    getGuides(): ReadonlyArray<PublishedGuide>;
+    isGuideCompleted(idOrKey: string): boolean;
+    /** Impressions, completion and dismissal for a guide. */
+    getGuideState(idOrKey: string): GuideLocalState;
+    openResourceCenter(): void;
+    closeResourceCenter(): void;
+    /** Creates or removes the messenger to match the config (on only when enabled for this platform). */
+    private syncMessenger;
+    /** The Scout messenger store when Scout is on for this platform (rendered by the overlay). */
+    getMessenger(): Messenger | null;
+    /** Opens the Scout messenger, optionally on a tab. No-op when Scout is off for this platform. */
+    openMessenger(tab?: MessengerTab): void;
+    closeMessenger(): void;
+    /** Opens a new messenger conversation, optionally pre-filling the message. */
+    showNewMessage(text?: string): void;
+    on<K extends keyof GuidelyEvents>(event: K, cb: GuidelyEvents[K]): () => void;
+    off<K extends keyof GuidelyEvents>(event: K, cb: GuidelyEvents[K]): void;
+    isClientReady(): boolean;
+    /** Snapshot for debugging. */
+    getState(): {
+        ready: boolean;
+        destroyed: boolean;
+        anonymousId: string;
+        user: GuidelyUser | null;
+        consent: ConsentState;
+        screen: string;
+        configVersion: number | null;
+        guides: {
+            id: string;
+            key: string;
+            kind: "tooltip" | "modal" | "banner" | "checklist" | "survey" | "flow" | "announcement";
+        }[];
+        activeGuide: {
+            status: GuideStatus;
+            stepId: string | null;
+            stepIndex: number;
+            total: number;
+            id: string;
+            key: string;
+        } | {
+            id: string;
+            key: string;
+        } | null;
+        queued: string[];
+        widgets: string[];
+        guideState: Record<string, GuideLocalState>;
+        checklists: Record<string, ChecklistProgressState>;
+        audienceIds: string[];
+        session: MobileSession;
+        pendingEvents: number;
+        targets: string[];
+    };
+    private persistState;
+    private persistSession;
+    private reportError;
+    private log;
+}
+
+type Side = "top" | "bottom" | "left" | "right";
+interface Insets {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+interface CardPosition {
+    x: number;
+    y: number;
+    side: Side;
+    /** Arrow centre along the card edge facing the target (px from the card's left/top). */
+    arrow: number;
+}
+/**
+ * Places a card of `size` next to `target` inside `viewport` minus `insets`, honouring the step's
+ * placement when it fits and flipping (then falling back to below/above) when it does not.
+ */
+declare function positionCard(target: Rect, size: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, insets: Insets, placement: Placement, offset: number): CardPosition;
+
+/**
+ * Declares which screen its children are on, so targets on screens that are mounted but not
+ * visible (inactive tabs, screens under a stack) are never used. `name` must match what you pass
+ * to `screen()`. With React Navigation, use {@link guidelyScreenLayout} instead of wrapping by hand.
+ */
+declare function GuidelyScreenScope({ name, children }: {
+    name: string;
+    children?: ReactNode;
+}): react.JSX.Element;
+/**
+ * React Navigation 7 `screenLayout`: scopes every screen of a navigator to its route name.
+ * `<Tab.Navigator screenLayout={guidelyScreenLayout}>`.
+ */
+declare function guidelyScreenLayout({ route, children }: {
+    route: {
+        name: string;
+    };
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * Props to spread on an existing view so guides can point at it, without adding a wrapper:
+ * `const target = useGuidelyTarget("new-deal-button"); <Pressable {...target}>…</Pressable>`.
+ * Taps are observed, never intercepted.
+ */
+declare function useGuidelyTarget(id: string): {
+    ref: react.RefObject<View | null>;
+    collapsable: false;
+    onLayout: () => void | undefined;
+    onTouchStart: (e: GestureResponderEvent) => void;
+    onTouchEnd: (e: GestureResponderEvent) => void;
+};
+interface GuidelyTargetProps extends ViewProps {
+    /** The Guidely id guides use to find this view (`data-guidely-id` on the web). */
+    id: string;
+    children?: ReactNode;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Marks a view as a guide target. Wraps children in a `View`; give it `style={{ alignSelf: "flex-start" }}`
+ * (or use {@link useGuidelyTarget}) when the wrapper should not stretch to its parent's width.
+ */
+declare function GuidelyTarget({ id, children, onLayout, onTouchStart, onTouchEnd, ...rest }: GuidelyTargetProps): react.JSX.Element;
+
+interface OverlayProps {
+    client: GuidelyClient;
+    insets?: Partial<Insets>;
+    /** Distance of the checklist launcher above the bottom inset (clears tab bars). */
+    launcherOffset: number;
+}
+/**
+ * Draws everything the client wants on screen, above the app. `pointerEvents="box-none"` keeps the
+ * app fully interactive except where guide UI (or a modal backdrop) is shown.
+ */
+declare function GuidelyOverlay({ client, insets: insetsProp, launcherOffset }: OverlayProps): react.JSX.Element;
+
+/**
+ * Tiny, tolerant HTML → rich-text converter for guide bodies (already sanitized server-side).
+ * Supports p, div, br, strong/b, em/i, u, a, code, ul/ol/li, h1–h6 and blockquote; every other tag
+ * is reduced to its text. Output is plain data so it can be unit-tested without React Native.
+ */
+interface TextRun {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    code?: boolean;
+    href?: string;
+}
+interface TextBlock {
+    kind: "paragraph" | "heading" | "list-item" | "quote";
+    /** Heading level 1–3, list nesting depth from 1. */
+    level: number;
+    /** For list items: the bullet ("•") or number ("1.") to show. */
+    marker?: string;
+    runs: TextRun[];
+}
+declare function parseHtml(html: string): TextBlock[];
+/** Plain-text rendering of an HTML body (accessibility labels, previews). */
+declare function htmlToText(html: string): string;
+
+interface GuidelyProviderProps extends Omit<GuidelyOptions, "user"> {
+    /** Identify this user once the client is ready; changing to `null` resets the identity (logout). */
+    user?: GuidelyUser | null;
+    /** Safe-area insets for banners, launchers and sheets. Pass `useSafeAreaInsets()` from react-native-safe-area-context for exact values. */
+    insets?: Partial<Insets>;
+    /** How far above the bottom inset the checklist launcher sits, to clear tab bars (default 72). */
+    launcherOffset?: number;
+    children?: ReactNode;
+}
+/**
+ * Creates one Guidely client for the app and renders guide UI above `children`. Place it at the
+ * root of the app (outside navigators) so the overlay covers every screen.
+ */
+declare function GuidelyProvider({ children, user, insets, launcherOffset, ...options }: GuidelyProviderProps): react.JSX.Element;
+/** A client that ignores every call; returned by `useGuidely()` before the provider has created one. */
+declare const noopClient: GuidelyClient;
+/** The Guidely client (a no-op stand-in until the provider has created it). */
+declare function useGuidely(): GuidelyClient;
+/** True once config is loaded and triggers have been evaluated. */
+declare function useGuidelyReady(): boolean;
+/** Identifies the user whenever the id or traits change. */
+declare function useGuidelyIdentify(userId: string | null | undefined, traits?: Record<string, unknown>, account?: GuidelyAccount): void;
+/** Subscribes to a Guidely event for the lifetime of the component. */
+declare function useGuidelyEvent<K extends keyof GuidelyEvents>(event: K, handler: GuidelyEvents[K]): void;
+/** Records a screen view while the component is mounted (and when `name` changes). */
+declare function useGuidelyScreen(name: string | null | undefined, properties?: Record<string, unknown>): void;
+interface NavigationRefLike {
+    getCurrentRoute(): {
+        name: string;
+    } | undefined | null;
+}
+/**
+ * React Navigation integration: spread the result on `<NavigationContainer>` and every route
+ * change becomes a Guidely screen view named after the route.
+ *
+ * ```tsx
+ * const ref = useNavigationContainerRef();
+ * <NavigationContainer ref={ref} {...useGuidelyNavigation(ref)}>
+ * ```
+ */
+declare function useGuidelyNavigation(navigationRef: NavigationRefLike, options?: {
+    screenName?: (route: {
+        name: string;
+    }) => string;
+}): {
+    onReady: () => void;
+    onStateChange: () => void;
+};
+/** Live progress of a checklist guide (by id or key). */
+declare function useChecklistProgress(idOrKey: string): ChecklistProgressState;
+/** Live impressions / completion / dismissal of a guide (by id or key). */
+declare function useGuideState(idOrKey: string): {
+    impressions: number;
+    completed: boolean;
+    dismissed: boolean;
+};
+/** The guide currently running exclusively (flow, modal, survey…), or null. */
+declare function useActiveGuide(): PublishedGuide | null;
+
+export { type ChecklistView, DEFAULT_API_URL, type DeviceEnvironment, type GuideStepInfo, GuidelyClient, type GuidelyEventName, type GuidelyEvents, type GuidelyOptions, GuidelyOverlay, GuidelyProvider, type GuidelyProviderProps, GuidelyScreenScope, type GuidelyStorage, GuidelyTarget, type GuidelyTargetProps, type Insets, Messenger, type MessengerSnapshot, type MessengerTab, type MessengerThread, type MessengerView, type PlatformBridge, SDK_NAME, SDK_VERSION, type StepView, type SurveyView, TargetRegistry, type UiState, createSseParser, guidelyScreenLayout, htmlToText, noopClient, parseHtml, positionCard, targetIdsFor, useActiveGuide, useChecklistProgress, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyNavigation, useGuidelyReady, useGuidelyScreen, useGuidelyTarget };