-
+
{/* Split: Dashboard vs Presets */}
diff --git a/packages/app/src/components/landing/launch-banner.tsx b/packages/app/src/components/landing/launch-banner.tsx
deleted file mode 100644
index 65a970c1..00000000
--- a/packages/app/src/components/landing/launch-banner.tsx
+++ /dev/null
@@ -1,96 +0,0 @@
-'use client';
-
-import { ArrowRight, Sparkles, X } from 'lucide-react';
-import { useCallback, useEffect, useState } from 'react';
-
-import { track } from '@/lib/analytics';
-
-const DISMISS_KEY = 'inferencex-dsv4-banner-dismissed';
-const BANNER_ID = 'dsv4-launch';
-const PRESET_ID = 'dsv4-launch';
-
-function isDismissed(): boolean {
- try {
- return localStorage.getItem(DISMISS_KEY) === BANNER_ID;
- } catch {
- return false;
- }
-}
-
-export function LaunchBanner() {
- const [visible, setVisible] = useState(false);
-
- useEffect(() => {
- if (!isDismissed()) {
- setVisible(true);
- track('launch_banner_shown', { banner_id: BANNER_ID });
- }
- }, []);
-
- const handleDismiss = useCallback((e: React.MouseEvent) => {
- e.preventDefault();
- e.stopPropagation();
- try {
- localStorage.setItem(DISMISS_KEY, BANNER_ID);
- } catch {
- // localStorage unavailable
- }
- setVisible(false);
- track('launch_banner_dismissed', { banner_id: BANNER_ID });
- }, []);
-
- if (!visible) return null;
-
- const href = `/inference?preset=${PRESET_ID}`;
-
- const handleClick = (e: React.MouseEvent
) => {
- if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
- e.preventDefault();
- track('launch_banner_clicked', { banner_id: BANNER_ID, preset_id: PRESET_ID });
- // Hard navigation so the `?preset=` param is guaranteed to be in the URL
- // when InferenceContext first mounts and reads window.location.search.
- window.location.href = href;
- };
-
- return (
-
- );
-}
diff --git a/packages/app/src/components/nudges/Nudge.tsx b/packages/app/src/components/nudges/Nudge.tsx
new file mode 100644
index 00000000..0f4e0a0a
--- /dev/null
+++ b/packages/app/src/components/nudges/Nudge.tsx
@@ -0,0 +1,148 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { usePathname } from 'next/navigation';
+
+import { track } from '@/lib/analytics';
+import {
+ type NudgeContext,
+ type NudgeEntry,
+ isDismissed,
+ isWithinSchedule,
+ markDismissed,
+} from '@/lib/nudges';
+
+import { NudgeBanner } from './NudgeBanner';
+import { NudgeModal } from './NudgeModal';
+import { NudgeToast } from './NudgeToast';
+import { useNudgeSlot } from './NudgeProvider';
+import { useNudgeTrigger } from './use-nudge-trigger';
+
+interface NudgeProps {
+ entry: NudgeEntry;
+}
+
+/**
+ * Single nudge orchestrator. Handles the full lifecycle:
+ *
+ * route match → schedule check → persistence check → condition →
+ * trigger fires → slot request (modal/banner) → render → analytics
+ *
+ * Toast nudges skip the slot — `BottomToast` already self-coordinates a single
+ * visible toast via the `inferencex:dismiss-toast` window event.
+ */
+export function Nudge({ entry }: NudgeProps) {
+ const pathname = usePathname() ?? '';
+ const slot = useNudgeSlot();
+ const [visible, setVisible] = useState(false);
+ const [shownOnce, setShownOnce] = useState(false);
+
+ const routeMatches = useMemo(() => {
+ if (!entry.routes || entry.routes.length === 0) return true;
+ return entry.routes.some((re) => re.test(pathname));
+ }, [entry.routes, pathname]);
+
+ // Re-evaluated on every render so external state changes (e.g. another
+ // module called `markDismissed`) are picked up promptly.
+ const passesPreconditions =
+ routeMatches &&
+ isWithinSchedule(entry.schedule) &&
+ !isDismissed(entry.id, entry.persistence) &&
+ (entry.condition?.() ?? true);
+
+ const persistOn = entry.persistOn ?? (entry.kind === 'toast' ? 'show' : 'dismiss');
+
+ const { fired, detail } = useNudgeTrigger({
+ trigger: entry.trigger,
+ enabled: passesPreconditions,
+ alreadyShown: shownOnce,
+ });
+
+ // All kinds go through the slot manager so only one nudge per kind is
+ // visible at a time. Priority resolves ties: e.g. dsv4-launch-modal wins
+ // over github-star-modal, and eval-samples-nudge wins over reproducibility
+ // on /evaluation.
+ useEffect(() => {
+ if (!fired || shownOnce) return;
+ if (!passesPreconditions) return;
+ const priority = entry.priority ?? 0;
+ const granted = slot.requestSlot(entry.kind, entry.id, priority);
+ if (!granted) return;
+ setVisible(true);
+ setShownOnce(true);
+ if (persistOn === 'show') {
+ markDismissed(entry.id, entry.persistence);
+ }
+ track('nudge_shown', { id: entry.id, kind: entry.kind });
+ }, [
+ fired,
+ shownOnce,
+ passesPreconditions,
+ entry.id,
+ entry.kind,
+ entry.persistence,
+ entry.priority,
+ persistOn,
+ slot,
+ ]);
+
+ // External-dismiss listeners: hide without persisting (the underlying state
+ // these events represent is what gates re-show — e.g. starring sets
+ // `inferencex-starred` which `condition` checks).
+ const visibleRef = useRef(visible);
+ visibleRef.current = visible;
+ useEffect(() => {
+ if (!entry.externalDismissEvents || entry.externalDismissEvents.length === 0) return;
+ const handler = () => {
+ if (!visibleRef.current) return;
+ setVisible(false);
+ slot.releaseSlot(entry.kind, entry.id);
+ };
+ const events = entry.externalDismissEvents;
+ for (const name of events) window.addEventListener(name, handler);
+ return () => {
+ for (const name of events) window.removeEventListener(name, handler);
+ };
+ }, [entry.externalDismissEvents, entry.id, entry.kind, slot]);
+
+ // Release the slot if we get force-unmounted (route change while visible).
+ useEffect(
+ () => () => {
+ slot.releaseSlot(entry.kind, entry.id);
+ },
+ [entry.id, entry.kind, slot],
+ );
+
+ const dismiss = useCallback(() => {
+ if (!visible) return;
+ setVisible(false);
+ markDismissed(entry.id, entry.persistence);
+ slot.releaseSlot(entry.kind, entry.id);
+ track('nudge_dismissed', { id: entry.id, kind: entry.kind });
+ }, [visible, entry.id, entry.persistence, entry.kind, slot]);
+
+ const onAction = useCallback(() => {
+ setVisible(false);
+ markDismissed(entry.id, entry.persistence);
+ slot.releaseSlot(entry.kind, entry.id);
+ track('nudge_action_clicked', { id: entry.id, kind: entry.kind });
+ }, [entry.id, entry.persistence, entry.kind, slot]);
+
+ const ctx = useMemo(
+ () => ({ id: entry.id, triggerDetail: detail, dismiss }),
+ [entry.id, detail, dismiss],
+ );
+
+ if (!visible) return null;
+ if (!slot.isSlotHolder(entry.kind, entry.id)) return null;
+
+ const content = entry.render(ctx);
+
+ if (entry.kind === 'modal') {
+ return ;
+ }
+ if (entry.kind === 'banner') {
+ return ;
+ }
+ return ;
+}
diff --git a/packages/app/src/components/nudges/NudgeBanner.tsx b/packages/app/src/components/nudges/NudgeBanner.tsx
new file mode 100644
index 00000000..ae889f91
--- /dev/null
+++ b/packages/app/src/components/nudges/NudgeBanner.tsx
@@ -0,0 +1,101 @@
+'use client';
+
+import { ArrowRight, X } from 'lucide-react';
+import { useCallback } from 'react';
+import { useRouter } from 'next/navigation';
+
+import type { NudgeContent, NudgeContext } from '@/lib/nudges';
+
+interface NudgeBannerProps {
+ id: string;
+ content: NudgeContent;
+ ctx: NudgeContext;
+ onAction: () => void;
+}
+
+/**
+ * Inline announcement banner. The whole row is the primary action target; the X
+ * button on the right dismisses without triggering the action. Mirrors the
+ * original `LaunchBanner` styling.
+ */
+export function NudgeBanner({ id, content, ctx, onAction }: NudgeBannerProps) {
+ const router = useRouter();
+ const action = content.primaryAction;
+
+ const handleClick = useCallback(
+ (e: React.MouseEvent) => {
+ if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
+ if (!action) return;
+ e.preventDefault();
+ onAction();
+ if (action.onClick) action.onClick(ctx);
+ if (action.href) {
+ if (action.target === '_blank') {
+ window.open(action.href, '_blank', 'noopener,noreferrer');
+ } else if (action.inApp) {
+ router.push(action.href);
+ } else {
+ window.location.href = action.href;
+ }
+ }
+ },
+ [action, ctx, onAction, router],
+ );
+
+ const handleDismiss = useCallback(
+ (e: React.MouseEvent) => {
+ e.preventDefault();
+ e.stopPropagation();
+ ctx.dismiss();
+ },
+ [ctx],
+ );
+
+ const href = action?.href ?? '#';
+
+ return (
+
+ );
+}
diff --git a/packages/app/src/components/nudges/NudgeBannerSlot.tsx b/packages/app/src/components/nudges/NudgeBannerSlot.tsx
new file mode 100644
index 00000000..bd065fcd
--- /dev/null
+++ b/packages/app/src/components/nudges/NudgeBannerSlot.tsx
@@ -0,0 +1,20 @@
+'use client';
+
+import { Nudge } from './Nudge';
+import { NUDGE_REGISTRY } from './registry';
+
+/**
+ * Inline banner mount point. Drop this anywhere in a page layout and any
+ * registry entry whose `kind === 'banner'` and whose `routes` match the current
+ * pathname will render here. Wrap somewhere in the tree with ``
+ * (already done in the root layout).
+ */
+export function NudgeBannerSlot() {
+ return (
+ <>
+ {NUDGE_REGISTRY.filter((e) => e.kind === 'banner').map((entry) => (
+
+ ))}
+
+ );
+}
diff --git a/packages/app/src/components/nudges/NudgeModal.tsx b/packages/app/src/components/nudges/NudgeModal.tsx
new file mode 100644
index 00000000..69bcd9c5
--- /dev/null
+++ b/packages/app/src/components/nudges/NudgeModal.tsx
@@ -0,0 +1,91 @@
+'use client';
+
+import { X } from 'lucide-react';
+import { useCallback } from 'react';
+import { useRouter } from 'next/navigation';
+
+import { Button } from '@/components/ui/button';
+
+import type { NudgeContent, NudgeContext } from '@/lib/nudges';
+
+interface NudgeModalProps {
+ id: string;
+ content: NudgeContent;
+ ctx: NudgeContext;
+ onAction: () => void;
+}
+
+/**
+ * Bottom-right modal-card. Renders the nudge as a non-blocking dialog with a
+ * dismiss (X) and a primary CTA. Mirrors the look of the original
+ * `Dsv4LaunchModal` / `GitHubStarModal` so the visual change is invisible.
+ */
+export function NudgeModal({ id, content, ctx, onAction }: NudgeModalProps) {
+ const router = useRouter();
+ const titleId = `nudge-${id}-title`;
+ const descriptionId = `nudge-${id}-description`;
+
+ const handleAction = useCallback(() => {
+ const action = content.primaryAction;
+ if (!action) return;
+ onAction();
+ if (action.onClick) action.onClick(ctx);
+ if (action.href) {
+ if (action.target === '_blank') {
+ window.open(action.href, '_blank', 'noopener,noreferrer');
+ } else if (action.inApp) {
+ router.push(action.href);
+ } else {
+ window.location.href = action.href;
+ }
+ }
+ }, [content.primaryAction, ctx, onAction, router]);
+
+ return (
+
+ );
+}
diff --git a/packages/app/src/components/nudges/NudgeProvider.tsx b/packages/app/src/components/nudges/NudgeProvider.tsx
new file mode 100644
index 00000000..6ce6432a
--- /dev/null
+++ b/packages/app/src/components/nudges/NudgeProvider.tsx
@@ -0,0 +1,105 @@
+'use client';
+
+import {
+ type ReactNode,
+ createContext,
+ useCallback,
+ useContext,
+ useMemo,
+ useRef,
+ useState,
+} from 'react';
+
+import type { NudgeKind } from '@/lib/nudges';
+
+/**
+ * Slot manager for kinds that can only host one nudge at a time (modal,
+ * banner). Each candidate calls `requestSlot` with its priority; the highest
+ * priority requester wins. Toasts coordinate via the existing
+ * `inferencex:dismiss-toast` event in BottomToast and don't use the slot.
+ */
+interface NudgeProviderState {
+ requestSlot: (kind: NudgeKind, id: string, priority: number) => boolean;
+ releaseSlot: (kind: NudgeKind, id: string) => void;
+ isSlotHolder: (kind: NudgeKind, id: string) => boolean;
+}
+
+const NudgeContext = createContext(null);
+
+interface SlotState {
+ holder: string | null;
+ candidates: Map;
+}
+
+function pickHolder(candidates: Map): string | null {
+ let bestId: string | null = null;
+ let bestPriority = -Infinity;
+ for (const [id, priority] of candidates) {
+ if (priority > bestPriority) {
+ bestPriority = priority;
+ bestId = id;
+ }
+ }
+ return bestId;
+}
+
+export function NudgeProvider({ children }: { children: ReactNode }) {
+ const [, forceRender] = useState(0);
+ const slotsRef = useRef>(new Map());
+
+ const getSlot = useCallback((kind: NudgeKind): SlotState => {
+ let slot = slotsRef.current.get(kind);
+ if (!slot) {
+ slot = { holder: null, candidates: new Map() };
+ slotsRef.current.set(kind, slot);
+ }
+ return slot;
+ }, []);
+
+ const requestSlot = useCallback(
+ (kind: NudgeKind, id: string, priority: number): boolean => {
+ const slot = getSlot(kind);
+ slot.candidates.set(id, priority);
+ const newHolder = pickHolder(slot.candidates);
+ if (newHolder !== slot.holder) {
+ slot.holder = newHolder;
+ forceRender((n) => n + 1);
+ }
+ return slot.holder === id;
+ },
+ [getSlot],
+ );
+
+ const releaseSlot = useCallback(
+ (kind: NudgeKind, id: string): void => {
+ const slot = getSlot(kind);
+ slot.candidates.delete(id);
+ const newHolder = pickHolder(slot.candidates);
+ if (newHolder !== slot.holder) {
+ slot.holder = newHolder;
+ forceRender((n) => n + 1);
+ }
+ },
+ [getSlot],
+ );
+
+ const isSlotHolder = useCallback(
+ (kind: NudgeKind, id: string): boolean => getSlot(kind).holder === id,
+ [getSlot],
+ );
+
+ const value = useMemo(
+ () => ({ requestSlot, releaseSlot, isSlotHolder }),
+ [requestSlot, releaseSlot, isSlotHolder],
+ );
+
+ return {children};
+}
+
+export function useNudgeSlot() {
+ const ctx = useContext(NudgeContext);
+ if (!ctx) {
+ throw new Error('useNudgeSlot must be used inside ');
+ }
+ return ctx;
+}
diff --git a/packages/app/src/components/nudges/NudgeRoot.tsx b/packages/app/src/components/nudges/NudgeRoot.tsx
new file mode 100644
index 00000000..f4b1b6cd
--- /dev/null
+++ b/packages/app/src/components/nudges/NudgeRoot.tsx
@@ -0,0 +1,20 @@
+'use client';
+
+import { Nudge } from './Nudge';
+import { NUDGE_REGISTRY } from './registry';
+
+/**
+ * Floating-nudge mount point. Renders every modal- and toast-kind entry in the
+ * registry; each Nudge filters itself by route. Banners render inline via
+ * `` instead. Wrap the app in `` once, then
+ * place this near the top of the layout tree.
+ */
+export function NudgeRoot() {
+ return (
+ <>
+ {NUDGE_REGISTRY.filter((e) => e.kind !== 'banner').map((entry) => (
+
+ ))}
+
+ );
+}
diff --git a/packages/app/src/components/nudges/NudgeToast.tsx b/packages/app/src/components/nudges/NudgeToast.tsx
new file mode 100644
index 00000000..48733666
--- /dev/null
+++ b/packages/app/src/components/nudges/NudgeToast.tsx
@@ -0,0 +1,59 @@
+'use client';
+
+import { useCallback } from 'react';
+import { useRouter } from 'next/navigation';
+
+import { BottomToast } from '@/components/ui/bottom-toast';
+
+import type { NudgeContent, NudgeContext } from '@/lib/nudges';
+
+interface NudgeToastProps {
+ id: string;
+ content: NudgeContent;
+ ctx: NudgeContext;
+ onAction: () => void;
+}
+
+export function NudgeToast({ id, content, ctx, onAction }: NudgeToastProps) {
+ const router = useRouter();
+ const { primaryAction } = content;
+
+ const handleAction = useCallback(() => {
+ if (!primaryAction) return;
+ onAction();
+ if (primaryAction.onClick) {
+ primaryAction.onClick(ctx);
+ }
+ if (primaryAction.href) {
+ if (primaryAction.target === '_blank') {
+ window.open(primaryAction.href, '_blank', 'noopener,noreferrer');
+ } else if (primaryAction.inApp) {
+ router.push(primaryAction.href);
+ } else {
+ window.location.href = primaryAction.href;
+ }
+ }
+ }, [primaryAction, ctx, onAction, router]);
+
+ const action =
+ primaryAction !== undefined
+ ? {
+ label: primaryAction.label,
+ icon: primaryAction.icon,
+ onClick: handleAction,
+ }
+ : undefined;
+
+ return (
+
+ );
+}
diff --git a/packages/app/src/components/nudges/index.ts b/packages/app/src/components/nudges/index.ts
new file mode 100644
index 00000000..703a13f9
--- /dev/null
+++ b/packages/app/src/components/nudges/index.ts
@@ -0,0 +1,4 @@
+export { NudgeProvider } from './NudgeProvider';
+export { NudgeRoot } from './NudgeRoot';
+export { NudgeBannerSlot } from './NudgeBannerSlot';
+export { NUDGE_REGISTRY, userHasStarredRepo } from './registry';
diff --git a/packages/app/src/components/nudges/registry.test.ts b/packages/app/src/components/nudges/registry.test.ts
new file mode 100644
index 00000000..dd78e099
--- /dev/null
+++ b/packages/app/src/components/nudges/registry.test.ts
@@ -0,0 +1,157 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { NUDGE_REGISTRY, userHasStarredRepo } from './registry';
+
+const ALL_IDS = NUDGE_REGISTRY.map((e) => e.id);
+
+describe('NUDGE_REGISTRY shape', () => {
+ it('has unique ids', () => {
+ expect(new Set(ALL_IDS).size).toBe(ALL_IDS.length);
+ });
+
+ it('only uses supported kinds', () => {
+ for (const entry of NUDGE_REGISTRY) {
+ expect(['toast', 'modal', 'banner']).toContain(entry.kind);
+ }
+ });
+
+ it('has every previously-existing engagement nudge migrated', () => {
+ // Sanity: the issue requires "no parallel systems left" — these are the
+ // ids the framework now owns. If this list shrinks unintentionally, the
+ // test fails so the regression is caught.
+ const expected = [
+ 'launch-banner-dsv4',
+ 'dsv4-launch-modal',
+ 'github-star-modal',
+ 'reproducibility-nudge',
+ 'star-nudge',
+ 'export-nudge',
+ 'gradient-label-nudge',
+ 'eval-samples-nudge',
+ ];
+ expect(ALL_IDS.toSorted()).toEqual(expected.toSorted());
+ });
+
+ it('renders a non-empty title and description for each entry', () => {
+ for (const entry of NUDGE_REGISTRY) {
+ const ctx = { id: entry.id, triggerDetail: undefined, dismiss: () => {} };
+ const content = entry.render(ctx);
+ expect(content.title.length).toBeGreaterThan(0);
+ expect(content.description.length).toBeGreaterThan(0);
+ }
+ });
+
+ it('every banner has a primary action with an href (the banner itself is the click target)', () => {
+ for (const entry of NUDGE_REGISTRY.filter((e) => e.kind === 'banner')) {
+ const ctx = { id: entry.id, triggerDetail: undefined, dismiss: () => {} };
+ const content = entry.render(ctx);
+ expect(content.primaryAction).toBeDefined();
+ expect(content.primaryAction?.href).toBeTruthy();
+ }
+ });
+});
+
+describe('Migrated nudge triggers match original behavior', () => {
+ it('reproducibility-nudge fires after a 1.5s mount delay (session)', () => {
+ const entry = NUDGE_REGISTRY.find((e) => e.id === 'reproducibility-nudge')!;
+ expect(entry.trigger).toEqual({ kind: 'mount-delay', delayMs: 1500 });
+ expect(entry.persistence).toEqual({ kind: 'session' });
+ });
+
+ it('eval-samples-nudge is gated to /evaluation with weekly cooldown', () => {
+ const entry = NUDGE_REGISTRY.find((e) => e.id === 'eval-samples-nudge')!;
+ expect(entry.trigger).toEqual({ kind: 'mount-delay', delayMs: 1500 });
+ expect(entry.persistence).toEqual({ kind: 'cooldown', durationMs: 7 * 24 * 60 * 60 * 1000 });
+ expect(entry.routes?.some((r) => r.test('/evaluation'))).toBe(true);
+ expect(entry.routes?.some((r) => r.test('/inference'))).toBe(false);
+ expect(entry.externalDismissEvents).toContain('inferencex:eval-samples-opened');
+ });
+
+ it('export-nudge fires after the 2nd copy from a chart tooltip', () => {
+ const entry = NUDGE_REGISTRY.find((e) => e.id === 'export-nudge')!;
+ expect(entry.trigger.kind).toBe('event');
+ if (entry.trigger.kind !== 'event') throw new Error('unreachable');
+ const copy = entry.trigger.events[0];
+ expect(copy.name).toBe('copy');
+ expect(copy.target).toBe('document');
+ expect(copy.threshold).toBe(2);
+ expect(copy.selector).toBe('[data-chart-tooltip]');
+ });
+
+ it('star-nudge listens to tab-change (×2) and action (×1) with 1.5s debounce', () => {
+ const entry = NUDGE_REGISTRY.find((e) => e.id === 'star-nudge')!;
+ expect(entry.trigger.kind).toBe('event');
+ if (entry.trigger.kind !== 'event') throw new Error('unreachable');
+ expect(entry.trigger.afterDelayMs).toBe(1500);
+ const tabChange = entry.trigger.events.find((e) => e.name === 'inferencex:tab-change');
+ const action = entry.trigger.events.find((e) => e.name === 'inferencex:action');
+ expect(tabChange?.threshold).toBe(2);
+ expect(action?.threshold ?? 1).toBe(1);
+ expect(entry.externalDismissEvents).toContain('inferencex:starred');
+ });
+
+ it('gradient-label-nudge captures `enableGradient` from the trigger detail', () => {
+ const entry = NUDGE_REGISTRY.find((e) => e.id === 'gradient-label-nudge')!;
+ const enable = vi.fn();
+ const content = entry.render({
+ id: entry.id,
+ triggerDetail: { enableGradient: enable },
+ dismiss: () => {},
+ });
+ content.primaryAction?.onClick?.({ id: entry.id, triggerDetail: undefined, dismiss: () => {} });
+ expect(enable).toHaveBeenCalled();
+ });
+
+ it('github-star-modal yields to the dsv4-launch-modal until that one is dismissed', () => {
+ const entry = NUDGE_REGISTRY.find((e) => e.id === 'github-star-modal')!;
+ const dsv4 = NUDGE_REGISTRY.find((e) => e.id === 'dsv4-launch-modal')!;
+ expect(entry.priority ?? 0).toBeLessThan(dsv4.priority ?? 0);
+ expect(entry.condition).toBeDefined();
+ });
+
+ it('launch-banner uses forever persistence (one-shot announcement)', () => {
+ const entry = NUDGE_REGISTRY.find((e) => e.id === 'launch-banner-dsv4')!;
+ expect(entry.kind).toBe('banner');
+ expect(entry.persistence).toEqual({ kind: 'forever' });
+ });
+});
+
+describe('userHasStarredRepo', () => {
+ let store: Map;
+
+ beforeEach(() => {
+ store = new Map();
+ vi.stubGlobal('localStorage', {
+ getItem: (k: string) => store.get(k) ?? null,
+ setItem: (k: string, v: string) => {
+ store.set(k, v);
+ },
+ removeItem: (k: string) => {
+ store.delete(k);
+ },
+ });
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ });
+
+ it('returns false when the starred flag is absent', () => {
+ expect(userHasStarredRepo()).toBe(false);
+ });
+
+ it('returns true when the starred flag is set', () => {
+ store.set('inferencex-starred', '1');
+ expect(userHasStarredRepo()).toBe(true);
+ });
+
+ it('returns false when localStorage throws', () => {
+ vi.stubGlobal('localStorage', {
+ getItem: () => {
+ throw new Error('SecurityError');
+ },
+ });
+ expect(userHasStarredRepo()).toBe(false);
+ });
+});
diff --git a/packages/app/src/components/nudges/registry.ts b/packages/app/src/components/nudges/registry.ts
new file mode 100644
index 00000000..5167e41c
--- /dev/null
+++ b/packages/app/src/components/nudges/registry.ts
@@ -0,0 +1,244 @@
+import {
+ ArrowRight,
+ Download,
+ MessageSquareText,
+ Palette,
+ ShieldCheck,
+ Sparkles,
+ Star,
+} from 'lucide-react';
+import { createElement } from 'react';
+
+import { GITHUB_OWNER, GITHUB_REPO } from '@semianalysisai/inferencex-constants';
+import { isDismissed, type NudgeEntry } from '@/lib/nudges';
+import { STARRED_EVENT, STARRED_KEY, saveStarred } from '@/lib/star-storage';
+
+const GITHUB_REPO_URL = `https://github.com/${GITHUB_OWNER}/${GITHUB_REPO}`;
+const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+const LANDING_ROUTE = /^\/?$/;
+const DASHBOARD_ROUTE =
+ /^\/(inference|evaluation|historical|calculator|reliability|gpu-specs|gpu-metrics|ai-chart|submissions)(\/|$)/;
+const EVALUATION_ROUTE = /^\/evaluation(\/|$)/;
+
+const DSV4_LAUNCH_PRESET_HREF = '/inference?preset=dsv4-launch';
+
+export function userHasStarredRepo(): boolean {
+ try {
+ return localStorage.getItem(STARRED_KEY) === '1';
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Registry of every engagement nudge on the site. Each entry declares its
+ * trigger, audience, persistence, and analytics id in one place — the framework
+ * (`NudgeRoot` + `Nudge`) handles the rest.
+ *
+ * Adding a new nudge: append an entry here, no other code changes required.
+ */
+export const NUDGE_REGISTRY: NudgeEntry[] = [
+ // ---------------------------------------------------------------------
+ // Banners
+ // ---------------------------------------------------------------------
+ {
+ id: 'launch-banner-dsv4',
+ kind: 'banner',
+ trigger: { kind: 'mount' },
+ persistence: { kind: 'forever' },
+ routes: [LANDING_ROUTE],
+ render: () => ({
+ icon: createElement(Sparkles, { className: 'size-4 animate-pulse' }),
+ title: 'DeepSeek V4 Pro benchmarks are live',
+ badge: 'New',
+ description: 'First inference numbers across NVIDIA and AMD GPUs, click to explore.',
+ primaryAction: {
+ label: 'Explore',
+ href: DSV4_LAUNCH_PRESET_HREF,
+ // Hard navigation so the `?preset=` param is in the URL when
+ // InferenceContext first mounts and reads window.location.search.
+ },
+ }),
+ },
+
+ // ---------------------------------------------------------------------
+ // Modals (priority gates exclusivity — higher number wins)
+ // ---------------------------------------------------------------------
+ {
+ id: 'dsv4-launch-modal',
+ kind: 'modal',
+ trigger: { kind: 'mount' },
+ persistence: { kind: 'forever' },
+ priority: 100,
+ routes: [LANDING_ROUTE],
+ render: () => ({
+ icon: createElement(Sparkles, { className: 'size-5 text-brand' }),
+ title: 'DeepSeek V4 Pro is live',
+ badge: 'New',
+ description:
+ 'Day-zero benchmarks for DeepSeek V4 Pro are now available across the latest NVIDIA and AMD GPUs. Results are experimental — see how the new model performs across hardware.',
+ primaryAction: {
+ label: 'Explore',
+ icon: createElement(ArrowRight, { className: 'size-4' }),
+ href: DSV4_LAUNCH_PRESET_HREF,
+ },
+ }),
+ },
+ {
+ id: 'github-star-modal',
+ kind: 'modal',
+ trigger: { kind: 'mount' },
+ persistence: { kind: 'cooldown', durationMs: ONE_WEEK_MS },
+ priority: 50,
+ routes: [LANDING_ROUTE],
+ // Defer to the launch modal until that one resolves.
+ condition: () => !shouldShowDsv4Modal() && !userHasStarredRepo(),
+ externalDismissEvents: [STARRED_EVENT],
+ render: () => ({
+ icon: createElement(Star, { className: 'size-5 text-yellow-500 fill-yellow-500' }),
+ title: 'Star InferenceX on GitHub',
+ description:
+ 'Star InferenceX on GitHub to get notified when we publish new benchmark data. We update GPU performance comparisons regularly — starring is the easiest way to stay in the loop and help the project grow.',
+ primaryAction: {
+ label: 'Star on GitHub',
+ href: GITHUB_REPO_URL,
+ target: '_blank',
+ onClick: () => saveStarred(),
+ },
+ }),
+ },
+
+ // ---------------------------------------------------------------------
+ // Toasts (engagement)
+ // ---------------------------------------------------------------------
+ {
+ id: 'reproducibility-nudge',
+ kind: 'toast',
+ trigger: { kind: 'mount-delay', delayMs: 1500 },
+ persistence: { kind: 'session' },
+ routes: [DASHBOARD_ROUTE],
+ render: () => ({
+ icon: createElement(ShieldCheck, { className: 'text-brand' }),
+ title: 'Every result is reproducible',
+ description:
+ 'Each data point is produced by a public GitHub Actions run. Click any point on a chart to jump to the exact run, logs, and artifacts.',
+ primaryAction: {
+ label: 'See how',
+ href: '/about#reproducibility',
+ inApp: true,
+ },
+ }),
+ },
+ {
+ id: 'star-nudge',
+ kind: 'toast',
+ trigger: {
+ kind: 'event',
+ events: [
+ { name: 'inferencex:tab-change', threshold: 2 },
+ { name: 'inferencex:action', threshold: 1 },
+ ],
+ afterDelayMs: 1500,
+ },
+ persistence: { kind: 'session' },
+ condition: () => !userHasStarredRepo(),
+ externalDismissEvents: [STARRED_EVENT],
+ render: () => ({
+ icon: createElement(Star, { className: 'text-yellow-500 fill-yellow-500' }),
+ title: 'Finding us useful?',
+ description: 'Help the project grow so we can add more benchmarks! Star us on GitHub.',
+ primaryAction: {
+ label: 'Star on GitHub',
+ icon: createElement(
+ 'svg',
+ {
+ xmlns: 'http://www.w3.org/2000/svg',
+ viewBox: '0 0 16 16',
+ fill: 'currentColor',
+ className: 'size-3.5',
+ },
+ createElement('path', {
+ d: 'M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z',
+ }),
+ ),
+ href: GITHUB_REPO_URL,
+ target: '_blank',
+ onClick: () => saveStarred(),
+ },
+ }),
+ },
+ {
+ id: 'export-nudge',
+ kind: 'toast',
+ trigger: {
+ kind: 'event',
+ events: [
+ {
+ name: 'copy',
+ threshold: 2,
+ target: 'document',
+ selector: '[data-chart-tooltip]',
+ },
+ ],
+ },
+ persistence: { kind: 'session' },
+ routes: [DASHBOARD_ROUTE],
+ render: () => ({
+ icon: createElement(Download, { className: 'text-blue-500' }),
+ title: 'Need the data?',
+ description:
+ 'Use the download button on any chart to export as PNG or CSV — no need to copy from tooltips.',
+ }),
+ },
+ {
+ id: 'gradient-label-nudge',
+ kind: 'toast',
+ trigger: {
+ kind: 'event',
+ events: [{ name: 'inferencex:parallelism-label-enabled', threshold: 1 }],
+ },
+ persistence: { kind: 'session' },
+ render: (ctx) => {
+ const detail = ctx.triggerDetail as { enableGradient?: () => void } | undefined;
+ return {
+ icon: createElement(Palette, { className: 'text-purple-500' }),
+ title: 'Try Gradient Labels',
+ description:
+ 'Gradient labels color-code data points by parallelism level, making it easier to spot performance patterns at a glance.',
+ primaryAction: {
+ label: 'Enable Gradient Labels',
+ onClick: () => detail?.enableGradient?.(),
+ },
+ };
+ },
+ },
+ {
+ id: 'eval-samples-nudge',
+ kind: 'toast',
+ trigger: { kind: 'mount-delay', delayMs: 1500 },
+ persistence: { kind: 'cooldown', durationMs: ONE_WEEK_MS },
+ // Page-scoped toasts outrank the always-on toasts so users land on the
+ // page-relevant nudge first (mirrors the original DashboardShell vs.
+ // EvaluationPage mount order).
+ priority: 10,
+ routes: [EVALUATION_ROUTE],
+ externalDismissEvents: ['inferencex:eval-samples-opened'],
+ render: () => ({
+ icon: createElement(MessageSquareText, { className: 'text-brand' }),
+ title: "See the model's actual answers",
+ description:
+ 'Click Prompts on any row to compare each prompt, the expected answer, and what the model actually responded.',
+ }),
+ },
+];
+
+/**
+ * Helper used by the github-star-modal `condition` predicate so the modal
+ * defers to the time-sensitive launch modal until the user resolves it.
+ */
+function shouldShowDsv4Modal(): boolean {
+ const dsv4 = NUDGE_REGISTRY.find((n) => n.id === 'dsv4-launch-modal');
+ if (!dsv4) return false;
+ return !isDismissed(dsv4.id, dsv4.persistence);
+}
diff --git a/packages/app/src/components/nudges/use-nudge-trigger.ts b/packages/app/src/components/nudges/use-nudge-trigger.ts
new file mode 100644
index 00000000..d72f3e48
--- /dev/null
+++ b/packages/app/src/components/nudges/use-nudge-trigger.ts
@@ -0,0 +1,98 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import type { NudgeTrigger } from '@/lib/nudges';
+
+interface UseNudgeTriggerOptions {
+ trigger: NudgeTrigger;
+ /** Whether the nudge is currently allowed to fire (route + persistence + condition + schedule). */
+ enabled: boolean;
+ /**
+ * Once a nudge has been queued, ignore further trigger fires (we don't want a
+ * single nudge to be re-queued mid-display by a chatty event).
+ */
+ alreadyShown: boolean;
+}
+
+interface TriggerState {
+ /** True once the trigger condition has been satisfied. */
+ fired: boolean;
+ /** Detail object from the firing CustomEvent, if any. */
+ detail: unknown;
+}
+
+/**
+ * Wires a NudgeTrigger up to React state. Returns `{ fired, detail }` — once
+ * `fired` flips true, the parent component renders the nudge.
+ */
+export function useNudgeTrigger({
+ trigger,
+ enabled,
+ alreadyShown,
+}: UseNudgeTriggerOptions): TriggerState {
+ const [state, setState] = useState({ fired: false, detail: undefined });
+ const eventCounts = useRef>(new Map());
+
+ useEffect(() => {
+ if (!enabled || alreadyShown || state.fired) return;
+
+ if (trigger.kind === 'mount') {
+ setState({ fired: true, detail: undefined });
+ return;
+ }
+
+ if (trigger.kind === 'mount-delay') {
+ const id = window.setTimeout(() => {
+ setState({ fired: true, detail: undefined });
+ }, trigger.delayMs);
+ return () => window.clearTimeout(id);
+ }
+
+ // Event trigger — listen for one or more named CustomEvents. Each event
+ // can have its own threshold (default 1). The trigger fires the first
+ // time *any* tracked event meets its threshold.
+ const counts = eventCounts.current;
+ const cleanups: (() => void)[] = [];
+ let pendingTimer: number | null = null;
+
+ const fireAfterDelay = (detail: unknown) => {
+ const delayMs = trigger.afterDelayMs ?? 0;
+ if (delayMs <= 0) {
+ setState({ fired: true, detail });
+ return;
+ }
+ if (pendingTimer !== null) return;
+ pendingTimer = window.setTimeout(() => {
+ pendingTimer = null;
+ setState({ fired: true, detail });
+ }, delayMs);
+ };
+
+ for (const evt of trigger.events) {
+ const threshold = evt.threshold ?? 1;
+ const target: EventTarget = evt.target === 'document' ? document : window;
+ const handler = (e: Event) => {
+ if (evt.selector) {
+ const t = e.target as Element | null;
+ if (!t || !t.closest || !t.closest(evt.selector)) return;
+ }
+ const next = (counts.get(evt.name) ?? 0) + 1;
+ counts.set(evt.name, next);
+ if (next >= threshold) {
+ const detail = e instanceof CustomEvent ? e.detail : undefined;
+ fireAfterDelay(detail);
+ }
+ };
+ target.addEventListener(evt.name, handler);
+ cleanups.push(() => target.removeEventListener(evt.name, handler));
+ }
+
+ return () => {
+ if (pendingTimer !== null) window.clearTimeout(pendingTimer);
+ for (const cleanup of cleanups) cleanup();
+ };
+ }, [trigger, enabled, alreadyShown, state.fired]);
+
+ return state;
+}
diff --git a/packages/app/src/components/reproducibility-nudge.tsx b/packages/app/src/components/reproducibility-nudge.tsx
deleted file mode 100644
index 4d32a93b..00000000
--- a/packages/app/src/components/reproducibility-nudge.tsx
+++ /dev/null
@@ -1,64 +0,0 @@
-'use client';
-
-import { ShieldCheck } from 'lucide-react';
-import { useRouter } from 'next/navigation';
-import { useCallback, useEffect, useState } from 'react';
-
-import { BottomToast } from '@/components/ui/bottom-toast';
-import { track } from '@/lib/analytics';
-
-const SESSION_KEY = 'inferencex-reproducibility-nudge-shown';
-const SHOW_DELAY_MS = 1500;
-const ABOUT_URL = '/about#reproducibility';
-
-function shouldShow(): boolean {
- try {
- return !sessionStorage.getItem(SESSION_KEY);
- } catch {
- return false;
- }
-}
-
-function markShown(): void {
- try {
- sessionStorage.setItem(SESSION_KEY, '1');
- } catch {
- // ignore
- }
-}
-
-export function ReproducibilityNudge() {
- const router = useRouter();
- const [visible, setVisible] = useState(false);
-
- useEffect(() => {
- if (!shouldShow()) return;
- const timer = window.setTimeout(() => {
- markShown();
- setVisible(true);
- track('reproducibility_nudge_shown');
- }, SHOW_DELAY_MS);
- return () => window.clearTimeout(timer);
- }, []);
-
- const handleAction = useCallback(() => {
- track('reproducibility_nudge_see_how_clicked');
- router.push(ABOUT_URL);
- }, [router]);
-
- if (!visible) return null;
-
- return (
- }
- title="Every result is reproducible"
- description="Each data point is produced by a public GitHub Actions run. Click any point on a chart to jump to the exact run, logs, and artifacts."
- action={{
- label: 'See how',
- onClick: handleAction,
- }}
- onDismiss={() => track('reproducibility_nudge_dismissed')}
- />
- );
-}
diff --git a/packages/app/src/components/star-nudge.test.ts b/packages/app/src/components/star-nudge.test.ts
deleted file mode 100644
index 36e605dc..00000000
--- a/packages/app/src/components/star-nudge.test.ts
+++ /dev/null
@@ -1,105 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-
-import { NUDGE_SESSION_KEY, saveNudgeShown, shouldShowNudge } from '@/components/star-nudge';
-
-describe('StarNudge constants', () => {
- it('uses the expected sessionStorage key', () => {
- expect(NUDGE_SESSION_KEY).toBe('inferencex-star-nudge-shown');
- });
-});
-
-describe('shouldShowNudge', () => {
- const mockSession = new Map();
- const mockLocal = new Map();
-
- beforeEach(() => {
- mockSession.clear();
- mockLocal.clear();
- vi.stubGlobal('sessionStorage', {
- getItem: (key: string) => mockSession.get(key) ?? null,
- setItem: (key: string, value: string) => mockSession.set(key, value),
- removeItem: (key: string) => mockSession.delete(key),
- });
- vi.stubGlobal('localStorage', {
- getItem: (key: string) => mockLocal.get(key) ?? null,
- setItem: (key: string, value: string) => mockLocal.set(key, value),
- removeItem: (key: string) => mockLocal.delete(key),
- });
- });
-
- afterEach(() => {
- vi.unstubAllGlobals();
- vi.restoreAllMocks();
- });
-
- it('returns true when no session value is stored', () => {
- expect(shouldShowNudge()).toBe(true);
- });
-
- it('returns false when nudge was already shown this session', () => {
- mockSession.set(NUDGE_SESSION_KEY, '1');
- expect(shouldShowNudge()).toBe(false);
- });
-
- it('returns false when user has already starred', () => {
- mockLocal.set('inferencex-starred', '1');
- expect(shouldShowNudge()).toBe(false);
- });
-
- it('returns false when storage throws', () => {
- vi.stubGlobal('localStorage', {
- getItem: () => {
- throw new Error('SecurityError');
- },
- });
- expect(shouldShowNudge()).toBe(false);
- });
-});
-
-describe('saveNudgeShown', () => {
- const mockSession = new Map();
- const mockLocal = new Map();
-
- beforeEach(() => {
- mockSession.clear();
- mockLocal.clear();
- vi.stubGlobal('sessionStorage', {
- getItem: (key: string) => mockSession.get(key) ?? null,
- setItem: (key: string, value: string) => mockSession.set(key, value),
- removeItem: (key: string) => mockSession.delete(key),
- });
- vi.stubGlobal('localStorage', {
- getItem: (key: string) => mockLocal.get(key) ?? null,
- setItem: (key: string, value: string) => mockLocal.set(key, value),
- removeItem: (key: string) => mockLocal.delete(key),
- });
- });
-
- afterEach(() => {
- vi.unstubAllGlobals();
- vi.restoreAllMocks();
- });
-
- it('stores a value in sessionStorage', () => {
- saveNudgeShown();
- const stored = mockSession.get(NUDGE_SESSION_KEY);
- expect(stored).toBe('1');
- });
-
- it('does not throw when sessionStorage is unavailable', () => {
- vi.stubGlobal('sessionStorage', {
- getItem: () => {
- throw new Error('SecurityError');
- },
- setItem: () => {
- throw new Error('SecurityError');
- },
- });
- expect(() => saveNudgeShown()).not.toThrow();
- });
-
- it('makes shouldShowNudge return false after saving', () => {
- saveNudgeShown();
- expect(shouldShowNudge()).toBe(false);
- });
-});
diff --git a/packages/app/src/components/star-nudge.tsx b/packages/app/src/components/star-nudge.tsx
deleted file mode 100644
index 28acb375..00000000
--- a/packages/app/src/components/star-nudge.tsx
+++ /dev/null
@@ -1,104 +0,0 @@
-'use client';
-
-import { track } from '@/lib/analytics';
-import { Star } from 'lucide-react';
-import { useCallback, useEffect, useRef, useState } from 'react';
-
-import { GITHUB_OWNER, GITHUB_REPO } from '@semianalysisai/inferencex-constants';
-import { STARRED_EVENT, STARRED_KEY } from '@/lib/star-storage';
-import { BottomToast } from '@/components/ui/bottom-toast';
-
-const GITHUB_REPO_URL = `https://github.com/${GITHUB_OWNER}/${GITHUB_REPO}`;
-
-export const NUDGE_SESSION_KEY = 'inferencex-star-nudge-shown';
-const TAB_CHANGE_THRESHOLD = 2;
-
-export function shouldShowNudge(): boolean {
- try {
- if (localStorage.getItem(STARRED_KEY)) return false;
- if (sessionStorage.getItem(NUDGE_SESSION_KEY)) return false;
- return true;
- } catch {
- return false;
- }
-}
-
-export function saveNudgeShown(): void {
- try {
- sessionStorage.setItem(NUDGE_SESSION_KEY, '1');
- } catch {
- // sessionStorage unavailable
- }
-}
-
-export function StarNudge() {
- const [visible, setVisible] = useState(false);
- const tabChangeCount = useRef(0);
- const hasShown = useRef(false);
-
- const showNudge = useCallback(() => {
- if (hasShown.current) return;
- if (!shouldShowNudge()) return;
- hasShown.current = true;
- saveNudgeShown();
- setVisible(true);
- track('star_nudge_shown');
- }, []);
-
- useEffect(() => {
- const handleTabChange = () => {
- if (hasShown.current) return;
- tabChangeCount.current += 1;
- if (tabChangeCount.current >= TAB_CHANGE_THRESHOLD) {
- showNudge();
- }
- };
-
- const handleAction = () => {
- if (hasShown.current) return;
- setTimeout(() => showNudge(), 1500);
- };
-
- const handleStarred = () => setVisible(false);
-
- window.addEventListener('inferencex:tab-change', handleTabChange);
- window.addEventListener('inferencex:action', handleAction);
- window.addEventListener(STARRED_EVENT, handleStarred);
- return () => {
- window.removeEventListener('inferencex:tab-change', handleTabChange);
- window.removeEventListener('inferencex:action', handleAction);
- window.removeEventListener(STARRED_EVENT, handleStarred);
- };
- }, [showNudge]);
-
- const handleStar = useCallback(() => {
- window.open(GITHUB_REPO_URL, '_blank', 'noopener,noreferrer');
- track('star_nudge_starred');
- }, []);
-
- if (!visible) return null;
-
- return (
- }
- title="Finding us useful?"
- description="Help the project grow so we can add more benchmarks! Star us on GitHub."
- action={{
- label: 'Star on GitHub',
- icon: (
-
- ),
- onClick: handleStar,
- }}
- onDismiss={() => track('star_nudge_dismissed')}
- />
- );
-}
diff --git a/packages/app/src/lib/dsv4-launch-storage.ts b/packages/app/src/lib/dsv4-launch-storage.ts
deleted file mode 100644
index b70a03ca..00000000
--- a/packages/app/src/lib/dsv4-launch-storage.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-export const DSV4_MODAL_DISMISSED_KEY = 'inferencex-dsv4-modal-dismissed';
-
-export function isDsv4ModalDismissed(): boolean {
- try {
- return localStorage.getItem(DSV4_MODAL_DISMISSED_KEY) === '1';
- } catch {
- return false;
- }
-}
-
-export function saveDsv4ModalDismissed(): void {
- try {
- localStorage.setItem(DSV4_MODAL_DISMISSED_KEY, '1');
- } catch {
- // localStorage unavailable
- }
-}
diff --git a/packages/app/src/lib/nudges/index.ts b/packages/app/src/lib/nudges/index.ts
new file mode 100644
index 00000000..eb238bab
--- /dev/null
+++ b/packages/app/src/lib/nudges/index.ts
@@ -0,0 +1,19 @@
+export type {
+ NudgeAction,
+ NudgeContent,
+ NudgeContext,
+ NudgeEntry,
+ NudgeKind,
+ NudgePersistence,
+ NudgeSchedule,
+ NudgeTrigger,
+} from './types';
+export {
+ dismissalKey,
+ isDismissed,
+ markDismissed,
+ clearDismissal,
+ STORAGE_PREFIX,
+} from './persistence';
+export { isWithinSchedule } from './scheduling';
+export { shouldShowNudge } from './should-show';
diff --git a/packages/app/src/lib/nudges/persistence.test.ts b/packages/app/src/lib/nudges/persistence.test.ts
new file mode 100644
index 00000000..3d3fba65
--- /dev/null
+++ b/packages/app/src/lib/nudges/persistence.test.ts
@@ -0,0 +1,142 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { clearDismissal, dismissalKey, isDismissed, markDismissed } from './persistence';
+import type { NudgePersistence } from './types';
+
+describe('dismissalKey', () => {
+ it('namespaces with the framework prefix', () => {
+ expect(dismissalKey('star-nudge')).toBe('inferencex-nudge:star-nudge');
+ });
+});
+
+interface FakeStorage {
+ store: Map;
+ getItem: (k: string) => string | null;
+ setItem: (k: string, v: string) => void;
+ removeItem: (k: string) => void;
+}
+
+function makeStorage(): FakeStorage {
+ const store = new Map();
+ return {
+ store,
+ getItem: (k) => store.get(k) ?? null,
+ setItem: (k, v) => {
+ store.set(k, v);
+ },
+ removeItem: (k) => {
+ store.delete(k);
+ },
+ };
+}
+
+function stubStorages() {
+ const local = makeStorage();
+ const session = makeStorage();
+ vi.stubGlobal('localStorage', local);
+ vi.stubGlobal('sessionStorage', session);
+ return { local, session };
+}
+
+describe('isDismissed', () => {
+ let local: FakeStorage;
+ let session: FakeStorage;
+
+ beforeEach(() => {
+ ({ local, session } = stubStorages());
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ });
+
+ it('returns false when storage has no value', () => {
+ const policy: NudgePersistence = { kind: 'forever' };
+ expect(isDismissed('foo', policy)).toBe(false);
+ });
+
+ it('treats `forever` as dismissed once any value is stored', () => {
+ const policy: NudgePersistence = { kind: 'forever' };
+ markDismissed('foo', policy);
+ expect(isDismissed('foo', policy)).toBe(true);
+ });
+
+ it('uses sessionStorage for `session` policy', () => {
+ const policy: NudgePersistence = { kind: 'session' };
+ markDismissed('foo', policy);
+ expect(session.store.has(dismissalKey('foo'))).toBe(true);
+ expect(local.store.has(dismissalKey('foo'))).toBe(false);
+ });
+
+ it('expires the cooldown after duration elapses', () => {
+ const policy: NudgePersistence = { kind: 'cooldown', durationMs: 1000 };
+ markDismissed('foo', policy, 0);
+ expect(isDismissed('foo', policy, 500)).toBe(true);
+ expect(isDismissed('foo', policy, 1500)).toBe(false);
+ });
+
+ it('treats malformed cooldown timestamps as not dismissed', () => {
+ const policy: NudgePersistence = { kind: 'cooldown', durationMs: 1000 };
+ local.store.set(dismissalKey('foo'), 'not-a-number');
+ expect(isDismissed('foo', policy)).toBe(false);
+ });
+
+ it('fails closed (treats as dismissed) when storage throws', () => {
+ vi.stubGlobal('localStorage', {
+ getItem: () => {
+ throw new Error('SecurityError');
+ },
+ setItem: () => {
+ throw new Error('SecurityError');
+ },
+ removeItem: () => {},
+ });
+ const policy: NudgePersistence = { kind: 'forever' };
+ expect(isDismissed('foo', policy)).toBe(true);
+ });
+});
+
+describe('markDismissed / clearDismissal', () => {
+ beforeEach(() => {
+ stubStorages();
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ });
+
+ it('round-trips a forever dismissal', () => {
+ const policy: NudgePersistence = { kind: 'forever' };
+ markDismissed('foo', policy);
+ expect(isDismissed('foo', policy)).toBe(true);
+ clearDismissal('foo', policy);
+ expect(isDismissed('foo', policy)).toBe(false);
+ });
+
+ it('round-trips a cooldown dismissal', () => {
+ const policy: NudgePersistence = { kind: 'cooldown', durationMs: 1000 };
+ markDismissed('foo', policy, 100);
+ expect(isDismissed('foo', policy, 200)).toBe(true);
+ clearDismissal('foo', policy);
+ expect(isDismissed('foo', policy, 200)).toBe(false);
+ });
+
+ it('does not throw when storage is unavailable', () => {
+ vi.stubGlobal('localStorage', {
+ getItem: () => {
+ throw new Error('SecurityError');
+ },
+ setItem: () => {
+ throw new Error('SecurityError');
+ },
+ removeItem: () => {
+ throw new Error('SecurityError');
+ },
+ });
+ const policy: NudgePersistence = { kind: 'forever' };
+ expect(() => markDismissed('foo', policy)).not.toThrow();
+ expect(() => clearDismissal('foo', policy)).not.toThrow();
+ });
+});
diff --git a/packages/app/src/lib/nudges/persistence.ts b/packages/app/src/lib/nudges/persistence.ts
new file mode 100644
index 00000000..0a820bdf
--- /dev/null
+++ b/packages/app/src/lib/nudges/persistence.ts
@@ -0,0 +1,79 @@
+import type { NudgePersistence } from './types';
+
+export const STORAGE_PREFIX = 'inferencex-nudge:';
+
+export function dismissalKey(id: string): string {
+ return `${STORAGE_PREFIX}${id}`;
+}
+
+interface StorageLike {
+ getItem(key: string): string | null;
+ setItem(key: string, value: string): void;
+ removeItem(key: string): void;
+}
+
+function getStorage(persistence: NudgePersistence): StorageLike | null {
+ try {
+ // Reference globals directly (rather than via `window`) so unit tests can
+ // stub `localStorage` / `sessionStorage` with `vi.stubGlobal` in a node env.
+ return persistence.kind === 'session' ? sessionStorage : localStorage;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Whether a nudge is currently considered dismissed under its persistence
+ * policy. `forever` and `session` are simple flags; `cooldown` is a timestamp
+ * that expires after `durationMs`.
+ */
+export function isDismissed(
+ id: string,
+ persistence: NudgePersistence,
+ now: number = Date.now(),
+): boolean {
+ const storage = getStorage(persistence);
+ if (!storage) return false;
+ try {
+ const value = storage.getItem(dismissalKey(id));
+ if (!value) return false;
+ if (persistence.kind === 'cooldown') {
+ const dismissedAt = Number(value);
+ if (Number.isNaN(dismissedAt)) return false;
+ return now - dismissedAt < persistence.durationMs;
+ }
+ return true;
+ } catch {
+ // Treat storage-read failures as "dismissed" to fail closed and avoid
+ // re-showing a nudge that the user may have actually dismissed.
+ return true;
+ }
+}
+
+/** Mark a nudge dismissed under its persistence policy. */
+export function markDismissed(
+ id: string,
+ persistence: NudgePersistence,
+ now: number = Date.now(),
+): void {
+ const storage = getStorage(persistence);
+ if (!storage) return;
+ try {
+ const value = persistence.kind === 'cooldown' ? String(now) : '1';
+ storage.setItem(dismissalKey(id), value);
+ } catch {
+ // Storage unavailable — the nudge will reappear next mount, but that's
+ // safer than silently breaking the page.
+ }
+}
+
+/** Forget the dismissal so the nudge can be re-shown. */
+export function clearDismissal(id: string, persistence: NudgePersistence): void {
+ const storage = getStorage(persistence);
+ if (!storage) return;
+ try {
+ storage.removeItem(dismissalKey(id));
+ } catch {
+ // ignore
+ }
+}
diff --git a/packages/app/src/lib/nudges/scheduling.test.ts b/packages/app/src/lib/nudges/scheduling.test.ts
new file mode 100644
index 00000000..70ba75d6
--- /dev/null
+++ b/packages/app/src/lib/nudges/scheduling.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+
+import { isWithinSchedule } from './scheduling';
+
+const T = (s: string) => Date.parse(s);
+
+describe('isWithinSchedule', () => {
+ it('returns true when no schedule is provided', () => {
+ expect(isWithinSchedule(undefined)).toBe(true);
+ });
+
+ it('rejects times before showAfter', () => {
+ expect(isWithinSchedule({ showAfter: '2026-01-01T00:00:00Z' }, T('2025-12-31T23:59:59Z'))).toBe(
+ false,
+ );
+ });
+
+ it('accepts times at or after showAfter', () => {
+ expect(isWithinSchedule({ showAfter: '2026-01-01T00:00:00Z' }, T('2026-01-01T00:00:00Z'))).toBe(
+ true,
+ );
+ });
+
+ it('rejects times at or after hideAfter', () => {
+ expect(isWithinSchedule({ hideAfter: '2026-01-01T00:00:00Z' }, T('2026-01-01T00:00:00Z'))).toBe(
+ false,
+ );
+ });
+
+ it('accepts times before hideAfter', () => {
+ expect(isWithinSchedule({ hideAfter: '2026-01-01T00:00:00Z' }, T('2025-12-31T23:59:59Z'))).toBe(
+ true,
+ );
+ });
+
+ it('respects both bounds simultaneously', () => {
+ const schedule = { showAfter: '2026-01-01T00:00:00Z', hideAfter: '2026-02-01T00:00:00Z' };
+ expect(isWithinSchedule(schedule, T('2025-12-15T00:00:00Z'))).toBe(false);
+ expect(isWithinSchedule(schedule, T('2026-01-15T00:00:00Z'))).toBe(true);
+ expect(isWithinSchedule(schedule, T('2026-02-15T00:00:00Z'))).toBe(false);
+ });
+
+ it('treats unparseable ISO strings as no bound', () => {
+ expect(isWithinSchedule({ showAfter: 'whenever' }, 0)).toBe(true);
+ expect(isWithinSchedule({ hideAfter: 'whenever' }, Number.MAX_SAFE_INTEGER)).toBe(true);
+ });
+});
diff --git a/packages/app/src/lib/nudges/scheduling.ts b/packages/app/src/lib/nudges/scheduling.ts
new file mode 100644
index 00000000..319446b8
--- /dev/null
+++ b/packages/app/src/lib/nudges/scheduling.ts
@@ -0,0 +1,22 @@
+import type { NudgeSchedule } from './types';
+
+/**
+ * Whether `now` falls inside the nudge's [showAfter, hideAfter] window.
+ * Either bound is optional. Invalid ISO strings are treated as "no bound" so
+ * a typo in the registry doesn't silently disable a nudge.
+ */
+export function isWithinSchedule(
+ schedule: NudgeSchedule | undefined,
+ now: number = Date.now(),
+): boolean {
+ if (!schedule) return true;
+ if (schedule.showAfter) {
+ const t = Date.parse(schedule.showAfter);
+ if (!Number.isNaN(t) && now < t) return false;
+ }
+ if (schedule.hideAfter) {
+ const t = Date.parse(schedule.hideAfter);
+ if (!Number.isNaN(t) && now >= t) return false;
+ }
+ return true;
+}
diff --git a/packages/app/src/lib/nudges/should-show.test.ts b/packages/app/src/lib/nudges/should-show.test.ts
new file mode 100644
index 00000000..83c4d208
--- /dev/null
+++ b/packages/app/src/lib/nudges/should-show.test.ts
@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { dismissalKey } from './persistence';
+import { shouldShowNudge } from './should-show';
+import type { NudgeEntry } from './types';
+
+function fakeStorage() {
+ const store = new Map();
+ return {
+ store,
+ getItem: (k: string) => store.get(k) ?? null,
+ setItem: (k: string, v: string) => {
+ store.set(k, v);
+ },
+ removeItem: (k: string) => {
+ store.delete(k);
+ },
+ };
+}
+
+const baseEntry: NudgeEntry = {
+ id: 'test-nudge',
+ kind: 'toast',
+ trigger: { kind: 'mount' },
+ persistence: { kind: 'session' },
+ render: () => ({
+ icon: null,
+ title: 'Test',
+ description: 'Test description',
+ }),
+};
+
+describe('shouldShowNudge', () => {
+ let local: ReturnType;
+ let session: ReturnType;
+
+ beforeEach(() => {
+ local = fakeStorage();
+ session = fakeStorage();
+ vi.stubGlobal('localStorage', local);
+ vi.stubGlobal('sessionStorage', session);
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ });
+
+ it('returns true with no constraints', () => {
+ expect(shouldShowNudge(baseEntry)).toBe(true);
+ });
+
+ it('returns false when persistence flag is set', () => {
+ session.store.set(dismissalKey(baseEntry.id), '1');
+ expect(shouldShowNudge(baseEntry)).toBe(false);
+ });
+
+ it('respects schedule bounds', () => {
+ const entry = { ...baseEntry, schedule: { hideAfter: '2026-01-01T00:00:00Z' } };
+ expect(shouldShowNudge(entry, { now: Date.parse('2025-12-31T23:59:59Z') })).toBe(true);
+ expect(shouldShowNudge(entry, { now: Date.parse('2026-01-02T00:00:00Z') })).toBe(false);
+ });
+
+ it('requires the pathname to match if routes are set', () => {
+ const entry = { ...baseEntry, routes: [/^\/inference/] };
+ expect(shouldShowNudge(entry, { pathname: '/inference' })).toBe(true);
+ expect(shouldShowNudge(entry, { pathname: '/about' })).toBe(false);
+ // No pathname provided + routes specified means no route info → reject.
+ expect(shouldShowNudge(entry)).toBe(false);
+ });
+
+ it('runs the condition predicate last', () => {
+ const condition = vi.fn(() => false);
+ expect(shouldShowNudge({ ...baseEntry, condition })).toBe(false);
+ expect(condition).toHaveBeenCalledOnce();
+ });
+
+ it('skips condition when persistence already vetoed', () => {
+ const condition = vi.fn(() => true);
+ session.store.set(dismissalKey(baseEntry.id), '1');
+ expect(shouldShowNudge({ ...baseEntry, condition })).toBe(false);
+ expect(condition).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/app/src/lib/nudges/should-show.ts b/packages/app/src/lib/nudges/should-show.ts
new file mode 100644
index 00000000..dcdcc283
--- /dev/null
+++ b/packages/app/src/lib/nudges/should-show.ts
@@ -0,0 +1,25 @@
+import { isDismissed } from './persistence';
+import { isWithinSchedule } from './scheduling';
+import type { NudgeEntry } from './types';
+
+interface ShouldShowOptions {
+ pathname?: string;
+ now?: number;
+}
+
+/**
+ * Pure pre-flight check: would this nudge be allowed to show right now,
+ * ignoring trigger semantics (mount/event)? Combines route match, persistence,
+ * schedule, and the optional condition predicate.
+ */
+export function shouldShowNudge(entry: NudgeEntry, options: ShouldShowOptions = {}): boolean {
+ const { pathname, now = Date.now() } = options;
+ if (entry.routes && entry.routes.length > 0) {
+ if (pathname === undefined) return false;
+ if (!entry.routes.some((re) => re.test(pathname))) return false;
+ }
+ if (!isWithinSchedule(entry.schedule, now)) return false;
+ if (isDismissed(entry.id, entry.persistence, now)) return false;
+ if (entry.condition && !entry.condition()) return false;
+ return true;
+}
diff --git a/packages/app/src/lib/nudges/types.ts b/packages/app/src/lib/nudges/types.ts
new file mode 100644
index 00000000..36aa3a63
--- /dev/null
+++ b/packages/app/src/lib/nudges/types.ts
@@ -0,0 +1,134 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Surface a nudge renders on. The framework picks a different visual treatment
+ * (and z-index slot) per kind, but every kind shares the same registry, trigger,
+ * persistence, and analytics machinery.
+ */
+export type NudgeKind = 'toast' | 'modal' | 'banner';
+
+/**
+ * When a nudge becomes eligible to show. `mount` and `mount-delay` fire as soon
+ * as the relevant route is mounted; `event` waits for one or more `window`
+ * CustomEvents (with optional per-event count thresholds, e.g. show after the
+ * second tab change).
+ */
+export interface NudgeTriggerEvent {
+ /** Event name (CustomEvent or DOM event). */
+ name: string;
+ /** How many times the event must fire before the nudge becomes eligible. */
+ threshold?: number;
+ /** Where to listen — `window` for app-level CustomEvents, `document` for DOM events like `copy`. */
+ target?: 'window' | 'document';
+ /**
+ * Only count an event if its `target` element (or any ancestor) matches this
+ * CSS selector. Useful for DOM events where you want to scope to a specific
+ * affordance (e.g. copy events on chart tooltips only).
+ */
+ selector?: string;
+}
+
+export type NudgeTrigger =
+ | { kind: 'mount' }
+ | { kind: 'mount-delay'; delayMs: number }
+ | {
+ kind: 'event';
+ events: NudgeTriggerEvent[];
+ /** Optional delay applied after the threshold is met before showing. */
+ afterDelayMs?: number;
+ };
+
+/**
+ * How to remember a "this user has dismissed it" decision.
+ *
+ * - `session`: sessionStorage — re-shows next browser session.
+ * - `forever`: localStorage flag — never shows again on this browser.
+ * - `cooldown`: localStorage timestamp — re-shows after `durationMs` elapses.
+ */
+export type NudgePersistence =
+ | { kind: 'session' }
+ | { kind: 'forever' }
+ | { kind: 'cooldown'; durationMs: number };
+
+/** Optional time window when the nudge is allowed to show. */
+export interface NudgeSchedule {
+ /** ISO 8601 timestamp — only show on/after this date. */
+ showAfter?: string;
+ /** ISO 8601 timestamp — stop showing after this date. */
+ hideAfter?: string;
+}
+
+/** Context passed to render callbacks and action handlers. */
+export interface NudgeContext {
+ id: string;
+ /** Custom-event detail object for event triggers, otherwise undefined. */
+ triggerDetail: unknown;
+ /** Hide the nudge and persist the dismissal per the registered policy. */
+ dismiss: () => void;
+}
+
+export interface NudgeAction {
+ label: string;
+ icon?: ReactNode;
+ /** External URL or in-app path. Mutually exclusive with `onClick`. */
+ href?: string;
+ /** Open `href` in a new tab. */
+ target?: '_blank';
+ /** Use Next.js client-side navigation for in-app paths. */
+ inApp?: boolean;
+ /** Click handler for the primary action. */
+ onClick?: (ctx: NudgeContext) => void;
+ /** If true, do not auto-dismiss after the action runs. Default: dismiss. */
+ keepOpenAfterAction?: boolean;
+}
+
+export interface NudgeContent {
+ icon: ReactNode;
+ title: string;
+ description: string;
+ /** Primary CTA. Banners require this; toasts/modals may omit it. */
+ primaryAction?: NudgeAction;
+ /** Optional badge label rendered next to the title (e.g. "New"). */
+ badge?: string;
+}
+
+export interface NudgeEntry {
+ /** Stable id — used for analytics props and dismissal storage keys. */
+ id: string;
+ kind: NudgeKind;
+ trigger: NudgeTrigger;
+ persistence: NudgePersistence;
+ /**
+ * When the dismissal record is written.
+ *
+ * - `'show'`: the moment the nudge becomes visible. Refreshing mid-display
+ * will not re-show it. This is the default for toasts so they appear at
+ * most once per session/cooldown.
+ * - `'dismiss'`: only when the user actively dismisses or invokes the
+ * primary action. The default for modals and banners — they're meant to
+ * persist until the user resolves them.
+ */
+ persistOn?: 'show' | 'dismiss';
+ /**
+ * Routes (matched against `pathname`) where this nudge is allowed to fire.
+ * If omitted, allowed everywhere.
+ */
+ routes?: RegExp[];
+ schedule?: NudgeSchedule;
+ /** Higher number wins when multiple nudges of the same kind want a slot. */
+ priority?: number;
+ /** Extra runtime check evaluated alongside persistence. */
+ condition?: () => boolean;
+ /**
+ * Window CustomEvent names that should hide the nudge immediately *without*
+ * persisting a dismissal (the underlying state has already changed — e.g. the
+ * star-modal hides when the user actually stars the repo).
+ */
+ externalDismissEvents?: string[];
+ /**
+ * Render callback. Re-runs whenever `triggerDetail` changes so a closure
+ * captured here can read fresh detail (e.g. the gradient-label nudge picks up
+ * `detail.enableGradient` from the most recent event).
+ */
+ render: (ctx: NudgeContext) => NudgeContent;
+}
diff --git a/packages/app/src/lib/star-storage.ts b/packages/app/src/lib/star-storage.ts
index eaf1872c..45e8ec81 100644
--- a/packages/app/src/lib/star-storage.ts
+++ b/packages/app/src/lib/star-storage.ts
@@ -1,7 +1,11 @@
+/**
+ * Persistent state for "user has starred the repo." Read by the header/footer
+ * GitHub-star buttons and by nudges that should disappear once the user has
+ * starred. The nudge framework owns its own *dismissal* storage — this module
+ * only tracks the user's actual starring action.
+ */
export const STARRED_KEY = 'inferencex-starred';
export const STARRED_EVENT = 'inferencex:starred';
-export const DISMISS_KEY = 'inferencex-star-modal-dismissed';
-export const DISMISS_DURATION_MS = 7 * 24 * 60 * 60 * 1000; // 1 week
export function saveStarred(): void {
try {
@@ -11,11 +15,3 @@ export function saveStarred(): void {
}
window.dispatchEvent(new Event(STARRED_EVENT));
}
-
-export function saveDismissTimestamp(): void {
- try {
- localStorage.setItem(DISMISS_KEY, String(Date.now()));
- } catch {
- // localStorage unavailable
- }
-}