@thelol3882/sapar 0.0.0-stage → 0.3.0

package/dist/rtk/index.js

@@ -0,0 +1,114 @@
+'use client';
+import {
+  fromWireAnnouncement,
+  fromWireInbox,
+  fromWireTour,
+  toWireProgress
+} from "../chunk-FM64UDKJ.js";
+
+// src/rtk/createSaparRtk.ts
+import { useMemo } from "react";
+import { useDispatch } from "react-redux";
+
+// src/rtk/errors.ts
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// src/rtk/createSaparRtk.ts
+var TAG_TYPE = "Sapar";
+var INBOX_TAG = { type: TAG_TYPE, id: "inbox" };
+var ALWAYS_FRESH = { subscribe: false, forceRefetch: true };
+var discardBody = () => void 0;
+function createSaparRtk(api, { basePath = "/tours" } = {}) {
+  const root = basePath.replace(/\/+$/, "");
+  const tourPath = (key) => `${root}/tours/${encodeURIComponent(key)}/`;
+  const injectedApi = api.enhanceEndpoints({ addTagTypes: [TAG_TYPE] }).injectEndpoints({
+    endpoints: (builder) => ({
+      getSaparInbox: builder.query({
+        query: (params) => ({ url: `${root}/inbox/`, params }),
+        transformResponse: (inbox) => fromWireInbox(inbox),
+        providesTags: [INBOX_TAG]
+      }),
+      getTour: builder.query({
+        async queryFn(key, _api, _extraOptions, baseQuery) {
+          const { data, error } = await baseQuery(tourPath(key));
+          if (isNotFound(error)) return { data: null };
+          return error ? { error } : { data: fromWireTour(data) };
+        }
+      }),
+      getAnnouncements: builder.query({
+        query: () => `${root}/announcements/`,
+        transformResponse: (announcements) => announcements.map(fromWireAnnouncement)
+      }),
+      markAnnouncementsSeen: builder.mutation({
+        query: (keys) => ({ url: `${root}/seen/`, method: "POST", body: { keys } }),
+        transformResponse: discardBody,
+        invalidatesTags: [INBOX_TAG]
+      }),
+      dismissAnnouncement: builder.mutation({
+        query: (key) => ({ url: `${root}/dismiss/`, method: "POST", body: { key } }),
+        transformResponse: discardBody,
+        invalidatesTags: [INBOX_TAG]
+      }),
+      recordAnnouncementClick: builder.mutation({
+        query: (key) => ({ url: `${root}/announcements/${encodeURIComponent(key)}/click/`, method: "POST" }),
+        transformResponse: discardBody
+      }),
+      recordTourProgress: builder.mutation({
+        query: (input) => ({
+          url: `${tourPath(input.key)}progress/`,
+          method: "POST",
+          body: toWireProgress(input)
+        }),
+        transformResponse: discardBody,
+        invalidatesTags: [INBOX_TAG]
+      })
+    })
+  });
+  const { endpoints } = injectedApi;
+  const {
+    useGetSaparInboxQuery,
+    useLazyGetSaparInboxQuery,
+    useGetTourQuery,
+    useLazyGetTourQuery,
+    useGetAnnouncementsQuery,
+    useMarkAnnouncementsSeenMutation,
+    useDismissAnnouncementMutation,
+    useRecordAnnouncementClickMutation,
+    useRecordTourProgressMutation
+  } = injectedApi;
+  function createSource(dispatch) {
+    return {
+      getInbox: (query) => dispatch(endpoints.getSaparInbox.initiate(query, ALWAYS_FRESH)).unwrap(),
+      getTour: (key) => dispatch(endpoints.getTour.initiate(key, ALWAYS_FRESH)).unwrap(),
+      listAnnouncements: () => dispatch(endpoints.getAnnouncements.initiate(void 0, ALWAYS_FRESH)).unwrap(),
+      recordProgress: (input) => dispatch(endpoints.recordTourProgress.initiate(input)).unwrap(),
+      markSeen: (keys) => dispatch(endpoints.markAnnouncementsSeen.initiate(keys)).unwrap(),
+      dismiss: (key) => dispatch(endpoints.dismissAnnouncement.initiate(key)).unwrap(),
+      recordClick: (key) => dispatch(endpoints.recordAnnouncementClick.initiate(key)).unwrap()
+    };
+  }
+  function useSaparSource() {
+    const dispatch = useDispatch();
+    return useMemo(() => createSource(dispatch), [dispatch]);
+  }
+  return {
+    api: injectedApi,
+    useGetSaparInboxQuery,
+    useLazyGetSaparInboxQuery,
+    useGetTourQuery,
+    useLazyGetTourQuery,
+    useGetAnnouncementsQuery,
+    useMarkAnnouncementsSeenMutation,
+    useDismissAnnouncementMutation,
+    useRecordAnnouncementClickMutation,
+    useRecordTourProgressMutation,
+    createSource,
+    useSaparSource
+  };
+}
+export {
+  createSaparRtk
+};
+//# sourceMappingURL=index.js.map

