featuredrop 2.6.1 → 2.7.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "featuredrop",
+  "description": "AI-assisted product adoption setup — changelogs, tours, checklists, badges, feedback widgets. Helps Claude Code configure FeatureDrop in any project.",
+  "version": "2.5.0",
+  "author": {
+    "name": "GLINR STUDIOS",
+    "url": "https://glincker.com"
+  },
+  "homepage": "https://featuredrop.dev",
+  "repository": "https://github.com/GLINCKER/featuredrop",
+  "license": "MIT",
+  "keywords": [
+    "feature-discovery",
+    "changelog",
+    "product-tours",
+    "onboarding",
+    "saas",
+    "react",
+    "developer-tools"
+  ]
+}

package/README.md

@@ -223,18 +223,84 @@ npx featuredrop migrate --from launchnotes --input launchnotes-export.json
 
 ---
 
-## React Hooks
+## Headless Hooks (for shadcn / custom UI)
 
-| Hook | Returns |
-|---|---|
-| `useFeatureDrop()` | Full context: features, count, dismiss, throttle controls |
-| `useNewFeature(key)` | Single nav item: `{ isNew, feature, dismiss }` |
-| `useNewCount()` | Current unread badge count |
-| `useTour(id)` | Imperative tour controls and step snapshot |
-| `useTourSequencer(sequence)` | Ordered multi-tour orchestration |
-| `useChecklist(id)` | Checklist progress + task controls |
-| `useSurvey(id)` | Survey controls: `show`, `hide`, `askLater` |
-| `useTabNotification()` | Browser tab title count: `"(3) My App"` |
+Don't want our components? Use hooks — **data + actions, zero JSX**:
+
+```tsx
+import { useChangelog } from 'featuredrop/react/hooks'
+import { Sheet, SheetContent, SheetTrigger } from '@/components/ui/sheet'
+import { Badge } from '@/components/ui/badge'
+
+function MyChangelog() {
+  const { newFeatures, newCount, dismiss, markAllSeen } = useChangelog()
+
+  return (
+    <Sheet onOpenChange={() => markAllSeen()}>
+      <SheetTrigger>
+        What's New {newCount > 0 && <Badge>{newCount}</Badge>}
+      </SheetTrigger>
+      <SheetContent>
+        {newFeatures.map(f => (
+          <div key={f.id} onClick={() => dismiss(f.id)}>
+            <h3>{f.label}</h3>
+            <p>{f.description}</p>
+          </div>
+        ))}
+      </SheetContent>
+    </Sheet>
+  )
+}
+```
+
+| Hook | Import | Returns |
+|---|---|---|
+| `useFeatureDrop()` | `featuredrop/react/hooks` | Full context: features, count, dismiss, throttle controls |
+| `useNewFeature(key)` | `featuredrop/react/hooks` | `{ isNew, feature, dismiss }` |
+| `useNewCount()` | `featuredrop/react/hooks` | Current unread badge count |
+| `useChangelog()` | `featuredrop/react/hooks` | `{ features, newFeatures, newCount, dismiss, dismissAll, markAllSeen, getByCategory }` |
+| `useTour(id)` | `featuredrop/react/hooks` | Imperative tour controls and step snapshot |
+| `useTourSequencer(sequence)` | `featuredrop/react/hooks` | Ordered multi-tour orchestration |
+| `useChecklist(id)` | `featuredrop/react/hooks` | Checklist progress + task controls |
+| `useSurvey(id)` | `featuredrop/react/hooks` | Survey controls: `show`, `hide`, `askLater` |
+| `useTabNotification()` | `featuredrop/react/hooks` | Browser tab title count: `"(3) My App"` |
+
+> **When to use hooks vs components:** If your project uses shadcn/ui, Radix, or any custom design system, use hooks from `featuredrop/react/hooks`. If you want out-of-the-box UI, use components from `featuredrop/react`.
+
+---
+
+## AI-Native
+
+FeatureDrop is built for the AI coding era. Your AI assistant already knows how to use it.
+
+### Claude Code Plugin
+
+```bash
+# Install the plugin — Claude Code learns FeatureDrop's API automatically
+/plugin install featuredrop
+```
+
+Then just ask: *"Add a changelog widget with auto-expiring badges to my app"* — Claude handles the rest.
+
+### Cursor / Copilot
+
+```bash
+# Auto-detect your IDE and copy the right context files
+npx featuredrop ai-setup
+```
+
+### Tailwind Plugin
+
+```ts
+// tailwind.config.ts
+import { featureDropPlugin } from 'featuredrop/tailwind'
+
+export default {
+  plugins: [featureDropPlugin()],
+  // Adds: fd-badge, fd-badge-dot, fd-badge-count, animations, CSS variables
+  // Auto dark mode, reduced-motion support
+}
+```
 
 ---
 

