featuredrop 1.1.0 → 1.3.0

package/dist/preact.d.ts

@@ -0,0 +1,1213 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties, RefObject } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** Entry type label — determines default icon/color in UI */
+type FeatureType = "feature" | "improvement" | "fix" | "breaking";
+/** Priority level for announcements */
+type FeaturePriority = "critical" | "normal" | "low";
+/** Motion preset for built-in component transitions */
+type FeatureDropAnimationPreset = "none" | "subtle" | "normal" | "playful";
+/** Call-to-action for a feature entry */
+interface FeatureCTA {
+    /** Button/link label */
+    label: string;
+    /** URL to navigate to */
+    url: string;
+}
+/** Variant-level overrides for A/B announcement testing */
+interface FeatureVariant {
+    /** Optional variant-specific label override */
+    label?: string;
+    /** Optional variant-specific description override */
+    description?: string;
+    /** Optional variant-specific image override */
+    image?: string;
+    /** Optional variant-specific CTA override */
+    cta?: FeatureCTA;
+    /** Optional variant-specific metadata overrides */
+    meta?: Record<string, unknown>;
+}
+/** Audience targeting rule — determines which user segments see a feature */
+interface AudienceRule {
+    /** Plans that should see this feature (e.g. ["pro", "enterprise"]) */
+    plan?: string[];
+    /** Roles that should see this feature (e.g. ["admin", "editor"]) */
+    role?: string[];
+    /** Regions that should see this feature (e.g. ["us", "eu"]) */
+    region?: string[];
+    /** Arbitrary key-value pairs for custom matching logic */
+    custom?: Record<string, unknown>;
+}
+/** User context for audience targeting */
+interface UserContext {
+    /** Current user's plan (e.g. "pro", "free") */
+    plan?: string;
+    /** Current user's role (e.g. "admin", "viewer") */
+    role?: string;
+    /** Current user's region (e.g. "us", "eu") */
+    region?: string;
+    /** Arbitrary traits for custom matching logic */
+    traits?: Record<string, unknown>;
+}
+/** Custom audience matcher function */
+type AudienceMatchFn = (audience: AudienceRule, userContext: UserContext) => boolean;
+/** Feature flag resolver interface for gating announcement visibility */
+interface FeatureFlagBridge {
+    isEnabled: (flagKey: string, userContext?: UserContext) => boolean;
+}
+/** Dependency gates for progressive feature discovery */
+interface FeatureDependencies {
+    /** Features the user must have seen before this one can surface */
+    seen?: string[];
+    /** Features the user must have clicked before this one can surface */
+    clicked?: string[];
+    /** Features the user must have dismissed before this one can surface */
+    dismissed?: string[];
+}
+/** Runtime context used by trigger evaluation */
+interface TriggerContext {
+    /** Current app route/path */
+    path?: string;
+    /** Named events observed in this session */
+    events?: ReadonlySet<string>;
+    /** Named milestone flags reached in this session */
+    milestones?: ReadonlySet<string>;
+    /** Usage counters keyed by event/pattern name */
+    usage?: Record<string, number>;
+    /** Session elapsed time in milliseconds */
+    elapsedMs?: number;
+    /** Scroll completion percentage (0-100) */
+    scrollPercent?: number;
+    /** Optional additional trigger context */
+    metadata?: Record<string, unknown>;
+}
+type FeatureTrigger = {
+    type: "page";
+    match: string | RegExp;
+} | {
+    type: "usage";
+    event: string;
+    minActions?: number;
+} | {
+    type: "time";
+    minSeconds: number;
+} | {
+    type: "milestone";
+    event: string;
+} | {
+    type: "frustration";
+    pattern: string;
+    threshold?: number;
+} | {
+    type: "scroll";
+    minPercent?: number;
+} | {
+    type: "custom";
+    evaluate: (context: TriggerContext) => boolean;
+};
+/** A single feature entry in the manifest */
+interface FeatureEntry {
+    /** Unique identifier for the feature */
+    id: string;
+    /** Human-readable label (e.g. "Decision Journal") */
+    label: string;
+    /** Optional longer description (supports markdown in UI components) */
+    description?: string;
+    /**
+     * Semantic version targeting.
+     * If provided as an object, requires `appVersion` to be supplied to the provider/helpers.
+     * - introduced: earliest app version that includes this feature
+     * - showNewUntil: stop showing "new" once appVersion reaches this
+     * - deprecatedAt: hide feature for app versions at or above this (optional safety)
+     * - showIn: range string, e.g. ">=2.5.0 <3.0.0"
+     */
+    version?: string | {
+        introduced?: string;
+        showNewUntil?: string;
+        deprecatedAt?: string;
+        showIn?: string;
+    };
+    /** ISO date when this feature was released */
+    releasedAt: string;
+    /** ISO date after which the "new" badge should stop showing */
+    showNewUntil: string;
+    /** Optional key to match navigation items (e.g. "/journal", "settings") */
+    sidebarKey?: string;
+    /** Optional grouping category (e.g. "ai", "billing", "core") */
+    category?: string;
+    /** Optional product scope (`"*"`, `"askverdict"`, etc.) for multi-product manifests */
+    product?: string;
+    /** Optional URL to link to (e.g. docs page, changelog entry) */
+    url?: string;
+    /** Optional feature flag key; requires a flag bridge to evaluate */
+    flagKey?: string;
+    /** Entry type — determines default icon/color in UI components */
+    type?: FeatureType;
+    /** Priority level — critical entries get special treatment in UI */
+    priority?: FeaturePriority;
+    /** Optional image/screenshot URL */
+    image?: string;
+    /** Optional call-to-action button */
+    cta?: FeatureCTA;
+    /** ISO date — entry is hidden until this date (scheduled publishing) */
+    publishAt?: string;
+    /** Optional arbitrary metadata */
+    meta?: Record<string, unknown>;
+    /** A/B variants keyed by variant name (e.g. control, treatment_a) */
+    variants?: Record<string, FeatureVariant>;
+    /** Percentage split per variant (same order as variants object keys) */
+    variantSplit?: number[];
+    /** Audience targeting — if set, only matching users see this feature */
+    audience?: AudienceRule;
+    /** Dependency requirements (progressive disclosure sequencing) */
+    dependsOn?: FeatureDependencies;
+    /** Contextual trigger rule */
+    trigger?: FeatureTrigger;
+}
+/** The full feature manifest — an array of feature entries */
+type FeatureManifest = readonly FeatureEntry[];
+/**
+ * Storage adapter interface — implement for your persistence layer.
+ *
+ * The adapter bridges two data sources:
+ * - **Watermark**: a server-side timestamp ("features seen at")
+ * - **Dismissed IDs**: client-side per-feature dismissals
+ */
+interface StorageAdapter {
+    /** Get the user's "features seen at" watermark (ISO string or null) */
+    getWatermark(): string | null;
+    /** Get the set of individually dismissed feature IDs */
+    getDismissedIds(): ReadonlySet<string>;
+    /** Dismiss a single feature by ID */
+    dismiss(id: string): void;
+    /** Dismiss all features — sets watermark to `now` and clears dismissals */
+    dismissAll(now: Date): Promise<void>;
+}
+/** Analytics event callbacks — pipe to your analytics provider */
+interface AnalyticsCallbacks {
+    /** Fired when a feature badge becomes visible to the user */
+    onFeatureSeen?: (feature: FeatureEntry) => void;
+    /** Fired when a user dismisses a single feature */
+    onFeatureDismissed?: (feature: FeatureEntry) => void;
+    /** Fired when a user clicks a feature link or CTA */
+    onFeatureClicked?: (feature: FeatureEntry) => void;
+    /** Fired when the changelog widget is opened */
+    onWidgetOpened?: () => void;
+    /** Fired when the changelog widget is closed */
+    onWidgetClosed?: () => void;
+    /** Fired when all features are dismissed at once */
+    onAllDismissed?: () => void;
+}
+
+interface ThrottleOptions {
+    maxSimultaneousBadges?: number;
+    maxSimultaneousSpotlights?: number;
+    maxToastsPerSession?: number;
+    minTimeBetweenModals?: number;
+    minTimeBetweenTours?: number;
+    sessionCooldown?: number;
+    respectDoNotDisturb?: boolean;
+}
+
+type AdoptionEventType = "feature_seen" | "feature_clicked" | "feature_dismissed" | "tour_started" | "tour_completed" | "tour_skipped" | "checklist_task_completed" | "checklist_completed" | "survey_submitted" | "feedback_submitted" | "announcement_shown" | "cta_clicked";
+interface AdoptionEvent {
+    type: AdoptionEventType;
+    featureId?: string;
+    tourId?: string;
+    variant?: string;
+    timestamp: string;
+    sessionId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
+type AdoptionEventInput = Omit<AdoptionEvent, "timestamp"> & {
+    timestamp?: string;
+};
+interface AnalyticsAdapter {
+    track: (event: AdoptionEvent) => void | Promise<void>;
+    trackBatch?: (events: AdoptionEvent[]) => void | Promise<void>;
+}
+interface AnalyticsCollectorOptions {
+    adapter: AnalyticsAdapter;
+    batchSize?: number;
+    flushInterval?: number;
+    sampleRate?: number;
+    enabled?: boolean;
+    sessionId?: string;
+    userId?: string;
+    now?: () => Date;
+    random?: () => number;
+}
+declare class AnalyticsCollector {
+    private adapter;
+    private queue;
+    private batchSize;
+    private flushInterval;
+    private sampleRate;
+    private enabled;
+    private now;
+    private random;
+    private sessionId?;
+    private userId?;
+    private timer;
+    private flushing;
+    constructor(options: AnalyticsCollectorOptions);
+    setEnabled(enabled: boolean): void;
+    setContext(context: {
+        sessionId?: string;
+        userId?: string;
+    }): void;
+    getQueueSize(): number;
+    track(event: AdoptionEventInput): void;
+    flush(): Promise<void>;
+    destroy(): Promise<void>;
+    private startTimer;
+}
+interface FeatureEngagementMetrics {
+    seen: number;
+    clicked: number;
+    dismissed: number;
+}
+interface AdoptionMetrics {
+    getAdoptionRate: (featureId: string) => number;
+    getTourCompletionRate: (tourId: string) => number;
+    getChecklistCompletionRate: (checklistId: string) => number;
+    getFeatureEngagement: (featureId: string) => FeatureEngagementMetrics;
+    getVariantPerformance: (featureId: string) => Record<string, number>;
+}
+
+interface FeatureDropTranslations {
+    newBadge: string;
+    whatsNewTitle: string;
+    markAllRead: string;
+    allCaughtUp: string;
+    close: string;
+    changelogTitle: string;
+    searchPlaceholder: string;
+    allCategories: string;
+    noUpdatesYet: string;
+    loadMore: string;
+    share: string;
+    skipToEntries: string;
+    newFeatureCount: (count: number) => string;
+    stepOf: (current: number, total: number) => string;
+    back: string;
+    next: string;
+    skip: string;
+    finish: string;
+    gotIt: string;
+    announcement: string;
+    feedbackTitle: string;
+    feedbackTrigger: string;
+    feedbackSubmitted: string;
+    submit: string;
+    cancel: string;
+    askLater: string;
+}
+
+interface FeatureDropProviderProps {
+    /** The feature manifest — typically a frozen array of FeatureEntry objects */
+    manifest: FeatureManifest;
+    /** Storage adapter instance (e.g. LocalStorageAdapter, MemoryAdapter) */
+    storage: StorageAdapter;
+    /** Optional analytics callbacks — pipe to your analytics provider */
+    analytics?: AnalyticsCallbacks;
+    /** Optional error callback for monitoring caught component errors */
+    onError?: (error: unknown, context?: {
+        component?: string;
+        componentStack?: string;
+    }) => void;
+    /** User context for audience targeting (plan, role, region, traits) */
+    userContext?: UserContext;
+    /** Custom audience matcher — overrides default AND/OR matching logic */
+    matchAudience?: AudienceMatchFn;
+    /** Current app version (semver) for version-pinned features */
+    appVersion?: string;
+    /** Current product scope for multi-product manifests */
+    product?: string;
+    /** Announcement throttling and session cooldown controls */
+    throttle?: ThrottleOptions;
+    /** Stable identifier for A/B variant assignment (e.g. userId) */
+    variantKey?: string;
+    /** Optional adoption analytics collector */
+    collector?: AnalyticsCollector;
+    /** Feature flag bridge for evaluating `feature.flagKey` visibility */
+    flagBridge?: FeatureFlagBridge;
+    /** Locale code for built-in component translations (e.g. "en", "fr", "es") */
+    locale?: string;
+    /** Animation preset for built-in component transitions */
+    animation?: FeatureDropAnimationPreset;
+    /** Custom translation overrides for built-in component strings */
+    translations?: Partial<FeatureDropTranslations>;
+    children: ReactNode;
+}
+/**
+ * Provides feature discovery state to the component tree.
+ *
+ * Wrap your app (or a subtree) with this provider to enable
+ * `useFeatureDrop`, `useNewFeature`, `useNewCount`, and other hooks.
+ */
+declare function FeatureDropProvider({ manifest, storage, analytics, onError, userContext, matchAudience: matchAudienceFn, appVersion, product, throttle, variantKey, collector, flagBridge, locale, animation, translations: translationOverrides, children, }: FeatureDropProviderProps): react_jsx_runtime.JSX.Element;
+
+interface FeatureDropTheme {
+    colors: {
+        primary: string;
+        background: string;
+        text: string;
+        textMuted: string;
+        border: string;
+        success: string;
+        warning: string;
+        error: string;
+    };
+    fonts: {
+        family: string;
+        sizeBase: string;
+        sizeSm: string;
+        sizeLg: string;
+    };
+    spacing: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+    };
+    radii: {
+        sm: string;
+        md: string;
+        lg: string;
+        full: string;
+    };
+    shadows: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+    zIndex: {
+        base: number;
+        tooltip: number;
+        modal: number;
+        overlay: number;
+    };
+}
+type FeatureDropThemePreset = "light" | "dark" | "auto" | "minimal" | "vibrant";
+type FeatureDropThemeOverrides = {
+    [K in keyof FeatureDropTheme]?: Partial<FeatureDropTheme[K]>;
+};
+type FeatureDropThemeInput = FeatureDropThemePreset | FeatureDropThemeOverrides | FeatureDropTheme;
+
+interface ThemeProviderProps {
+    /** Theme preset ("light" | "dark" | "auto" | "minimal" | "vibrant") or custom theme overrides */
+    theme?: FeatureDropThemeInput;
+    /** Optional CSS class for the wrapper element */
+    className?: string;
+    /** Optional inline style merged after theme CSS variables */
+    style?: CSSProperties;
+    children: ReactNode;
+}
+/**
+ * Applies FeatureDrop theme tokens as CSS custom properties to a subtree.
+ *
+ * All featuredrop components inside this provider inherit the resolved theme.
+ */
+declare function ThemeProvider({ theme, className, style, children, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+
+interface FeatureDropContextValue {
+    /** Full manifest provided to the provider */
+    manifest: FeatureEntry[] | readonly FeatureEntry[];
+    /** All currently "new" features */
+    newFeatures: FeatureEntry[];
+    /** New features currently queued by throttling rules */
+    queuedFeatures: FeatureEntry[];
+    /** Count of new features */
+    newCount: number;
+    /** Count before throttling (all pending new features) */
+    totalNewCount: number;
+    /** All new features sorted by priority then release date */
+    newFeaturesSorted: FeatureEntry[];
+    /** Check if a sidebar key has any new features */
+    isNew: (sidebarKey: string) => boolean;
+    /** Dismiss a single feature by ID */
+    dismiss: (id: string) => void;
+    /** Dismiss all features (marks all as seen) */
+    dismissAll: () => Promise<void>;
+    /** Get the feature entry for a sidebar key (if it's new) */
+    getFeature: (sidebarKey: string) => FeatureEntry | undefined;
+    /** Whether quiet mode (Do Not Disturb) is enabled */
+    quietMode: boolean;
+    /** Enable/disable quiet mode */
+    setQuietMode: (enabled: boolean) => void;
+    /** Mark a feature as seen for dependency-chain resolution */
+    markFeatureSeen: (featureId: string) => void;
+    /** Mark a feature as clicked for dependency-chain resolution */
+    markFeatureClicked: (featureId: string) => void;
+    /** Remaining toasts allowed in this session under throttle rules */
+    getRemainingToastSlots: () => number;
+    /** Mark toasts as shown in this session */
+    markToastsShown: (featureIds: string[]) => void;
+    /** Whether a modal can open right now under throttle rules */
+    canShowModal: (priority?: FeaturePriority) => boolean;
+    /** Record a modal display timestamp */
+    markModalShown: () => void;
+    /** Whether a tour can start right now under throttle rules */
+    canShowTour: () => boolean;
+    /** Record a tour start timestamp */
+    markTourShown: () => void;
+    /** Acquire/release spotlight slots under maxSimultaneousSpotlights */
+    acquireSpotlightSlot: (id: string, priority?: FeaturePriority) => boolean;
+    releaseSpotlightSlot: (id: string) => void;
+    /** Number of currently active spotlight slots */
+    activeSpotlightCount: number;
+    /** Emit an adoption analytics event (collector-backed when configured) */
+    trackAdoptionEvent: (event: AdoptionEventInput) => void;
+    /** Report a component/runtime error to provider-level monitoring hooks */
+    reportError: (error: unknown, context?: {
+        component?: string;
+        componentStack?: string;
+    }) => void;
+    /** Active locale code used by built-in UI strings */
+    locale: string;
+    /** Text direction derived from locale */
+    direction: "ltr" | "rtl";
+    /** Active motion preset for built-in component transitions */
+    animation: FeatureDropAnimationPreset;
+    /** Resolved translation strings for built-in React components */
+    translations: FeatureDropTranslations;
+    /** Track a named usage event for trigger rules */
+    trackUsageEvent: (event: string, delta?: number) => void;
+    /** Track a named trigger event for trigger rules */
+    trackTriggerEvent: (event: string) => void;
+    /** Mark a milestone for trigger rules */
+    trackMilestone: (event: string) => void;
+    /** Manually override current path for page trigger rules */
+    setTriggerPath: (path: string) => void;
+}
+declare const FeatureDropContext: react.Context<FeatureDropContextValue | null>;
+
+/**
+ * Access the full feature discovery context.
+ *
+ * Returns: `{ newFeatures, newCount, isNew, dismiss, dismissAll, getFeature }`
+ *
+ * @throws Error if used outside of `<FeatureDropProvider>`
+ */
+declare function useFeatureDrop(): FeatureDropContextValue;
+
+interface UseNewFeatureResult {
+    /** Whether this sidebar key has a new feature */
+    isNew: boolean;
+    /** The feature entry, if new */
+    feature: FeatureEntry | undefined;
+    /** Dismiss the feature for this sidebar key */
+    dismiss: () => void;
+}
+/**
+ * Check if a single navigation item has a new feature.
+ *
+ * @param sidebarKey - The key to check (e.g. "/journal", "settings")
+ * @returns `{ isNew, feature, dismiss }`
+ */
+declare function useNewFeature(sidebarKey: string): UseNewFeatureResult;
+
+/**
+ * Get the count of currently new features.
+ *
+ * Useful for rendering a badge count on a "What's New" button.
+ *
+ * @returns The number of new features
+ */
+declare function useNewCount(): number;
+
+interface UseTabNotificationOptions {
+    /** Whether tab notifications are enabled. Default: true */
+    enabled?: boolean;
+    /** Template string. `{count}` is replaced with the number. Default: "({count}) {title}" */
+    template?: string;
+    /** Enable flashing/blinking pattern for attention. Default: false */
+    flash?: boolean;
+    /** Flash interval in ms. Default: 1500 */
+    flashInterval?: number;
+}
+/**
+ * Updates the browser tab title with the unread feature count.
+ *
+ * Shows "(3) My App" when there are new features, restores the original
+ * title when all features are read. Optional flash/blink pattern for attention.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useTabNotification();
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @example With flash
+ * ```tsx
+ * useTabNotification({ flash: true, template: "[{count} new] {title}" });
+ * ```
+ */
+declare function useTabNotification(options?: UseTabNotificationOptions): void;
+
+declare function useAdoptionAnalytics(events: AdoptionEvent[]): AdoptionMetrics;
+
+interface TourStep {
+    id: string;
+    target: string | RefObject<HTMLElement | null>;
+    title: string;
+    content: string | ReactNode;
+    placement?: "top" | "bottom" | "left" | "right" | "auto";
+    action?: "click" | "input" | "custom";
+    advanceOn?: {
+        selector: string;
+        event: string;
+    };
+    highlightTarget?: boolean;
+    beforeStep?: () => Promise<void>;
+    afterStep?: () => Promise<void>;
+    skipable?: boolean;
+}
+interface TourRenderProps {
+    isActive: boolean;
+    step: TourStep | null;
+    stepIndex: number;
+    totalSteps: number;
+    startTour: () => void;
+    nextStep: () => void;
+    prevStep: () => void;
+    skipTour: () => void;
+    closeTour: () => void;
+}
+interface TourProps {
+    id: string;
+    steps: TourStep[];
+    onComplete?: () => void;
+    onSkip?: (stepId: string) => void;
+    onTourStarted?: () => void;
+    onTourCompleted?: () => void;
+    onTourSkipped?: (stepId: string) => void;
+    onStepViewed?: (step: TourStep, index: number) => void;
+    overlay?: boolean;
+    showProgress?: boolean;
+    keyboard?: boolean;
+    persistence?: boolean;
+    children?: (props: TourRenderProps) => ReactNode;
+}
+
+interface TourSnapshot {
+    isActive: boolean;
+    currentStepIndex: number;
+    currentStep: TourStep | null;
+    totalSteps: number;
+}
+
+interface UseTourResult {
+    startTour: () => void;
+    nextStep: () => void;
+    prevStep: () => void;
+    skipTour: () => void;
+    closeTour: () => void;
+    currentStep: TourSnapshot["currentStep"];
+    currentStepIndex: number;
+    totalSteps: number;
+    isActive: boolean;
+}
+declare function useTour(id: string): UseTourResult;
+
+interface TourSequenceItem {
+    featureId: string;
+    tourId: string;
+}
+interface UseTourSequencerResult {
+    nextTourId: string | null;
+    nextFeatureId: string | null;
+    remainingTours: number;
+    startNextTour: () => boolean;
+}
+declare function useTourSequencer(sequence: TourSequenceItem[]): UseTourSequencerResult;
+
+interface UseChecklistResult {
+    completeTask: (taskId: string) => void;
+    resetChecklist: () => void;
+    dismissChecklist: () => void;
+    toggleCollapsed: () => void;
+    isComplete: boolean;
+    progress: {
+        completed: number;
+        total: number;
+        percent: number;
+    };
+    tasks: Array<{
+        id: string;
+        completed: boolean;
+    }>;
+    dismissed: boolean;
+    collapsed: boolean;
+}
+declare function useChecklist(id: string): UseChecklistResult;
+
+type SurveyType = "nps" | "csat" | "ces" | "custom";
+type SurveyQuestionType = "single-choice" | "multi-choice" | "text";
+interface SurveyQuestion {
+    id: string;
+    type: SurveyQuestionType;
+    prompt: string;
+    options?: string[];
+    required?: boolean;
+}
+interface SurveyTriggerRules {
+    signupAt?: string | Date;
+    minDaysSinceSignup?: number;
+    featureUsageIds?: string[];
+    pageMatch?: string | RegExp | ((path: string) => boolean);
+    sampleRate?: number;
+    maxFrequencyDays?: number;
+    askLaterCooldownDays?: number;
+}
+interface SurveyPayload {
+    id: string;
+    type: SurveyType;
+    prompt?: string;
+    score?: number;
+    responses?: Record<string, unknown>;
+    feedback?: string;
+    timestamp: string;
+    url: string;
+    featureId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SurveyRenderProps {
+    isOpen: boolean;
+    isSubmitting: boolean;
+    submitted: boolean;
+    canShow: boolean;
+    error: string | null;
+    type: SurveyType;
+    score: number | null;
+    feedback: string;
+    responses: Record<string, unknown>;
+    show: (options?: {
+        force?: boolean;
+    }) => boolean;
+    hide: () => void;
+    askLater: () => void;
+    setScore: (value: number | null) => void;
+    setFeedback: (value: string) => void;
+    setResponse: (questionId: string, value: unknown) => void;
+    submit: () => Promise<boolean>;
+}
+interface SurveyProps {
+    id: string;
+    type: SurveyType;
+    prompt?: string;
+    featureId?: string;
+    questions?: SurveyQuestion[];
+    trigger?: "auto" | "manual";
+    triggerRules?: SurveyTriggerRules;
+    defaultOpen?: boolean;
+    showAskLater?: boolean;
+    submitLabel?: string;
+    askLaterLabel?: string;
+    closeLabel?: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+    onSubmit: (payload: SurveyPayload) => Promise<void> | void;
+    onAskLater?: () => void;
+    onDismiss?: () => void;
+    className?: string;
+    style?: CSSProperties;
+    children?: (props: SurveyRenderProps) => ReactNode;
+}
+
+interface UseSurveyResult {
+    show: (options?: {
+        force?: boolean;
+    }) => boolean;
+    hide: () => void;
+    askLater: () => void;
+    isOpen: boolean;
+    submitted: boolean;
+    canShow: boolean;
+    type: SurveyType;
+}
+declare function useSurvey(id: string): UseSurveyResult;
+
+interface NewBadgeRenderProps {
+    /** Whether the feature is currently new */
+    isNew: boolean;
+}
+interface NewBadgeProps {
+    /** Display variant */
+    variant?: "pill" | "dot" | "count";
+    /** Whether to show the badge (typically from `useNewFeature().isNew`) */
+    show?: boolean;
+    /** Count to display when variant is "count" */
+    count?: number;
+    /** Text label for the pill variant. Default: "New" */
+    label?: string;
+    /** Dismiss callback. If set with `dismissOnClick`, clicking dismisses. */
+    onDismiss?: () => void;
+    /** Whether clicking the badge should trigger onDismiss */
+    dismissOnClick?: boolean;
+    /** Additional CSS class */
+    className?: string;
+    /** Additional inline styles (merged with defaults) */
+    style?: CSSProperties;
+    /** Render prop for full customization */
+    children?: (props: NewBadgeRenderProps) => ReactNode;
+}
+
+type ReactionCounts = Record<string, number>;
+
+interface ChangelogEntryRenderProps {
+    feature: FeatureEntry;
+    dismiss: () => void;
+    onFeatureClick?: () => void;
+    reactions?: ReactionCounts;
+    userReaction?: string | null;
+    canReact?: boolean;
+    react?: (reaction: string) => void;
+}
+interface ChangelogWidgetRenderProps {
+    /** Whether the widget is currently open */
+    isOpen: boolean;
+    /** Open the widget */
+    open: () => void;
+    /** Close the widget */
+    close: () => void;
+    /** Toggle open/close */
+    toggle: () => void;
+    /** Current new feature count */
+    count: number;
+    /** Sorted features to display */
+    features: FeatureEntry[];
+    /** Dismiss a single feature */
+    dismiss: (id: string) => void;
+    /** Dismiss all features */
+    dismissAll: () => Promise<void>;
+}
+interface ChangelogWidgetProps {
+    /** Display variant */
+    variant?: "panel" | "modal" | "popover";
+    /** Title shown in the widget header. Default: "What's New" */
+    title?: string;
+    /** Text for the trigger button. Default: "What's New" */
+    triggerLabel?: string;
+    /** Show trigger badge count. Default: true */
+    showCount?: boolean;
+    /** Text for the "mark all as read" button. Default: "Mark all as read" */
+    markAllLabel?: string;
+    /** Whether to show the mark-all button. Default: true */
+    showMarkAll?: boolean;
+    /** Text shown when no new features exist. Default: "You're all caught up!" */
+    emptyLabel?: string;
+    /** Max height for the feed area. Default: "400px" */
+    maxHeight?: string;
+    /** Date display mode for entry metadata. Default: "absolute" */
+    dateFormat?: "absolute" | "relative";
+    /** Analytics callbacks */
+    analytics?: AnalyticsCallbacks;
+    /** Additional CSS class for the container */
+    className?: string;
+    /** Additional inline styles for the container */
+    style?: CSSProperties;
+    /** Optional component-scoped theme preset or overrides */
+    theme?: FeatureDropThemeInput;
+    /** Render prop for full customization — receives widget state */
+    children?: (props: ChangelogWidgetRenderProps) => ReactNode;
+    /** Custom render for each entry — receives feature + dismiss callback */
+    renderEntry?: (props: ChangelogEntryRenderProps) => ReactNode;
+    /** Custom render for the trigger button */
+    renderTrigger?: (props: {
+        count: number;
+        onClick: () => void;
+    }) => ReactNode;
+    /** Show reaction controls on each entry. Default: false */
+    showReactions?: boolean;
+    /** Reaction options. Default: 👍 ❤️ 🎉 👀 👎 */
+    reactions?: string[];
+    /** Callback fired when a reaction is persisted */
+    onReaction?: (feature: FeatureEntry, reaction: string, counts: ReactionCounts) => void;
+}
+
+interface SpotlightRenderProps {
+    /** The feature being spotlighted */
+    feature: FeatureEntry | undefined;
+    /** Whether the spotlight is active */
+    isActive: boolean;
+    /** Whether the tooltip is visible */
+    isTooltipOpen: boolean;
+    /** Show the tooltip */
+    openTooltip: () => void;
+    /** Hide the tooltip */
+    closeTooltip: () => void;
+    /** Dismiss this spotlight permanently */
+    dismiss: () => void;
+}
+interface SpotlightProps {
+    /** The feature ID to spotlight */
+    featureId: string;
+    /** Ref to the target DOM element — beacon will be positioned over it */
+    targetRef?: RefObject<HTMLElement | null>;
+    /** CSS selector for the target element (alternative to targetRef) */
+    targetSelector?: string;
+    /** Tooltip placement relative to target */
+    placement?: "top" | "bottom" | "left" | "right";
+    /** Beacon size in pixels. Default: 12 */
+    beaconSize?: number;
+    /** Auto-dismiss after the tooltip is seen */
+    autoDismiss?: boolean;
+    /** Delay before auto-dismiss in ms. Default: 5000 */
+    autoDismissDelay?: number;
+    /** Analytics callbacks */
+    analytics?: AnalyticsCallbacks;
+    /** Additional CSS class */
+    className?: string;
+    /** Custom tooltip content */
+    tooltipContent?: ReactNode;
+    /** Render prop for full customization */
+    children?: (props: SpotlightRenderProps) => ReactNode;
+}
+
+type BannerVariant = "info" | "success" | "warning" | "announcement";
+interface BannerRenderProps {
+    /** The feature being announced */
+    feature: FeatureEntry | undefined;
+    /** Whether the banner is active */
+    isActive: boolean;
+    /** Whether the banner has been dismissed this session */
+    isDismissed: boolean;
+    /** Dismiss the banner permanently */
+    dismiss: () => void;
+}
+interface BannerProps {
+    /** Feature ID to display as a banner */
+    featureId: string;
+    /** Banner visual variant. Default: "announcement" */
+    variant?: BannerVariant;
+    /** Whether the banner is dismissible. Default: true */
+    dismissible?: boolean;
+    /** Position mode. Default: "sticky" */
+    position?: "sticky" | "inline" | "fixed";
+    /** Analytics callbacks */
+    analytics?: AnalyticsCallbacks;
+    /** Additional CSS class */
+    className?: string;
+    /** Additional inline styles */
+    style?: CSSProperties;
+    /** Render prop for full customization */
+    children?: (props: BannerRenderProps) => ReactNode;
+}
+
+interface ToastRenderProps {
+    /** Features currently showing as toasts */
+    toasts: FeatureEntry[];
+    /** Dismiss a specific toast */
+    dismiss: (id: string) => void;
+    /** Dismiss all toasts */
+    dismissAll: () => void;
+}
+interface ToastProps {
+    /** Feature IDs to show as toasts. If omitted, shows all new features. */
+    featureIds?: string[];
+    /** Max number of visible toasts at once. Default: 3 */
+    maxVisible?: number;
+    /** Auto-dismiss delay in ms. Default: 8000. Set to 0 to disable. */
+    autoDismissMs?: number;
+    /** Position on screen. Default: "bottom-right" */
+    position?: "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";
+    /** Analytics callbacks */
+    analytics?: AnalyticsCallbacks;
+    /** Additional CSS class for the container */
+    className?: string;
+    /** Additional inline styles for the container */
+    style?: CSSProperties;
+    /** Render prop for full customization */
+    children?: (props: ToastRenderProps) => ReactNode;
+    /** Custom render for each toast */
+    renderToast?: (props: {
+        feature: FeatureEntry;
+        dismiss: () => void;
+    }) => ReactNode;
+}
+
+type PaginationMode = "infinite-scroll" | "load-more" | "numbered";
+interface ChangelogPageProps {
+    pageSize?: number;
+    pagination?: PaginationMode;
+    showFilters?: boolean;
+    showSearch?: boolean;
+    categories?: string[];
+    emptyState?: ReactNode;
+    renderEntry?: (entry: FeatureEntry, index: number) => ReactNode;
+    formatDate?: (date: string) => string;
+    dateFormat?: "absolute" | "relative";
+    basePath?: string;
+    manifest?: FeatureManifest;
+    className?: string;
+    style?: CSSProperties;
+    theme?: FeatureDropThemeInput;
+    showReactions?: boolean;
+    reactions?: string[];
+    onReaction?: (entry: FeatureEntry, reaction: string, counts: ReactionCounts) => void;
+}
+
+interface ChecklistTask {
+    id: string;
+    title: string;
+    description?: string;
+    completed?: boolean;
+    completionEvent?: string;
+    action?: {
+        type: "tour" | "link" | "callback";
+        target: string;
+    };
+    icon?: ReactNode;
+    estimatedTime?: string;
+}
+interface ChecklistRenderProps {
+    tasks: ChecklistTask[];
+    completedIds: Set<string>;
+    completeTask: (taskId: string) => void;
+    resetChecklist: () => void;
+    dismissChecklist: () => void;
+    isComplete: boolean;
+    progress: {
+        completed: number;
+        total: number;
+        percent: number;
+    };
+    collapsed: boolean;
+    toggleCollapsed: () => void;
+}
+interface ChecklistProps {
+    id: string;
+    tasks: ChecklistTask[];
+    position?: "bottom-right" | "bottom-left" | "top-right" | "top-left" | "inline";
+    collapsible?: boolean;
+    showProgress?: boolean;
+    onComplete?: () => void;
+    dismissible?: boolean;
+    actionHandlers?: Record<string, () => void>;
+    children?: (props: ChecklistRenderProps) => ReactNode;
+}
+
+interface HotspotProps {
+    id: string;
+    target: string;
+    type?: "info" | "new" | "help";
+    frequency?: "once" | "every-session" | "always";
+    children: ReactNode;
+}
+interface TooltipGroupProps {
+    maxVisible?: number;
+    children: ReactNode;
+}
+
+type FeedbackEmoji = "thumbs-up" | "thumbs-down" | "heart" | "thinking" | "fire";
+interface FeedbackPayload {
+    featureId?: string;
+    text: string;
+    category?: string;
+    emoji?: FeedbackEmoji;
+    screenshot?: Blob;
+    url: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+type FeedbackRateLimit = "none" | "1-per-feature" | "1-per-session";
+interface FeedbackWidgetRenderProps {
+    isOpen: boolean;
+    isSubmitting: boolean;
+    isRateLimited: boolean;
+    submitted: boolean;
+    text: string;
+    category: string;
+    emoji: FeedbackEmoji | null;
+    screenshot: Blob | null;
+    error: string | null;
+    open: () => void;
+    close: () => void;
+    setText: (value: string) => void;
+    setCategory: (value: string) => void;
+    setEmoji: (value: FeedbackEmoji | null) => void;
+    captureScreenshot: () => Promise<void>;
+    submit: () => Promise<void>;
+}
+interface FeedbackWidgetProps {
+    featureId?: string;
+    onSubmit: (payload: FeedbackPayload) => Promise<void> | void;
+    showScreenshot?: boolean;
+    showEmoji?: boolean;
+    rateLimit?: FeedbackRateLimit;
+    categories?: string[];
+    metadata?: Record<string, unknown>;
+    screenshotCapture?: () => Promise<Blob | null | undefined>;
+    triggerLabel?: string;
+    title?: string;
+    className?: string;
+    style?: CSSProperties;
+    children?: (props: FeedbackWidgetRenderProps) => ReactNode;
+}
+
+interface AnnouncementSlide {
+    id?: string;
+    title: string;
+    description?: string;
+    image?: string;
+    videoUrl?: string;
+    primaryCta?: FeatureCTA;
+    secondaryCta?: FeatureCTA;
+}
+interface AnnouncementModalRenderProps {
+    isOpen: boolean;
+    currentSlide: AnnouncementSlide | null;
+    currentSlideIndex: number;
+    totalSlides: number;
+    open: () => void;
+    close: () => void;
+    nextSlide: () => void;
+    prevSlide: () => void;
+    dismiss: () => void;
+}
+interface AnnouncementModalProps {
+    id?: string;
+    featureId?: string;
+    feature?: FeatureEntry;
+    trigger?: "auto" | "manual";
+    defaultOpen?: boolean;
+    slides?: AnnouncementSlide[];
+    frequency?: "once" | "every-session" | "always";
+    dismissible?: boolean;
+    mobileBreakpoint?: number;
+    onOpen?: () => void;
+    onDismiss?: () => void;
+    onPrimaryCtaClick?: (slide: AnnouncementSlide, index: number) => void;
+    onSecondaryCtaClick?: (slide: AnnouncementSlide, index: number) => void;
+    className?: string;
+    style?: CSSProperties;
+    children?: (props: AnnouncementModalRenderProps) => ReactNode;
+}
+
+interface SpotlightChainStep {
+    id?: string;
+    target: string;
+    title?: string;
+    content: ReactNode;
+    autoAdvanceMs?: number;
+}
+interface SpotlightChainRenderProps {
+    isActive: boolean;
+    currentStep: SpotlightChainStep | null;
+    currentStepIndex: number;
+    totalSteps: number;
+    start: () => void;
+    next: () => void;
+    skip: () => void;
+}
+interface SpotlightChainProps {
+    steps: SpotlightChainStep[];
+    startOnMount?: boolean;
+    autoAdvance?: boolean;
+    autoAdvanceMs?: number;
+    onComplete?: () => void;
+    onStepViewed?: (step: SpotlightChainStep, index: number) => void;
+    onSkip?: (step: SpotlightChainStep | null, index: number) => void;
+    children?: (props: SpotlightChainRenderProps) => ReactNode;
+}
+
+interface FeatureRequestRecord {
+    id: string;
+    featureId?: string;
+    title: string;
+    description?: string;
+    category?: string;
+    votes: number;
+    createdAt: string;
+    updatedAt: string;
+}
+type FeatureRequestSort = "votes" | "recent";
+
+interface FeatureRequestButtonRenderProps {
+    votes: number;
+    hasVoted: boolean;
+    vote: () => void;
+    request: FeatureRequestRecord | null;
+}
+interface FeatureRequestButtonProps {
+    featureId: string;
+    requestId?: string;
+    requestTitle?: string;
+    label?: string;
+    onVote?: (result: {
+        voted: boolean;
+        request: FeatureRequestRecord;
+    }) => void;
+    className?: string;
+    style?: CSSProperties;
+    children?: (props: FeatureRequestButtonRenderProps) => ReactNode;
+}
+
+interface FeatureRequestPayload extends FeatureRequestRecord {
+    metadata?: Record<string, unknown>;
+}
+interface FeatureRequestFormRenderProps {
+    requests: FeatureRequestRecord[];
+    sortBy: FeatureRequestSort;
+    title: string;
+    description: string;
+    category: string;
+    isSubmitting: boolean;
+    error: string | null;
+    setTitle: (value: string) => void;
+    setDescription: (value: string) => void;
+    setCategory: (value: string) => void;
+    setSortBy: (value: FeatureRequestSort) => void;
+    submit: () => Promise<void>;
+    vote: (requestId: string) => void;
+}
+interface FeatureRequestFormProps {
+    onSubmit?: (request: FeatureRequestPayload) => Promise<void> | void;
+    onWebhook?: (request: FeatureRequestPayload) => Promise<void> | void;
+    categories?: string[];
+    defaultSort?: FeatureRequestSort;
+    metadata?: Record<string, unknown>;
+    className?: string;
+    style?: CSSProperties;
+    children?: (props: FeatureRequestFormRenderProps) => ReactNode;
+}
+
+declare const NewBadge: react.ComponentType<NewBadgeProps>;
+
+declare const ChangelogWidget: react.ComponentType<ChangelogWidgetProps>;
+
+declare const Spotlight: react.ComponentType<SpotlightProps>;
+
+declare const Banner: react.ComponentType<BannerProps>;
+
+declare const Toast: react.ComponentType<ToastProps>;
+
+declare const ChangelogPage: react.ComponentType<ChangelogPageProps>;
+
+declare const Tour: react.ComponentType<TourProps>;
+
+declare const Checklist: react.ComponentType<ChecklistProps>;
+
+declare const Hotspot: react.ComponentType<HotspotProps>;
+declare const TooltipGroup: react.ComponentType<TooltipGroupProps>;
+
+declare const FeedbackWidget: react.ComponentType<FeedbackWidgetProps>;
+
+declare const AnnouncementModal: react.ComponentType<AnnouncementModalProps>;
+
+declare const SpotlightChain: react.ComponentType<SpotlightChainProps>;
+
+declare const Survey: react.ComponentType<SurveyProps>;
+
+declare const FeatureRequestButton: react.ComponentType<FeatureRequestButtonProps>;
+
+declare const FeatureRequestForm: react.ComponentType<FeatureRequestFormProps>;
+
+export { AnnouncementModal, type AnnouncementModalProps, type AnnouncementModalRenderProps, type AnnouncementSlide, Banner, type BannerProps, type BannerRenderProps, type BannerVariant, type ChangelogEntryRenderProps, ChangelogPage, type ChangelogPageProps, ChangelogWidget, type ChangelogWidgetProps, type ChangelogWidgetRenderProps, Checklist, type ChecklistProps, type ChecklistRenderProps, type ChecklistTask, FeatureDropContext, type FeatureDropContextValue, FeatureDropProvider, type FeatureDropProviderProps, FeatureRequestButton, type FeatureRequestButtonProps, type FeatureRequestButtonRenderProps, FeatureRequestForm, type FeatureRequestFormProps, type FeatureRequestFormRenderProps, type FeatureRequestPayload, type FeedbackEmoji, type FeedbackPayload, type FeedbackRateLimit, FeedbackWidget, type FeedbackWidgetProps, type FeedbackWidgetRenderProps, Hotspot, type HotspotProps, NewBadge, type NewBadgeProps, type NewBadgeRenderProps, type PaginationMode, Spotlight, SpotlightChain, type SpotlightChainProps, type SpotlightChainRenderProps, type SpotlightChainStep, type SpotlightProps, type SpotlightRenderProps, Survey, type SurveyPayload, type SurveyProps, type SurveyQuestion, type SurveyQuestionType, type SurveyRenderProps, type SurveyTriggerRules, type SurveyType, ThemeProvider, type ThemeProviderProps, Toast, type ToastProps, type ToastRenderProps, TooltipGroup, type TooltipGroupProps, Tour, type TourProps, type TourRenderProps, type TourSequenceItem, type TourStep, type UseChecklistResult, type UseNewFeatureResult, type UseSurveyResult, type UseTabNotificationOptions, type UseTourResult, type UseTourSequencerResult, useAdoptionAnalytics, useChecklist, useFeatureDrop, useNewCount, useNewFeature, useSurvey, useTabNotification, useTour, useTourSequencer };