package/dist/rtk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/rtk/createSaparRtk.ts","../../src/rtk/errors.ts"],"sourcesContent":["'use client';\n\nimport type { ThunkDispatch, UnknownAction } from '@reduxjs/toolkit';\nimport type {\n    Api,\n    BaseQueryFn,\n    EndpointDefinitions,\n    FetchArgs,\n    FetchBaseQueryError,\n    coreModuleName,\n    reactHooksModuleName,\n} from '@reduxjs/toolkit/query/react';\nimport { useMemo } from 'react';\nimport { useDispatch } from 'react-redux';\nimport { fromWireAnnouncement, fromWireInbox, fromWireTour, toWireProgress } from '../core';\nimport type {\n    Announcement,\n    Inbox,\n    Platform,\n    ProgressInput,\n    Tour,\n    SaparSource,\n    WireAnnouncement,\n    WireInbox,\n    WireTour,\n} from '../core';\nimport { isNotFound } from './errors';\n\nexport type SaparBaseQuery = BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError>;\n\n/** The host's own `createApi` slice, whose base query owns auth, refresh and the base URL. */\nexport type HostApi<\n    Definitions extends EndpointDefinitions = EndpointDefinitions,\n    ReducerPath extends string = string,\n    TagTypes extends string = string,\n> = Api<SaparBaseQuery, Definitions, ReducerPath, TagTypes, typeof coreModuleName | typeof reactHooksModuleName>;\n\nexport type SaparDispatch = ThunkDispatch<unknown, unknown, UnknownAction>;\n\nexport interface SaparRtkOptions {\n    /** Prefix of the tours endpoints, relative to the host base query's base URL. Default `/tours`. */\n    basePath?: string;\n}\n\nconst TAG_TYPE = 'Sapar';\nconst INBOX_TAG = { type: TAG_TYPE, id: 'inbox' } as const;\nconst ALWAYS_FRESH = { subscribe: false, forceRefetch: true } as const;\n\nconst discardBody = (): void => undefined;\n\n/**\n * Generic over the host slice so any `createApi` result is accepted; the body widens it once,\n * because RTK cannot resolve the hooks module through those generics.\n */\nexport function createSaparRtk<\n    Definitions extends EndpointDefinitions,\n    ReducerPath extends string,\n    TagTypes extends string,\n>(api: HostApi<Definitions, ReducerPath, TagTypes>, { basePath = '/tours' }: SaparRtkOptions = {}) {\n    const root = basePath.replace(/\\/+$/, '');\n    const tourPath = (key: string): string => `${root}/tours/${encodeURIComponent(key)}/`;\n\n    const injectedApi = (api as unknown as HostApi).enhanceEndpoints({ addTagTypes: [TAG_TYPE] }).injectEndpoints({\n        endpoints: (builder) => ({\n            getSaparInbox: builder.query<Inbox, { route?: string; platform: Platform }>({\n                query: (params) => ({ url: `${root}/inbox/`, params }),\n                transformResponse: (inbox: WireInbox) => fromWireInbox(inbox),\n                providesTags: [INBOX_TAG],\n            }),\n            getTour: builder.query<Tour | null, string>({\n                async queryFn(key, _api, _extraOptions, baseQuery) {\n                    const { data, error } = await baseQuery(tourPath(key));\n                    if (isNotFound(error)) return { data: null };\n                    return error ? { error } : { data: fromWireTour(data as WireTour) };\n                },\n            }),\n            getAnnouncements: builder.query<Announcement[], void>({\n                query: () => `${root}/announcements/`,\n                transformResponse: (announcements: WireAnnouncement[]) => announcements.map(fromWireAnnouncement),\n            }),\n            markAnnouncementsSeen: builder.mutation<void, string[]>({\n                query: (keys) => ({ url: `${root}/seen/`, method: 'POST', body: { keys } }),\n                transformResponse: discardBody,\n                invalidatesTags: [INBOX_TAG],\n            }),\n            dismissAnnouncement: builder.mutation<void, string>({\n                query: (key) => ({ url: `${root}/dismiss/`, method: 'POST', body: { key } }),\n                transformResponse: discardBody,\n                invalidatesTags: [INBOX_TAG],\n            }),\n            recordAnnouncementClick: builder.mutation<void, string>({\n                query: (key) => ({ url: `${root}/announcements/${encodeURIComponent(key)}/click/`, method: 'POST' }),\n                transformResponse: discardBody,\n            }),\n            recordTourProgress: builder.mutation<void, ProgressInput>({\n                query: (input) => ({\n                    url: `${tourPath(input.key)}progress/`,\n                    method: 'POST',\n                    body: toWireProgress(input),\n                }),\n                transformResponse: discardBody,\n                invalidatesTags: [INBOX_TAG],\n            }),\n        }),\n    });\n\n    const { endpoints } = injectedApi;\n    const {\n        useGetSaparInboxQuery,\n        useLazyGetSaparInboxQuery,\n        useGetTourQuery,\n        useLazyGetTourQuery,\n        useGetAnnouncementsQuery,\n        useMarkAnnouncementsSeenMutation,\n        useDismissAnnouncementMutation,\n        useRecordAnnouncementClickMutation,\n        useRecordTourProgressMutation,\n    } = injectedApi;\n\n    function createSource(dispatch: SaparDispatch): SaparSource {\n        return {\n            getInbox: (query) => dispatch(endpoints.getSaparInbox.initiate(query, ALWAYS_FRESH)).unwrap(),\n            getTour: (key) => dispatch(endpoints.getTour.initiate(key, ALWAYS_FRESH)).unwrap(),\n            listAnnouncements: () => dispatch(endpoints.getAnnouncements.initiate(undefined, ALWAYS_FRESH)).unwrap(),\n            recordProgress: (input) => dispatch(endpoints.recordTourProgress.initiate(input)).unwrap(),\n            markSeen: (keys) => dispatch(endpoints.markAnnouncementsSeen.initiate(keys)).unwrap(),\n            dismiss: (key) => dispatch(endpoints.dismissAnnouncement.initiate(key)).unwrap(),\n            recordClick: (key) => dispatch(endpoints.recordAnnouncementClick.initiate(key)).unwrap(),\n        };\n    }\n\n    function useSaparSource(): SaparSource {\n        const dispatch = useDispatch<SaparDispatch>();\n        return useMemo(() => createSource(dispatch), [dispatch]);\n    }\n\n    return {\n        api: injectedApi,\n        useGetSaparInboxQuery,\n        useLazyGetSaparInboxQuery,\n        useGetTourQuery,\n        useLazyGetTourQuery,\n        useGetAnnouncementsQuery,\n        useMarkAnnouncementsSeenMutation,\n        useDismissAnnouncementMutation,\n        useRecordAnnouncementClickMutation,\n        useRecordTourProgressMutation,\n        createSource,\n        useSaparSource,\n    };\n}\n","export function isNotFound(error: unknown): boolean {\n    return typeof error === 'object' && error !== null && 'status' in error && error.status === 404;\n}\n"],"mappings":";;;;;;;;AAYA,SAAS,eAAe;AACxB,SAAS,mBAAmB;;;ACbrB,SAAS,WAAW,OAAyB;AAChD,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,YAAY,SAAS,MAAM,WAAW;AAChG;;;AD0CA,IAAM,WAAW;AACjB,IAAM,YAAY,EAAE,MAAM,UAAU,IAAI,QAAQ;AAChD,IAAM,eAAe,EAAE,WAAW,OAAO,cAAc,KAAK;AAE5D,IAAM,cAAc,MAAY;AAMzB,SAAS,eAId,KAAkD,EAAE,WAAW,SAAS,IAAqB,CAAC,GAAG;AAC/F,QAAM,OAAO,SAAS,QAAQ,QAAQ,EAAE;AACxC,QAAM,WAAW,CAAC,QAAwB,GAAG,IAAI,UAAU,mBAAmB,GAAG,CAAC;AAElF,QAAM,cAAe,IAA2B,iBAAiB,EAAE,aAAa,CAAC,QAAQ,EAAE,CAAC,EAAE,gBAAgB;AAAA,IAC1G,WAAW,CAAC,aAAa;AAAA,MACrB,eAAe,QAAQ,MAAqD;AAAA,QACxE,OAAO,CAAC,YAAY,EAAE,KAAK,GAAG,IAAI,WAAW,OAAO;AAAA,QACpD,mBAAmB,CAAC,UAAqB,cAAc,KAAK;AAAA,QAC5D,cAAc,CAAC,SAAS;AAAA,MAC5B,CAAC;AAAA,MACD,SAAS,QAAQ,MAA2B;AAAA,QACxC,MAAM,QAAQ,KAAK,MAAM,eAAe,WAAW;AAC/C,gBAAM,EAAE,MAAM,MAAM,IAAI,MAAM,UAAU,SAAS,GAAG,CAAC;AACrD,cAAI,WAAW,KAAK,EAAG,QAAO,EAAE,MAAM,KAAK;AAC3C,iBAAO,QAAQ,EAAE,MAAM,IAAI,EAAE,MAAM,aAAa,IAAgB,EAAE;AAAA,QACtE;AAAA,MACJ,CAAC;AAAA,MACD,kBAAkB,QAAQ,MAA4B;AAAA,QAClD,OAAO,MAAM,GAAG,IAAI;AAAA,QACpB,mBAAmB,CAAC,kBAAsC,cAAc,IAAI,oBAAoB;AAAA,MACpG,CAAC;AAAA,MACD,uBAAuB,QAAQ,SAAyB;AAAA,QACpD,OAAO,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,UAAU,QAAQ,QAAQ,MAAM,EAAE,KAAK,EAAE;AAAA,QACzE,mBAAmB;AAAA,QACnB,iBAAiB,CAAC,SAAS;AAAA,MAC/B,CAAC;AAAA,MACD,qBAAqB,QAAQ,SAAuB;AAAA,QAChD,OAAO,CAAC,SAAS,EAAE,KAAK,GAAG,IAAI,aAAa,QAAQ,QAAQ,MAAM,EAAE,IAAI,EAAE;AAAA,QAC1E,mBAAmB;AAAA,QACnB,iBAAiB,CAAC,SAAS;AAAA,MAC/B,CAAC;AAAA,MACD,yBAAyB,QAAQ,SAAuB;AAAA,QACpD,OAAO,CAAC,SAAS,EAAE,KAAK,GAAG,IAAI,kBAAkB,mBAAmB,GAAG,CAAC,WAAW,QAAQ,OAAO;AAAA,QAClG,mBAAmB;AAAA,MACvB,CAAC;AAAA,MACD,oBAAoB,QAAQ,SAA8B;AAAA,QACtD,OAAO,CAAC,WAAW;AAAA,UACf,KAAK,GAAG,SAAS,MAAM,GAAG,CAAC;AAAA,UAC3B,QAAQ;AAAA,UACR,MAAM,eAAe,KAAK;AAAA,QAC9B;AAAA,QACA,mBAAmB;AAAA,QACnB,iBAAiB,CAAC,SAAS;AAAA,MAC/B,CAAC;AAAA,IACL;AAAA,EACJ,CAAC;AAED,QAAM,EAAE,UAAU,IAAI;AACtB,QAAM;AAAA,IACF;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACJ,IAAI;AAEJ,WAAS,aAAa,UAAsC;AACxD,WAAO;AAAA,MACH,UAAU,CAAC,UAAU,SAAS,UAAU,cAAc,SAAS,OAAO,YAAY,CAAC,EAAE,OAAO;AAAA,MAC5F,SAAS,CAAC,QAAQ,SAAS,UAAU,QAAQ,SAAS,KAAK,YAAY,CAAC,EAAE,OAAO;AAAA,MACjF,mBAAmB,MAAM,SAAS,UAAU,iBAAiB,SAAS,QAAW,YAAY,CAAC,EAAE,OAAO;AAAA,MACvG,gBAAgB,CAAC,UAAU,SAAS,UAAU,mBAAmB,SAAS,KAAK,CAAC,EAAE,OAAO;AAAA,MACzF,UAAU,CAAC,SAAS,SAAS,UAAU,sBAAsB,SAAS,IAAI,CAAC,EAAE,OAAO;AAAA,MACpF,SAAS,CAAC,QAAQ,SAAS,UAAU,oBAAoB,SAAS,GAAG,CAAC,EAAE,OAAO;AAAA,MAC/E,aAAa,CAAC,QAAQ,SAAS,UAAU,wBAAwB,SAAS,GAAG,CAAC,EAAE,OAAO;AAAA,IAC3F;AAAA,EACJ;AAEA,WAAS,iBAA8B;AACnC,UAAM,WAAW,YAA2B;AAC5C,WAAO,QAAQ,MAAM,aAAa,QAAQ,GAAG,CAAC,QAAQ,CAAC;AAAA,EAC3D;AAEA,SAAO;AAAA,IACH,KAAK;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACJ;AACJ;","names":[]}