package/context7.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "FeatureDrop",
+  "description": "Open-source product adoption toolkit — changelogs, badges, tours, checklists, hotspots, feedback widgets, surveys. Zero dependencies, < 3 kB core, 8 framework adapters, 12 storage adapters. Free Beamer/Pendo alternative.",
+  "folders": ["apps/docs/pages/docs", "skills", "README.md"],
+  "excludeFolders": ["node_modules", "dist", "coverage", ".git", "examples", "docs-local", ".claude"],
+  "excludeFiles": ["CHANGELOG.md", "CODE_OF_CONDUCT.md", "_app.tsx", "_meta.json"],
+  "rules": [
+    "Always use subpath imports: featuredrop/react, featuredrop/react/hooks, featuredrop/adapters",
+    "Prefer hooks from featuredrop/react/hooks for custom design systems (shadcn, Radix, etc.)",
+    "Features are defined in a JSON manifest with { id, label, description, releasedAt, showNewUntil? }",
+    "Core bundle is under 3 kB gzipped with zero production dependencies",
+    "All components support headless mode via render props for full customization"
+  ]
+}

package/dist/index.d.cts

@@ -232,6 +232,94 @@ interface AnalyticsCallbacks {
     /** Fired when all features are dismissed at once */
     onAllDismissed?: () => void;
 }
+/** Display format hint from the engine */
+type DisplayFormat = "badge" | "toast" | "modal" | "banner" | "inline" | "spotlight";
+/** Interaction type tracked by the engine */
+type InteractionType = "seen" | "dismissed" | "clicked" | "completed" | "snoozed" | "hovered" | "expanded";
+/** Timing decision returned by the engine */
+interface TimingDecision {
+    /** Whether to show the announcement now */
+    show: boolean;
+    /** Reason for the decision */
+    reason: string;
+    /** Suggested delay in ms if not showing now */
+    delayMs?: number;
+    /** Confidence level (0-1) */
+    confidence: number;
+}
+/** Format recommendation from the engine */
+interface FormatRecommendation {
+    /** Recommended display format */
+    primary: DisplayFormat;
+    /** Fallback format if primary component isn't used */
+    fallback: DisplayFormat;
+    /** Reason for the recommendation */
+    reason: string;
+}
+/** Adoption score breakdown */
+interface AdoptionScore {
+    /** Overall score (0-100) */
+    score: number;
+    /** Letter grade */
+    grade: "A" | "B" | "C" | "D" | "F";
+    /** Score breakdown */
+    breakdown: {
+        /** % of features the user has explored */
+        featuresExplored: number;
+        /** Rate of dismissals (lower is better) */
+        dismissRate: number;
+        /** Rate of tour/checklist completion */
+        completionRate: number;
+        /** Whether engagement is rising, stable, or declining */
+        engagementTrend: "rising" | "stable" | "declining";
+    };
+    /** Actionable recommendations */
+    recommendations: string[];
+}
+/** Per-feature adoption status */
+interface FeatureAdoptionStatus {
+    featureId: string;
+    status: "unseen" | "seen" | "explored" | "adopted" | "dismissed";
+    firstSeen?: string;
+    lastInteraction?: string;
+    interactionCount: number;
+}
+/** Delivery context passed to the engine for timing decisions */
+interface DeliveryContext {
+    /** Current route/path */
+    currentPath: string;
+    /** Seconds since session start */
+    sessionAge: number;
+    /** Dismissals in last 5 minutes */
+    recentDismissals: number;
+    /** Feature priority */
+    featurePriority: FeaturePriority;
+}
+/**
+ * Plugin interface for the FeatureDrop engine.
+ *
+ * The open-source library defines this interface.
+ * The proprietary @featuredrop/engine implements it.
+ * Users can also build their own engine implementation.
+ *
+ * The free library works perfectly without any engine.
+ */
+interface FeatureDropEngine {
+    /** Decide whether to show a feature announcement now */
+    shouldShow(featureId: string, context: DeliveryContext): TimingDecision;
+    /** Recommend the best display format for a feature */
+    recommendFormat(featureId: string): FormatRecommendation;
+    /** Get the user's overall adoption score */
+    getAdoptionScore(): AdoptionScore;
+    /** Track a user interaction with a feature */
+    trackInteraction(featureId: string, type: InteractionType): void;
+    /** Get adoption status for a specific feature */
+    getFeatureAdoption(featureId: string): FeatureAdoptionStatus;
+    /** Initialize the engine (called by provider on mount) */
+    initialize?(): void;
+    /** Cleanup resources (called by provider on unmount) */
+    destroy?(): void;
+}
 
 /**
  * Default audience matching logic.
@@ -337,4 +425,4 @@ declare class MemoryAdapter implements StorageAdapter {
     dismissAll(now: Date): Promise<void>;
 }
 
-export { type AnalyticsCallbacks, type AudienceMatchFn, type AudienceRule, type DismissalState, type FeatureCTA, type FeatureDependencies, type FeatureDependencyState, type FeatureDropAnimationPreset, type FeatureEntry, type FeatureFlagBridge, type FeatureManifest, type FeaturePriority, type FeatureTrigger, type FeatureType, type FeatureVariant, LocalStorageAdapter, type LocalStorageAdapterOptions, MemoryAdapter, type ServerStorageAdapter, type StorageAdapter, type TriggerContext, type UserContext, createManifest, getFeatureById, getNewFeatureCount, getNewFeatures, getNewFeaturesByCategory, getNewFeaturesSorted, hasNewFeature, isNew, matchesAudience };
+export { type AdoptionScore, type AnalyticsCallbacks, type AudienceMatchFn, type AudienceRule, type DeliveryContext, type DismissalState, type DisplayFormat, type FeatureAdoptionStatus, type FeatureCTA, type FeatureDependencies, type FeatureDependencyState, type FeatureDropAnimationPreset, type FeatureDropEngine, type FeatureEntry, type FeatureFlagBridge, type FeatureManifest, type FeaturePriority, type FeatureTrigger, type FeatureType, type FeatureVariant, type FormatRecommendation, type InteractionType, LocalStorageAdapter, type LocalStorageAdapterOptions, MemoryAdapter, type ServerStorageAdapter, type StorageAdapter, type TimingDecision, type TriggerContext, type UserContext, createManifest, getFeatureById, getNewFeatureCount, getNewFeatures, getNewFeaturesByCategory, getNewFeaturesSorted, hasNewFeature, isNew, matchesAudience };

package/dist/index.d.ts

@@ -232,6 +232,94 @@ interface AnalyticsCallbacks {
     /** Fired when all features are dismissed at once */
     onAllDismissed?: () => void;
 }
