featuredrop 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Glincker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+# featuredrop
+
+**Lightweight feature discovery system. Show "New" badges that auto-expire.**
+
+[![npm version](https://img.shields.io/npm/v/featuredrop)](https://www.npmjs.com/package/featuredrop)
+[![license](https://img.shields.io/npm/l/featuredrop)](https://github.com/GLINCKER/featuredrop/blob/main/LICENSE)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/featuredrop)](https://bundlephobia.com/package/featuredrop)
+[![CI](https://github.com/GLINCKER/featuredrop/actions/workflows/ci.yml/badge.svg)](https://github.com/GLINCKER/featuredrop/actions/workflows/ci.yml)
+
+---
+
+## Why featuredrop?
+
+Every SaaS needs "New" badges on sidebar items when features ship. But most solutions are either too complex (LaunchDarkly), too coupled (Beamer), or don't actually expire.
+
+**featuredrop** solves this with a dead-simple API:
+
+- Define features in a manifest (just an array of objects)
+- Badges auto-expire based on time windows
+- Users can dismiss individually or "mark all as seen"
+- Works with any framework — React bindings included
+- Zero dependencies, < 2 kB minzipped
+
+## Quick Start
+
+### Install
+
+```bash
+npm install featuredrop
+# or
+pnpm add featuredrop
+```
+
+### 1. Define your feature manifest
+
+```ts
+import { createManifest } from 'featuredrop'
+
+export const FEATURES = createManifest([
+  {
+    id: 'ai-journal',
+    label: 'AI Decision Journal',
+    description: 'Track decisions with AI-powered insights',
+    releasedAt: '2026-02-20T00:00:00Z',
+    showNewUntil: '2026-03-20T00:00:00Z',
+    sidebarKey: '/journal',
+    category: 'ai',
+  },
+  {
+    id: 'analytics-v2',
+    label: 'Analytics Dashboard v2',
+    releasedAt: '2026-02-25T00:00:00Z',
+    showNewUntil: '2026-03-25T00:00:00Z',
+    sidebarKey: '/analytics',
+  },
+])
+```
+
+### 2. Create a storage adapter
+
+```ts
+import { LocalStorageAdapter } from 'featuredrop'
+
+const storage = new LocalStorageAdapter({
+  // Server-side watermark from user profile (e.g. user.featuresSeenAt)
+  watermark: user.featuresSeenAt,
+  // Optional: callback when user clicks "Mark all as seen"
+  onDismissAll: async (now) => {
+    await api.updateUser({ featuresSeenAt: now.toISOString() })
+  },
+})
+```
+
+### 3. Check what's new
+
+```ts
+import { getNewFeatures, hasNewFeature } from 'featuredrop'
+
+// Get all new features
+const newFeatures = getNewFeatures(FEATURES, storage)
+console.log(`${newFeatures.length} new features!`)
+
+// Check a specific sidebar item
+if (hasNewFeature(FEATURES, '/journal', storage)) {
+  showBadge('/journal')
+}
+```
+
+## React Integration
+
+```bash
+# React is an optional peer dependency — only needed if you use featuredrop/react
+npm install featuredrop react
+```
+
+### Wrap your app with the provider
+
+```tsx
+import { FeatureDropProvider } from 'featuredrop/react'
+import { LocalStorageAdapter } from 'featuredrop'
+
+const storage = new LocalStorageAdapter({
+  watermark: user.featuresSeenAt,
+  onDismissAll: (now) => api.markFeaturesSeen(now),
+})
+
+function App() {
+  return (
+    <FeatureDropProvider manifest={FEATURES} storage={storage}>
+      <Sidebar />
+    </FeatureDropProvider>
+  )
+}
+```
+
+### Use hooks in your components
+
+```tsx
+import { useNewFeature, NewBadge } from 'featuredrop/react'
+
+function SidebarItem({ path, label }: { path: string; label: string }) {
+  const { isNew, dismiss } = useNewFeature(path)
+
+  return (
+    <a href={path} onClick={() => isNew && dismiss()}>
+      {label}
+      {isNew && <NewBadge />}
+    </a>
+  )
+}
+```
+
+### "What's New" panel
+
+```tsx
+import { useFeatureDrop } from 'featuredrop/react'
+
+function WhatsNew() {
+  const { newFeatures, newCount, dismissAll } = useFeatureDrop()
+
+  return (
+    <div>
+      <h2>What's New ({newCount})</h2>
+      {newFeatures.map(f => (
+        <div key={f.id}>
+          <h3>{f.label}</h3>
+          <p>{f.description}</p>
+        </div>
+      ))}
+      <button onClick={dismissAll}>Mark all as seen</button>
+    </div>
+  )
+}
+```
+
+## How It Works
+
+```
+  Feature Manifest (static)     Storage Adapter
+  ┌─────────────────────┐      ┌──────────────────────┐
+  │ id: "ai-journal"    │      │ watermark: server     │
+  │ releasedAt: Feb 20  │      │ dismissed: localStorage│
+  │ showNewUntil: Mar 20│      └──────────┬───────────┘
+  └─────────┬───────────┘                 │
+            │                             │
+            ▼                             ▼
+       ┌─────────────────────────────────────┐
+       │            isNew(feature)            │
+       │                                     │
+       │  1. Not dismissed?          ✓       │
+       │  2. Before showNewUntil?    ✓       │
+       │  3. Released after watermark? ✓     │
+       │                                     │
+       │  → Show "New" badge                 │
+       └─────────────────────────────────────┘
+```
+
+**Three-check algorithm:**
+
+1. **Dismissed?** — Has the user clicked to dismiss this specific feature? (client-side, per-device)
+2. **Expired?** — Is the current time past `showNewUntil`? (automatic, no user action needed)
+3. **After watermark?** — Was the feature released after the user's "features seen at" timestamp? (server-side, cross-device)
+
+This hybrid approach means:
+- New users see all recent features (no watermark = everything is new)
+- Returning users only see features released since their last visit
+- Individual dismissals are instant (localStorage, no server call)
+- "Mark all as seen" syncs across devices (server watermark update)
+
+## API Reference
+
+### Core Functions
+
+| Function | Description |
+|----------|-------------|
+| `isNew(feature, watermark, dismissedIds, now?)` | Check if a single feature is "new" |
+| `getNewFeatures(manifest, storage, now?)` | Get all currently new features |
+| `getNewFeatureCount(manifest, storage, now?)` | Get count of new features |
+| `hasNewFeature(manifest, sidebarKey, storage, now?)` | Check if a sidebar key has new features |
+
+### Helpers
+
+| Function | Description |
+|----------|-------------|
+| `createManifest(entries)` | Create a frozen, typed manifest |
+| `getFeatureById(manifest, id)` | Find a feature by ID |
+| `getNewFeaturesByCategory(manifest, category, storage, now?)` | Filter new features by category |
+
+### Adapters
+
+| Adapter | Description |
+|---------|-------------|
+| `LocalStorageAdapter` | Browser localStorage + server watermark |
+| `MemoryAdapter` | In-memory (testing, SSR) |
+
+### React (`featuredrop/react`)
+
+| Export | Description |
+|--------|-------------|
+| `FeatureDropProvider` | Context provider — wraps your app |
+| `useFeatureDrop()` | Full context: `{ newFeatures, newCount, isNew, dismiss, dismissAll }` |
+| `useNewFeature(key)` | Single item: `{ isNew, feature, dismiss }` |
+| `useNewCount()` | Just the count number |
+| `NewBadge` | Headless badge: `variant="pill" \| "dot" \| "count"` |
+
+### NewBadge Styling
+
+Zero CSS framework dependency. Style via CSS custom properties:
+
+```css
+/* In your global CSS or CSS-in-JS */
+[data-featuredrop] {
+  --featuredrop-color: #b45309;
+  --featuredrop-bg: rgba(245, 158, 11, 0.15);
+  --featuredrop-font-size: 10px;
+  --featuredrop-dot-size: 8px;
+  --featuredrop-glow: rgba(245, 158, 11, 0.6);
+  --featuredrop-count-size: 18px;
+  --featuredrop-count-color: white;
+  --featuredrop-count-bg: #f59e0b;
+}
+```
+
+## Custom Storage Adapter
+
+Implement the `StorageAdapter` interface for your persistence layer:
+
+```ts
+import type { StorageAdapter } from 'featuredrop'
+
+class RedisAdapter implements StorageAdapter {
+  getWatermark(): string | null {
+    return this.cache.get('watermark')
+  }
+
+  getDismissedIds(): ReadonlySet<string> {
+    return new Set(this.cache.get('dismissed') ?? [])
+  }
+
+  dismiss(id: string): void {
+    this.cache.append('dismissed', id)
+  }
+
+  async dismissAll(now: Date): Promise<void> {
+    await this.cache.set('watermark', now.toISOString())
+    await this.cache.delete('dismissed')
+  }
+}
+```
+
+## Comparison
+
+| Feature | featuredrop | LaunchDarkly | Beamer | Joyride |
+|---------|------------|-------------|--------|---------|
+| Auto-expiring badges | Yes | No | No | No |
+| Zero dependencies | Yes | No | No | No |
+| Framework agnostic | Yes | Yes | No | No |
+| React bindings | Yes | Yes | No | Yes |
+| Server watermark | Yes | N/A | Yes | No |
+| Per-feature dismiss | Yes | N/A | No | No |
+| < 2 kB bundle | Yes | No | No | No |
+| TypeScript | Yes | Yes | No | Partial |
+| Free & OSS | Yes | No | Freemium | Yes |
+
+## License
+
+MIT - [Glincker](https://glincker.com)
+
+---
+
+<p align="center">
+  <strong>A <a href="https://glincker.com">GLINCKER</a> Open Source Project</strong>
+</p>

package/dist/index.cjs

@@ -0,0 +1,133 @@
+'use strict';
+
+// src/core.ts
+function isNew(feature, watermark, dismissedIds, now = /* @__PURE__ */ new Date()) {
+  if (dismissedIds.has(feature.id)) return false;
+  const nowMs = now.getTime();
+  const showUntilMs = new Date(feature.showNewUntil).getTime();
+  if (nowMs >= showUntilMs) return false;
+  if (watermark) {
+    const watermarkMs = new Date(watermark).getTime();
+    const releasedMs = new Date(feature.releasedAt).getTime();
+    if (releasedMs <= watermarkMs) return false;
+  }
+  return true;
+}
+function getNewFeatures(manifest, storage, now = /* @__PURE__ */ new Date()) {
+  const watermark = storage.getWatermark();
+  const dismissedIds = storage.getDismissedIds();
+  return manifest.filter((f) => isNew(f, watermark, dismissedIds, now));
+}
+function getNewFeatureCount(manifest, storage, now = /* @__PURE__ */ new Date()) {
+  return getNewFeatures(manifest, storage, now).length;
+}
+function hasNewFeature(manifest, sidebarKey, storage, now = /* @__PURE__ */ new Date()) {
+  const watermark = storage.getWatermark();
+  const dismissedIds = storage.getDismissedIds();
+  return manifest.some(
+    (f) => f.sidebarKey === sidebarKey && isNew(f, watermark, dismissedIds, now)
+  );
+}
+
+// src/helpers.ts
+function createManifest(entries) {
+  return Object.freeze([...entries]);
+}
+function getFeatureById(manifest, id) {
+  return manifest.find((f) => f.id === id);
+}
+function getNewFeaturesByCategory(manifest, category, storage, now = /* @__PURE__ */ new Date()) {
+  const watermark = storage.getWatermark();
+  const dismissedIds = storage.getDismissedIds();
+  return manifest.filter(
+    (f) => f.category === category && isNew(f, watermark, dismissedIds, now)
+  );
+}
+
+// src/adapters/local-storage.ts
+var DISMISSED_SUFFIX = ":dismissed";
+var LocalStorageAdapter = class {
+  prefix;
+  watermarkValue;
+  onDismissAllCallback;
+  dismissedKey;
+  constructor(options = {}) {
+    this.prefix = options.prefix ?? "featuredrop";
+    this.watermarkValue = options.watermark ?? null;
+    this.onDismissAllCallback = options.onDismissAll;
+    this.dismissedKey = `${this.prefix}${DISMISSED_SUFFIX}`;
+  }
+  getWatermark() {
+    return this.watermarkValue;
+  }
+  getDismissedIds() {
+    try {
+      if (typeof window === "undefined") return /* @__PURE__ */ new Set();
+      const raw = localStorage.getItem(this.dismissedKey);
+      if (!raw) return /* @__PURE__ */ new Set();
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return new Set(parsed);
+      return /* @__PURE__ */ new Set();
+    } catch {
+      return /* @__PURE__ */ new Set();
+    }
+  }
+  dismiss(id) {
+    try {
+      if (typeof window === "undefined") return;
+      const raw = localStorage.getItem(this.dismissedKey);
+      const existing = raw ? JSON.parse(raw) : [];
+      if (!existing.includes(id)) {
+        existing.push(id);
+        localStorage.setItem(this.dismissedKey, JSON.stringify(existing));
+      }
+    } catch {
+    }
+  }
+  async dismissAll(now) {
+    try {
+      if (typeof window !== "undefined") {
+        localStorage.removeItem(this.dismissedKey);
+      }
+    } catch {
+    }
+    if (this.onDismissAllCallback) {
+      await this.onDismissAllCallback(now);
+    }
+  }
+};
+
+// src/adapters/memory.ts
+var MemoryAdapter = class {
+  watermark;
+  dismissed;
+  constructor(options = {}) {
+    this.watermark = options.watermark ?? null;
+    this.dismissed = /* @__PURE__ */ new Set();
+  }
+  getWatermark() {
+    return this.watermark;
+  }
+  getDismissedIds() {
+    return this.dismissed;
+  }
+  dismiss(id) {
+    this.dismissed.add(id);
+  }
+  async dismissAll(now) {
+    this.watermark = now.toISOString();
+    this.dismissed.clear();
+  }
+};
+
+exports.LocalStorageAdapter = LocalStorageAdapter;
+exports.MemoryAdapter = MemoryAdapter;
+exports.createManifest = createManifest;
+exports.getFeatureById = getFeatureById;
+exports.getNewFeatureCount = getNewFeatureCount;
+exports.getNewFeatures = getNewFeatures;
+exports.getNewFeaturesByCategory = getNewFeaturesByCategory;
+exports.hasNewFeature = hasNewFeature;
+exports.isNew = isNew;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core.ts","../src/helpers.ts","../src/adapters/local-storage.ts","../src/adapters/memory.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { FeatureEntry, FeatureManifest, StorageAdapter } from \"./types\";\n\n/**\n * Check if a single feature should show as \"new\".\n *\n * A feature is \"new\" when ALL of these are true:\n * 1. Current time is before `showNewUntil`\n * 2. Feature was released after the watermark (or no watermark exists)\n * 3. Feature has not been individually dismissed\n */\nexport function isNew(\n  feature: FeatureEntry,\n  watermark: string | null,\n  dismissedIds: ReadonlySet<string>,\n  now: Date = new Date(),\n): boolean {\n  // Already dismissed by the user on this device\n  if (dismissedIds.has(feature.id)) return false;\n\n  const nowMs = now.getTime();\n  const showUntilMs = new Date(feature.showNewUntil).getTime();\n\n  // Past the display window\n  if (nowMs >= showUntilMs) return false;\n\n  // If there's a watermark, feature must have been released after it\n  if (watermark) {\n    const watermarkMs = new Date(watermark).getTime();\n    const releasedMs = new Date(feature.releasedAt).getTime();\n    if (releasedMs <= watermarkMs) return false;\n  }\n\n  return true;\n}\n\n/**\n * Get all features that are currently \"new\" for this user.\n */\nexport function getNewFeatures(\n  manifest: FeatureManifest,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): FeatureEntry[] {\n  const watermark = storage.getWatermark();\n  const dismissedIds = storage.getDismissedIds();\n  return manifest.filter((f) => isNew(f, watermark, dismissedIds, now));\n}\n\n/**\n * Get the count of new features.\n */\nexport function getNewFeatureCount(\n  manifest: FeatureManifest,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): number {\n  return getNewFeatures(manifest, storage, now).length;\n}\n\n/**\n * Check if a specific sidebar key has a new feature.\n */\nexport function hasNewFeature(\n  manifest: FeatureManifest,\n  sidebarKey: string,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): boolean {\n  const watermark = storage.getWatermark();\n  const dismissedIds = storage.getDismissedIds();\n  return manifest.some(\n    (f) => f.sidebarKey === sidebarKey && isNew(f, watermark, dismissedIds, now),\n  );\n}\n","import type { FeatureEntry, FeatureManifest, StorageAdapter } from \"./types\";\nimport { isNew } from \"./core\";\n\n/**\n * Create a frozen feature manifest from an array of entries.\n * Ensures the manifest is immutable at runtime.\n */\nexport function createManifest(\n  entries: FeatureEntry[],\n): FeatureManifest {\n  return Object.freeze([...entries]);\n}\n\n/**\n * Find a feature by its ID in the manifest.\n * Returns `undefined` if not found.\n */\nexport function getFeatureById(\n  manifest: FeatureManifest,\n  id: string,\n): FeatureEntry | undefined {\n  return manifest.find((f) => f.id === id);\n}\n\n/**\n * Get all new features in a specific category.\n */\nexport function getNewFeaturesByCategory(\n  manifest: FeatureManifest,\n  category: string,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): FeatureEntry[] {\n  const watermark = storage.getWatermark();\n  const dismissedIds = storage.getDismissedIds();\n  return manifest.filter(\n    (f) => f.category === category && isNew(f, watermark, dismissedIds, now),\n  );\n}\n","import type { StorageAdapter } from \"../types\";\n\nexport interface LocalStorageAdapterOptions {\n  /** Key prefix for localStorage entries. Default: \"featuredrop\" */\n  prefix?: string;\n  /** Server-side watermark (ISO string). Typically from user profile. */\n  watermark?: string | null;\n  /** Callback when dismissAll is called. Use for server-side watermark updates. */\n  onDismissAll?: (now: Date) => Promise<void>;\n}\n\nconst DISMISSED_SUFFIX = \":dismissed\";\n\n/**\n * localStorage-based storage adapter.\n *\n * Architecture:\n * - **Watermark** comes from the server (passed at construction time)\n * - **Per-feature dismissals** are stored in localStorage (zero server writes)\n * - **dismissAll()** optionally calls a server callback, then clears localStorage\n *\n * Gracefully handles SSR environments where `window`/`localStorage` is unavailable.\n */\nexport class LocalStorageAdapter implements StorageAdapter {\n  private readonly prefix: string;\n  private readonly watermarkValue: string | null;\n  private readonly onDismissAllCallback?: (now: Date) => Promise<void>;\n  private readonly dismissedKey: string;\n\n  constructor(options: LocalStorageAdapterOptions = {}) {\n    this.prefix = options.prefix ?? \"featuredrop\";\n    this.watermarkValue = options.watermark ?? null;\n    this.onDismissAllCallback = options.onDismissAll;\n    this.dismissedKey = `${this.prefix}${DISMISSED_SUFFIX}`;\n  }\n\n  getWatermark(): string | null {\n    return this.watermarkValue;\n  }\n\n  getDismissedIds(): ReadonlySet<string> {\n    try {\n      if (typeof window === \"undefined\") return new Set();\n      const raw = localStorage.getItem(this.dismissedKey);\n      if (!raw) return new Set();\n      const parsed: unknown = JSON.parse(raw);\n      if (Array.isArray(parsed)) return new Set(parsed as string[]);\n      return new Set();\n    } catch {\n      return new Set();\n    }\n  }\n\n  dismiss(id: string): void {\n    try {\n      if (typeof window === \"undefined\") return;\n      const raw = localStorage.getItem(this.dismissedKey);\n      const existing: string[] = raw ? (JSON.parse(raw) as string[]) : [];\n      if (!existing.includes(id)) {\n        existing.push(id);\n        localStorage.setItem(this.dismissedKey, JSON.stringify(existing));\n      }\n    } catch {\n      // localStorage unavailable — silent fail\n    }\n  }\n\n  async dismissAll(now: Date): Promise<void> {\n    try {\n      if (typeof window !== \"undefined\") {\n        localStorage.removeItem(this.dismissedKey);\n      }\n    } catch {\n      // localStorage unavailable — silent fail\n    }\n\n    if (this.onDismissAllCallback) {\n      await this.onDismissAllCallback(now);\n    }\n  }\n}\n","import type { StorageAdapter } from \"../types\";\n\n/**\n * In-memory storage adapter.\n *\n * Useful for:\n * - Testing (no side effects)\n * - Server-side rendering (no `window`/`localStorage`)\n * - Environments without persistent storage\n */\nexport class MemoryAdapter implements StorageAdapter {\n  private watermark: string | null;\n  private dismissed: Set<string>;\n\n  constructor(options: { watermark?: string | null } = {}) {\n    this.watermark = options.watermark ?? null;\n    this.dismissed = new Set();\n  }\n\n  getWatermark(): string | null {\n    return this.watermark;\n  }\n\n  getDismissedIds(): ReadonlySet<string> {\n    return this.dismissed;\n  }\n\n  dismiss(id: string): void {\n    this.dismissed.add(id);\n  }\n\n  async dismissAll(now: Date): Promise<void> {\n    this.watermark = now.toISOString();\n    this.dismissed.clear();\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,131 @@
+/** 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 */
+    description?: 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 URL to link to (e.g. docs page, changelog entry) */
+    url?: string;
+    /** Optional version string when this feature shipped */
+    version?: string;
+    /** Optional arbitrary metadata */
+    meta?: Record<string, unknown>;
+}
+/** 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>;
+}
+
+/**
+ * Check if a single feature should show as "new".
+ *
+ * A feature is "new" when ALL of these are true:
+ * 1. Current time is before `showNewUntil`
+ * 2. Feature was released after the watermark (or no watermark exists)
+ * 3. Feature has not been individually dismissed
+ */
+declare function isNew(feature: FeatureEntry, watermark: string | null, dismissedIds: ReadonlySet<string>, now?: Date): boolean;
+/**
+ * Get all features that are currently "new" for this user.
+ */
+declare function getNewFeatures(manifest: FeatureManifest, storage: StorageAdapter, now?: Date): FeatureEntry[];
+/**
+ * Get the count of new features.
+ */
+declare function getNewFeatureCount(manifest: FeatureManifest, storage: StorageAdapter, now?: Date): number;
+/**
+ * Check if a specific sidebar key has a new feature.
+ */
+declare function hasNewFeature(manifest: FeatureManifest, sidebarKey: string, storage: StorageAdapter, now?: Date): boolean;
+
+/**
+ * Create a frozen feature manifest from an array of entries.
+ * Ensures the manifest is immutable at runtime.
+ */
+declare function createManifest(entries: FeatureEntry[]): FeatureManifest;
+/**
+ * Find a feature by its ID in the manifest.
+ * Returns `undefined` if not found.
+ */
+declare function getFeatureById(manifest: FeatureManifest, id: string): FeatureEntry | undefined;
+/**
+ * Get all new features in a specific category.
+ */
+declare function getNewFeaturesByCategory(manifest: FeatureManifest, category: string, storage: StorageAdapter, now?: Date): FeatureEntry[];
+
+interface LocalStorageAdapterOptions {
+    /** Key prefix for localStorage entries. Default: "featuredrop" */
+    prefix?: string;
+    /** Server-side watermark (ISO string). Typically from user profile. */
+    watermark?: string | null;
+    /** Callback when dismissAll is called. Use for server-side watermark updates. */
+    onDismissAll?: (now: Date) => Promise<void>;
+}
+/**
+ * localStorage-based storage adapter.
+ *
+ * Architecture:
+ * - **Watermark** comes from the server (passed at construction time)
+ * - **Per-feature dismissals** are stored in localStorage (zero server writes)
+ * - **dismissAll()** optionally calls a server callback, then clears localStorage
+ *
+ * Gracefully handles SSR environments where `window`/`localStorage` is unavailable.
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    private readonly prefix;
+    private readonly watermarkValue;
+    private readonly onDismissAllCallback?;
+    private readonly dismissedKey;
+    constructor(options?: LocalStorageAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+}
+
+/**
+ * In-memory storage adapter.
+ *
+ * Useful for:
+ * - Testing (no side effects)
+ * - Server-side rendering (no `window`/`localStorage`)
+ * - Environments without persistent storage
+ */
+declare class MemoryAdapter implements StorageAdapter {
+    private watermark;
+    private dismissed;
+    constructor(options?: {
+        watermark?: string | null;
+    });
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+}
+
+export { type FeatureEntry, type FeatureManifest, LocalStorageAdapter, type LocalStorageAdapterOptions, MemoryAdapter, type StorageAdapter, createManifest, getFeatureById, getNewFeatureCount, getNewFeatures, getNewFeaturesByCategory, hasNewFeature, isNew };