package/dist/stepCount-CTYYFWiV.d.ts

@@ -0,0 +1,57 @@
+import { T as Tour, q as TourStep, k as AnchorHandle, f as Announcement, j as Inbox, m as InboxStatus, o as SaparSnapshot } from './types-CHD2pB5X.js';
+
+declare function useSaparSnapshot(): SaparSnapshot;
+interface UseSaparResult {
+    startTour: (tourOrKey: Tour | string) => Promise<void>;
+    inbox: Inbox | null;
+    inboxStatus: InboxStatus;
+    isRunning: boolean;
+}
+declare function useSapar(): UseSaparResult;
+interface TourStepState {
+    tour: Tour;
+    step: TourStep;
+    /** One-based position among the steps that are expected to be shown. */
+    position: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+    handle: AnchorHandle | null;
+    next: () => Promise<void>;
+    previous: () => Promise<void>;
+    skip: () => void;
+}
+declare function useTourStep(): TourStepState | null;
+interface UseWhatsNewResult {
+    items: Announcement[];
+    unreadCount: number;
+    status: InboxStatus;
+    /** Marks the items that are unread at the moment of the call. */
+    markAllSeen: () => Promise<void>;
+    markSeen: (keys: string[]) => Promise<void>;
+    dismiss: (key: string) => Promise<void>;
+    recordClick: (key: string) => void;
+    startTour: (tourOrKey: Tour | string) => Promise<void>;
+}
+declare function useWhatsNew(): UseWhatsNewResult;
+interface AnnouncementInterruption {
+    /** The modal-tier announcement the source wants shown now, if any. */
+    announcement: Announcement | null;
+    dismiss: () => Promise<void>;
+    /** Marks the announcement seen without recording a dismissal. */
+    acknowledge: () => Promise<void>;
+}
+declare function useAnnouncementInterruption(): AnnouncementInterruption;
+
+interface StepCount {
+    /** One-based. */
+    position: number;
+    total: number;
+}
+interface StepAnnouncement extends StepCount {
+    title: string;
+}
+declare const defaultAnnounceStep: ({ position, total, title }: StepAnnouncement) => string;
+declare const defaultProgress: ({ position, total }: StepCount) => string;
+
+export { type AnnouncementInterruption as A, type StepAnnouncement as S, type TourStepState as T, type UseSaparResult as U, type StepCount as a, type UseWhatsNewResult as b, defaultProgress as c, defaultAnnounceStep as d, useSapar as e, useSaparSnapshot as f, useTourStep as g, useWhatsNew as h, useAnnouncementInterruption as u };