+/** Display format hint from the engine */
+type DisplayFormat = "badge" | "toast" | "modal" | "banner" | "inline" | "spotlight";
+/** Interaction type tracked by the engine */
+type InteractionType = "seen" | "dismissed" | "clicked" | "completed" | "snoozed" | "hovered" | "expanded";
+/** Timing decision returned by the engine */
+interface TimingDecision {
+    /** Whether to show the announcement now */
+    show: boolean;
+    /** Reason for the decision */
+    reason: string;
+    /** Suggested delay in ms if not showing now */
+    delayMs?: number;
+    /** Confidence level (0-1) */
+    confidence: number;
+}
+/** Format recommendation from the engine */
+interface FormatRecommendation {
+    /** Recommended display format */
+    primary: DisplayFormat;
+    /** Fallback format if primary component isn't used */
+    fallback: DisplayFormat;
+    /** Reason for the recommendation */
+    reason: string;
+}
+/** Adoption score breakdown */
+interface AdoptionScore {
+    /** Overall score (0-100) */
+    score: number;
+    /** Letter grade */
+    grade: "A" | "B" | "C" | "D" | "F";
+    /** Score breakdown */
+    breakdown: {
+        /** % of features the user has explored */
+        featuresExplored: number;
+        /** Rate of dismissals (lower is better) */
+        dismissRate: number;
+        /** Rate of tour/checklist completion */
+        completionRate: number;
+        /** Whether engagement is rising, stable, or declining */
+        engagementTrend: "rising" | "stable" | "declining";
+    };
+    /** Actionable recommendations */
+    recommendations: string[];
+}
+/** Per-feature adoption status */
+interface FeatureAdoptionStatus {
+    featureId: string;
+    status: "unseen" | "seen" | "explored" | "adopted" | "dismissed";
+    firstSeen?: string;
+    lastInteraction?: string;
+    interactionCount: number;
+}
+/** Delivery context passed to the engine for timing decisions */
+interface DeliveryContext {
+    /** Current route/path */
+    currentPath: string;
+    /** Seconds since session start */
+    sessionAge: number;
+    /** Dismissals in last 5 minutes */
+    recentDismissals: number;
+    /** Feature priority */
+    featurePriority: FeaturePriority;
+}
+/**
+ * Plugin interface for the FeatureDrop engine.
+ *
+ * The open-source library defines this interface.
+ * The proprietary @featuredrop/engine implements it.
+ * Users can also build their own engine implementation.
+ *
+ * The free library works perfectly without any engine.
+ */
+interface FeatureDropEngine {
+    /** Decide whether to show a feature announcement now */
+    shouldShow(featureId: string, context: DeliveryContext): TimingDecision;
+    /** Recommend the best display format for a feature */
+    recommendFormat(featureId: string): FormatRecommendation;
+    /** Get the user's overall adoption score */
+    getAdoptionScore(): AdoptionScore;
+    /** Track a user interaction with a feature */
+    trackInteraction(featureId: string, type: InteractionType): void;
+    /** Get adoption status for a specific feature */
+    getFeatureAdoption(featureId: string): FeatureAdoptionStatus;
+    /** Initialize the engine (called by provider on mount) */
+    initialize?(): void;
+    /** Cleanup resources (called by provider on unmount) */
+    destroy?(): void;
+}
 
 /**
  * Default audience matching logic.
@@ -337,4 +425,4 @@ declare class MemoryAdapter implements StorageAdapter {
     dismissAll(now: Date): Promise<void>;
 }
 
-export { type AnalyticsCallbacks, type AudienceMatchFn, type AudienceRule, type DismissalState, type FeatureCTA, type FeatureDependencies, type FeatureDependencyState, type FeatureDropAnimationPreset, type FeatureEntry, type FeatureFlagBridge, type FeatureManifest, type FeaturePriority, type FeatureTrigger, type FeatureType, type FeatureVariant, LocalStorageAdapter, type LocalStorageAdapterOptions, MemoryAdapter, type ServerStorageAdapter, type StorageAdapter, type TriggerContext, type UserContext, createManifest, getFeatureById, getNewFeatureCount, getNewFeatures, getNewFeaturesByCategory, getNewFeaturesSorted, hasNewFeature, isNew, matchesAudience };
+export { type AdoptionScore, type AnalyticsCallbacks, type AudienceMatchFn, type AudienceRule, type DeliveryContext, type DismissalState, type DisplayFormat, type FeatureAdoptionStatus, type FeatureCTA, type FeatureDependencies, type FeatureDependencyState, type FeatureDropAnimationPreset, type FeatureDropEngine, type FeatureEntry, type FeatureFlagBridge, type FeatureManifest, type FeaturePriority, type FeatureTrigger, type FeatureType, type FeatureVariant, type FormatRecommendation, type InteractionType, LocalStorageAdapter, type LocalStorageAdapterOptions, MemoryAdapter, type ServerStorageAdapter, type StorageAdapter, type TimingDecision, type TriggerContext, type UserContext, createManifest, getFeatureById, getNewFeatureCount, getNewFeatures, getNewFeaturesByCategory, getNewFeaturesSorted, hasNewFeature, isNew, matchesAudience };

package/dist/preact.cjs

@@ -1099,6 +1099,7 @@ function FeatureDropProvider({
   locale = "en",
   animation = "normal",
   translations: translationOverrides,
+  engine,
   children
 }) {
   const analyticsRef = react.useRef(analytics);
@@ -1155,20 +1156,20 @@ function FeatureDropProvider({
       seenFeatureIds: readIdSet(SEEN_FEATURES_STORAGE_KEY),
       clickedFeatureIds: readIdSet(CLICKED_FEATURES_STORAGE_KEY),
       triggerContext: (() => {
-        const engine = triggerEngineRef.current;
-        if (!engine) return void 0;
-        engine.setElapsedMs(Date.now() - sessionStartedAtRef.current);
-        return engine.getContext();
+        const engine2 = triggerEngineRef.current;
+        if (!engine2) return void 0;
+        engine2.setElapsedMs(Date.now() - sessionStartedAtRef.current);
+        return engine2.getContext();
       })(),
       flagBridge
     })
   );
   const recompute = react.useCallback(() => {
-    const engine = triggerEngineRef.current;
+    const engine2 = triggerEngineRef.current;
     let triggerContext;
-    if (engine) {
-      engine.setElapsedMs(Date.now() - sessionStartedAtRef.current);
-      triggerContext = engine.getContext();
+    if (engine2) {
+      engine2.setElapsedMs(Date.now() - sessionStartedAtRef.current);
+      triggerContext = engine2.getContext();
     }
     setFeatureState(
       computeFeatureState({
@@ -1205,6 +1206,12 @@ function FeatureDropProvider({
   react.useEffect(() => {
     recompute();
   }, [recompute]);
+  react.useEffect(() => {
+    engine?.initialize?.();
+    return () => {
+      engine?.destroy?.();
+    };
+  }, [engine]);
   const hasTimeTriggers = react.useMemo(
     () => resolvedManifest.some((feature) => feature.trigger?.type === "time"),
     [resolvedManifest]
@@ -1487,7 +1494,8 @@ function FeatureDropProvider({
       trackUsageEvent,
       trackTriggerEvent,
       trackMilestone,
-      setTriggerPath
+      setTriggerPath,
+      engine: engine ?? null
     }),
     [
       resolvedManifest,
@@ -1521,7 +1529,8 @@ function FeatureDropProvider({
       trackUsageEvent,
       trackTriggerEvent,
       trackMilestone,
-      setTriggerPath
+      setTriggerPath,
+      engine
     ]
   );
   return /* @__PURE__ */ jsxRuntime.jsx(FeatureDropContext.Provider, { value, children });