package/dist/types-CHD2pB5X.d.ts

@@ -0,0 +1,192 @@
+type Platform = 'web' | 'native';
+type Placement = 'auto' | 'top' | 'bottom' | 'left' | 'right';
+type AnnouncementTier = 'silent' | 'feed' | 'modal';
+type TourStatus = 'started' | 'completed' | 'dismissed';
+/** `'manual'` starts only on request; `{ route }` may auto-start where the pattern matches. */
+type TourTrigger = 'manual' | {
+    route: string;
+};
+/** Plain text, or a per-locale map resolved by the source. */
+type LocalizedText = string | Readonly<Record<string, string>>;
+interface TourStep {
+    key: string;
+    /** Absent means a centered step with no spotlight. */
+    anchor?: string;
+    /** Route the anchor lives on; the runner navigates there first. */
+    route?: string;
+    title: string;
+    body: string;
+    placement: Placement;
+    padding: number;
+    /** A missing anchor skips the step unless this is set, which aborts the tour when the runner reaches it. */
+    required: boolean;
+    /** `'press'` advances when the user presses the anchored element itself. */
+    advanceOn: 'next' | 'press';
+}
+interface Tour {
+    key: string;
+    revision: number;
+    title: string;
+    trigger: TourTrigger;
+    steps: TourStep[];
+}
+interface Announcement {
+    key: string;
+    tier: AnnouncementTier;
+    title: string;
+    body: string;
+    imageUrl?: string;
+    cta?: {
+        label: string;
+        url: string;
+    };
+    /** ISO 8601. */
+    publishedAt: string | null;
+    tourKey?: string;
+    unread: boolean;
+}
+type Interruption = {
+    kind: 'tour';
+    tour: Tour;
+} | {
+    kind: 'announcement';
+    announcement: Announcement;
+};
+interface Inbox {
+    /** Unread non-silent announcements. */
+    unreadCount: number;
+    items: Announcement[];
+    /** At most one unbidden thing to show, already filtered by the source's policy. */
+    interruption: Interruption | null;
+}
+interface ProgressInput {
+    key: string;
+    revision: number;
+    status: TourStatus;
+    stepIndex: number;
+    autoStarted: boolean;
+}
+/**
+ * Where tours, announcements and per-user state come from.
+ * Implementations: `memorySource` (definitions in code, state in storage),
+ * `httpSource` (the Django/FastAPI backend over fetch), `createSaparRtk` (same backend through RTK Query).
+ */
+interface SaparSource {
+    getInbox(query: {
+        route?: string;
+        platform: Platform;
+    }): Promise<Inbox>;
+    getTour(key: string): Promise<Tour | null>;
+    recordProgress(input: ProgressInput): Promise<void>;
+    markSeen(keys: string[]): Promise<void>;
+    dismiss(key: string): Promise<void>;
+    recordClick(key: string): Promise<void>;
+    listAnnouncements(): Promise<Announcement[]>;
+}
+/** Possibly-async key-value storage: localStorage, AsyncStorage, MMKV, memory. */
+interface KeyValueStore {
+    get(key: string): string | null | Promise<string | null>;
+    set(key: string, value: string): void | Promise<void>;
+    remove(key: string): void | Promise<void>;
+}
+/** Synchronous per-session storage for the client-side interruption cap. */
+interface SessionStore {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+}
+interface AnchorRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface AnchorHandle {
+    key: string;
+    /** Async because native measurement is; live because the element moves. */
+    measure(): Promise<AnchorRect | null>;
+    /** Resolves on the next press of the anchored element. Returns an unsubscribe. */
+    onPress(listener: () => void): () => void;
+}
+/** Everything platform-shaped. The web implementation lives in `/web`, a native one would sit beside it. */
+interface PlatformAdapter {
+    platform: Platform;
+    /** Resolves `null` on timeout. Must never reject for a missing anchor. */
+    resolveAnchor(key: string, options: {
+        timeoutMs: number;
+    }): Promise<AnchorHandle | null>;
+    scrollIntoView(handle: AnchorHandle, options: {
+        reducedMotion: boolean;
+    }): Promise<void>;
+    /** Raw route in the host router's spelling; the controller normalizes it. */
+    currentRoute(): string;
+    /** Resolves once the destination has rendered. */
+    navigate(route: string): Promise<void>;
+    prefersReducedMotion(): boolean;
+    isCompact(): boolean;
+    session: SessionStore;
+    now(): number;
+}
+type RunnerPhase = 'idle' | 'preparing' | 'running';
+interface RunnerSnapshot {
+    phase: RunnerPhase;
+    tour: Tour | null;
+    /** Index into `tour.steps` of the step being shown. */
+    index: number;
+    /** The current step's anchor, or null for a centered step. */
+    handle: AnchorHandle | null;
+    /** Keys of the steps whose anchor is missing right now. An estimate: the runner still tries each on arrival. */
+    skipped: readonly string[];
+    autoStarted: boolean;
+}
+type InboxStatus = 'idle' | 'loading' | 'ready' | 'error';
+interface SaparSnapshot {
+    inbox: Inbox | null;
+    inboxStatus: InboxStatus;
+    runner: RunnerSnapshot;
+}
+interface SaparControllerOptions {
+    source: SaparSource;
+    adapter: PlatformAdapter;
+    /** Locale prefixes stripped from routes (`/ru/billing` -> `/billing`). Must match the backend. */
+    locales?: readonly string[];
+    /** How long to wait for an anchor right after navigating, while the page loads. Default 3000. */
+    anchorTimeoutMs?: number;
+    /** How long to wait for an anchor on a page that is already rendered. Default 300. */
+    presentAnchorTimeoutMs?: number;
+    /** How long an auto-started tour waits for its first anchor before giving up quietly. Default 10000. */
+    autoStartTimeoutMs?: number;
+    /** At most one unbidden interruption per session on top of the source's policy. Default true. */
+    sessionCap?: boolean;
+    /** Called for swallowed errors (failed progress writes, adapter bugs). Default `console.error`. */
+    onError?: (error: unknown, context: string) => void;
+}
+/** Framework-free owner of the inbox, the runner and every behaviour rule. React only binds to it. */
+interface SaparController {
+    subscribe(listener: () => void): () => void;
+    /** Referentially stable until state changes, for `useSyncExternalStore`. */
+    getSnapshot(): SaparSnapshot;
+    /** Reports the current route; refetches the inbox and may auto-start the offered interruption. `undefined` opts out of route triggers. */
+    setRoute(route: string | undefined): void;
+    refresh(): Promise<void>;
+    /** A tour the user asked for: never capped, reported with `autoStarted: false`. */
+    startTour(tourOrKey: Tour | string): Promise<void>;
+    next(): Promise<void>;
+    previous(): Promise<void>;
+    skip(): void;
+    /** Optimistically clears unread state, rolls back if the source rejects. */
+    markSeen(keys: string[]): Promise<void>;
+    dismiss(key: string): Promise<void>;
+    recordClick(key: string): void;
+    destroy(): void;
+}
+/** Local interruption policy, used by `memorySource`. Mirrors the backend's settings and defaults. */
+interface InterruptionPolicy {
+    /** No interruptions for accounts younger than this. Default 3. */
+    newUserGraceDays: number;
+    /** Minimum gap between auto interruptions. Default 24. */
+    cooldownHours: number;
+    /** A dismissed tour is re-offered after this long; 0 means immediately. Default 30. */
+    dismissalBackoffDays: number;
+}
+
+export type { AnnouncementTier as A, InterruptionPolicy as I, KeyValueStore as K, LocalizedText as L, ProgressInput as P, RunnerSnapshot as R, SaparControllerOptions as S, Tour as T, SaparController as a, PlatformAdapter as b, TourTrigger as c, Placement as d, Platform as e, Announcement as f, TourStatus as g, Interruption as h, SaparSource as i, Inbox as j, AnchorHandle as k, AnchorRect as l, InboxStatus as m, RunnerPhase as n, SaparSnapshot as o, SessionStore as p, TourStep as q };

package/dist/web/index.d.ts

@@ -0,0 +1,112 @@
+export { W as WebAdapterOptions, c as createWebAdapter } from '../adapter-Y9yB3-q3.js';
+import * as react from 'react';
+import { ReactNode, RefCallback, CSSProperties, ComponentPropsWithoutRef, ReactElement } from 'react';
+import { l as AnchorRect } from '../types-CHD2pB5X.js';
+import { T as TourStepState, S as StepAnnouncement, a as StepCount } from '../stepCount-CTYYFWiV.js';
+import { P as Presentation } from '../presentation-CClsPRT6.js';
+
+declare const ANCHOR_ATTRIBUTE = "data-sapar";
+declare function registerAnchor(key: string, element: HTMLElement): () => void;
+declare function getAnchorElement(key: string): HTMLElement | null;
+/** Resolves `null` on timeout. Woken by registration, or by a DOM mutation for plain `data-sapar` markup. */
+declare function waitForAnchor(key: string, timeoutMs: number): Promise<HTMLElement | null>;
+
+interface SyncStore {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+declare const localStorageStore: () => SyncStore;
+declare const browserSessionStore: () => SyncStore;
+
+/** Renders nothing on the server and during hydration, then portals into `document.body`. */
+declare function BodyPortal({ children }: {
+    children: ReactNode;
+}): react.ReactPortal | null;
+
+interface TourAnchorProps<K extends string, E extends HTMLElement> {
+    ref: RefCallback<E>;
+    [ANCHOR_ATTRIBUTE]: K;
+}
+/** Spread the result onto the element a tour step points at: `<button {...useTourAnchor('billing.upgrade')} />`. */
+declare function useTourAnchor<K extends string = string, E extends HTMLElement = HTMLElement>(key: K): TourAnchorProps<K, E>;
+
+/** Live viewport rect of `element`, re-measured at most once per animation frame; null when there is none or it is detached. */
+declare function useElementRect(element: HTMLElement | null): AnchorRect | null;
+
+interface TourPopoverProps {
+    className?: string;
+    style?: CSSProperties;
+    /** Gap in px between the anchor and the popover. */
+    offset?: number;
+    /**
+     * `'anchored'` puts the popover next to the anchor (centred without one), `'sheet'` is a bottom sheet, and
+     * `'auto'` is a sheet on viewports narrower than the adapter's `compactBreakpointPx` (default 768). Default `'auto'`.
+     */
+    presentation?: Presentation;
+    children?: ReactNode;
+}
+declare function TourPopover(props: TourPopoverProps): react.JSX.Element | null;
+
+interface TourOverlayProps extends Pick<TourPopoverProps, 'presentation'> {
+    spotlightClassName?: string;
+    spotlightStyle?: CSSProperties;
+    popoverClassName?: string;
+    popoverStyle?: CSSProperties;
+    onClickOutside?: () => void;
+    /** The step card, either directly or built from the running step. */
+    children: ReactNode | ((tourStep: TourStepState) => ReactNode);
+}
+declare function TourOverlay({ spotlightClassName, spotlightStyle, popoverClassName, popoverStyle, onClickOutside, presentation, children, }: TourOverlayProps): react.JSX.Element | null;
+
+interface TourSpotlightProps {
+    /** Colours the dim layer through `currentColor`, e.g. `text-black/50` (or `style.color`). */
+    className?: string;
+    style?: CSSProperties;
+    /** Corner radius of the cutout in px. */
+    radius?: number;
+    /** Called when the dim layer is clicked. Defaults to skipping the tour. */
+    onClickOutside?: () => void;
+}
+declare function TourSpotlight({ onClickOutside, ...rest }: TourSpotlightProps): react.JSX.Element | null;
+
+interface TourStepRootProps extends ComponentPropsWithoutRef<'div'> {
+    /** Text read by screen readers on each step change. */
+    announceStep?: (step: StepAnnouncement) => string;
+}
+declare function Root(props: TourStepRootProps): react.JSX.Element | null;
+declare function Title({ children, ...rest }: ComponentPropsWithoutRef<'h2'>): react.JSX.Element;
+declare function Body({ children, ...rest }: ComponentPropsWithoutRef<'p'>): react.JSX.Element;
+interface TourStepProgressProps extends Omit<ComponentPropsWithoutRef<'span'>, 'children'> {
+    /** Defaults to `"{position} / {total}"`. */
+    children?: ReactNode | ((count: StepCount) => ReactNode);
+}
+declare function Progress({ children, ...rest }: TourStepProgressProps): react.JSX.Element;
+type ButtonProps = ComponentPropsWithoutRef<'button'>;
+interface TourStepButtonProps extends ButtonProps {
+    /** Renders your own button (a design-system component) with the wired-up props. */
+    render?: (props: ButtonProps) => ReactElement;
+}
+interface TourStepNextProps extends TourStepButtonProps {
+    /** Labels for the last step and the others. Ignored when `children` is given. */
+    doneLabel?: ReactNode;
+    nextLabel?: ReactNode;
+    /** Steps that advance when the anchor is pressed hide this button unless set. */
+    showOnPress?: boolean;
+}
+declare function Next({ doneLabel, nextLabel, showOnPress, children, onClick, ...rest }: TourStepNextProps): react.JSX.Element | null;
+declare function Back({ children, onClick, ...rest }: TourStepButtonProps): react.JSX.Element | null;
+declare function Skip({ children, onClick, ...rest }: TourStepButtonProps): react.JSX.Element;
+declare function Close({ children, ...rest }: TourStepButtonProps): react.JSX.Element;
+declare const TourStep: {
+    Root: typeof Root;
+    Title: typeof Title;
+    Body: typeof Body;
+    Progress: typeof Progress;
+    Next: typeof Next;
+    Back: typeof Back;
+    Skip: typeof Skip;
+    Close: typeof Close;
+};
+
+export { BodyPortal, Presentation, type TourAnchorProps, TourOverlay, type TourOverlayProps, TourPopover, type TourPopoverProps, TourSpotlight, type TourSpotlightProps, TourStep, type TourStepButtonProps, type TourStepNextProps, type TourStepProgressProps, type TourStepRootProps, browserSessionStore, getAnchorElement, localStorageStore, registerAnchor, useElementRect, useTourAnchor, waitForAnchor };

package/dist/web/index.js

@@ -0,0 +1,34 @@
+'use client';
+import {
+  BodyPortal,
+  TourOverlay,
+  TourPopover,
+  TourSpotlight,
+  TourStep,
+  browserSessionStore,
+  createWebAdapter,
+  getAnchorElement,
+  localStorageStore,
+  registerAnchor,
+  useElementRect,
+  useTourAnchor,
+  waitForAnchor
+} from "../chunk-7B66QEMY.js";
+import "../chunk-VC6XLWM3.js";
+import "../chunk-FM64UDKJ.js";
+export {
+  BodyPortal,
+  TourOverlay,
+  TourPopover,
+  TourSpotlight,
+  TourStep,
+  browserSessionStore,
+  createWebAdapter,
+  getAnchorElement,
+  localStorageStore,
+  registerAnchor,
+  useElementRect,
+  useTourAnchor,
+  waitForAnchor
+};
+//# sourceMappingURL=index.js.map

package/dist/web/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}