Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(app): proactive feedback card, time and usage gated (#2842)

sarah878f8f741be3
diff --git a/.changeset/proactive-feedback-card.md b/.changeset/proactive-feedback-card.md
new file mode 100644
index 000000000..0eb120359
--- /dev/null
+++ b/.changeset/proactive-feedback-card.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+Ask for feedback once, when it is actually worth asking. A card now appears in the sidebar footer for people who have been using OpenKnowledge for at least two weeks and have built up at least ten documents, inviting a quick good / not great rating with room for a message. It waits its turn behind the first-run checklist and any what's-new notice, and it starts collapsed to just the question, expanding only once you pick a rating. Answer it or close it and it never comes back on that device. Documents that OpenKnowledge manages for you, like installed skills and folder templates, do not count toward the ten.
diff --git a/packages/app/src/components/FeedbackCard.dom.test.tsx b/packages/app/src/components/FeedbackCard.dom.test.tsx
new file mode 100644
index 000000000..f5cb482df
--- /dev/null
+++ b/packages/app/src/components/FeedbackCard.dom.test.tsx
@@ -0,0 +1,115 @@
+/**
+ * Behavioral tests for `FeedbackCard` — the sidebar-footer feedback card.
+ *
+ * Renders the real `FeedbackForm` in its compact variant, so these pin the
+ * seam the card depends on: the heading and close affordance the card supplies,
+ * and the rating controls the user actually reaches.
+ */
+
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { TooltipProvider } from '@/components/ui/tooltip';
+import { FeedbackCard, FeedbackCardMount } from './FeedbackCard';
+
+function renderCard(onClose = vi.fn()) {
+ render(
+ <TooltipProvider>
+ <FeedbackCard onClose={onClose} />
+ </TooltipProvider>,
+ );
+ return { onClose };
+}
+
+describe('FeedbackCard', () => {
+ afterEach(() => cleanup());
+
+ test('renders the prompt and both rating choices inline (no dialog)', () => {
+ renderCard();
+
+ expect(screen.getByText("Tell us how it's going")).toBeTruthy();
+ // The dialog keeps its own title; the card must not borrow it.
+ expect(screen.queryByText('How do you like OpenKnowledge?')).toBeNull();
+ // Single-select ToggleGroup — the rating choices are radios, not buttons.
+ expect(screen.getByRole('radio', { name: 'Good' })).toBeTruthy();
+ expect(screen.getByRole('radio', { name: 'Not great' })).toBeTruthy();
+ // The card is inline in the footer — nothing modal about it.
+ expect(screen.queryByRole('dialog')).toBeNull();
+ });
+
+ test('exposes a labelled landmark so the footer card is navigable', () => {
+ renderCard();
+ expect(screen.getByRole('region', { name: 'Share feedback' })).toBeTruthy();
+ });
+
+ test('mounts without a PageListProvider and renders nothing', () => {
+ // The mount is a leaf of the sidebar footer. Requiring the page list would
+ // make FileSidebar itself demand a provider it otherwise has no need for,
+ // which is what broke every FileSidebar.*.dom.test.tsx. No provider means
+ // no document count, which must fail closed rather than throw.
+ expect(() => render(<FeedbackCardMount />)).not.toThrow();
+ expect(screen.queryByRole('region', { name: 'Share feedback' })).toBeNull();
+ });
+
+ test('the close button reports the dismissal', async () => {
+ const user = userEvent.setup();
+ const { onClose } = renderCard();
+
+ await user.click(screen.getByRole('button', { name: 'Close' }));
+
+ expect(onClose).toHaveBeenCalledTimes(1);
+ });
+
+ test('shows only the rating until one is picked', () => {
+ renderCard();
+
+ // The rating is required by the schema, so a Send the user cannot succeed
+ // with must not be on screen before they answer it.
+ expect(screen.queryByRole('button', { name: 'Send' })).toBeNull();
+ expect(screen.queryByPlaceholderText('Tell us more (optional)')).toBeNull();
+ expect(screen.queryByRole('checkbox', { name: 'Share your email for followups' })).toBeNull();
+ });
+
+ test('reveals the rest of the form once a rating is picked', async () => {
+ const user = userEvent.setup();
+ renderCard();
+
+ await user.click(screen.getByRole('radio', { name: 'Good' }));
+
+ expect(screen.getByRole('button', { name: 'Send' })).toBeTruthy();
+ expect(screen.getByPlaceholderText('Tell us more (optional)')).toBeTruthy();
+ expect(screen.getByRole('checkbox', { name: 'Share your email for followups' })).toBeTruthy();
+ });
+
+ test('reason pills stay hidden until the negative rating is chosen', async () => {
+ const user = userEvent.setup();
+ renderCard();
+
+ expect(screen.queryByText('What got in the way?')).toBeNull();
+
+ await user.click(screen.getByRole('radio', { name: 'Not great' }));
+
+ expect(screen.getByText('What got in the way?')).toBeTruthy();
+ expect(screen.getByText('Too slow')).toBeTruthy();
+ });
+
+ test('switching back to Good drops the reason selection', async () => {
+ // The form clears `reasons` on the switch so hidden pills can't leak into
+ // the submitted payload. Without this test, removing that clear would
+ // silently corrupt feedback attribution: reasons sent, pills not shown.
+ const user = userEvent.setup();
+ renderCard();
+
+ await user.click(screen.getByRole('radio', { name: 'Not great' }));
+ await user.click(screen.getByRole('button', { name: 'Too slow' }));
+ expect(screen.getByRole('button', { name: 'Too slow' }).dataset.state).toBe('on');
+
+ await user.click(screen.getByRole('radio', { name: 'Good' }));
+ expect(screen.queryByText('What got in the way?')).toBeNull();
+
+ // Re-opening the pills must show a clean slate, which is observable proof
+ // the selection was dropped rather than merely hidden.
+ await user.click(screen.getByRole('radio', { name: 'Not great' }));
+ expect(screen.getByRole('button', { name: 'Too slow' }).dataset.state).toBe('off');
+ });
+});
diff --git a/packages/app/src/components/FeedbackCard.tsx b/packages/app/src/components/FeedbackCard.tsx
new file mode 100644
index 000000000..f6e59c705
--- /dev/null
+++ b/packages/app/src/components/FeedbackCard.tsx
@@ -0,0 +1,92 @@
+/**
+ * FeedbackCard — the proactive "How do you like OpenKnowledge?" card in the
+ * sidebar footer, shown once to engaged users past the honeymoon window (see
+ * `feedback-nudge-store`). Mirrors `SubscribeCard`: same footer slot, same
+ * bordered-card shell, form inlined rather than behind a dialog.
+ *
+ * Lifecycle:
+ * - Shown for exactly one session (see `use-feedback-nudge`), then never
+ * again on that device, whether the user engaged with it or ignored it.
+ * - The form's ✕ closes it AND stops the nudge for good (`dismiss()`).
+ * - A confirmed submit does the same — `FeedbackForm` raises its own
+ * "Thanks for the feedback!" toast, so the card just retires.
+ *
+ * `FeedbackCardMount` self-gates, so `FileSidebar` mounts it unconditionally.
+ */
+
+import { useLingui } from '@lingui/react/macro';
+import { useSyncExternalStore } from 'react';
+import { useOptionalPageList } from '@/components/PageListContext';
+import { FEEDBACK_NUDGE_SOURCE, useFeedbackNudgeVisible } from '@/hooks/use-feedback-nudge';
+import { feedbackNudgeStore } from '@/lib/feedback-nudge-store';
+import { onboardingCardStore } from '@/lib/onboarding-card-store';
+import { getNoticesSnapshot, subscribeToNotices } from '@/lib/update-notices-store';
+import { FeedbackForm } from './FeedbackForm';
+
+export function FeedbackCard({ onClose }: { onClose: () => void }) {
+ const { t } = useLingui();
+ return (
+ <section
+ // The heading is a <p> inside FeedbackForm, not an <h*>, so the landmark
+ // carries its own label rather than aria-labelledby.
+ aria-label={t`Share feedback`}
+ className="mx-1 mb-1 overflow-hidden rounded-lg border bg-card text-card-foreground"
+ >
+ <div className="px-3 py-2.5">
+ <FeedbackForm
+ compact
+ source={FEEDBACK_NUDGE_SOURCE}
+ // Deliberately not the dialog's "How do you like OpenKnowledge?".
+ // That title suits a surface the user opened on purpose; this card
+ // arrives uninvited, sits beside "Stay in the loop" and "Get set up"
+ // (both statements), and must not restate the Good / Not great
+ // toggle directly beneath it.
+ title={t`Tell us how it's going`}
+ onDismiss={onClose}
+ onSuccess={onClose}
+ />
+ </div>
+ </section>
+ );
+}
+
+export function FeedbackCardMount() {
+ // Optional on purpose. This card is a leaf of the sidebar footer, and the
+ // required hook would make `FileSidebar` itself demand a `PageListProvider`
+ // it otherwise has no need for. Absent provider means the document count is
+ // unknown, which fails closed: no count, no nudge. That matches how the
+ // onboarding card treats an unconfirmable probe — suppress rather than
+ // ambush someone we cannot vouch for.
+ const pageList = useOptionalPageList();
+ const onboarding = useSyncExternalStore(
+ onboardingCardStore.subscribe,
+ onboardingCardStore.getSnapshot,
+ onboardingCardStore.getSnapshot,
+ );
+ const notices = useSyncExternalStore(subscribeToNotices, getNoticesSnapshot, getNoticesSnapshot);
+
+ // The first-run card is showing, or a what's-new notice is up (which is where
+ // the subscribe prompt rides). Both share this footer — don't stack a third ask.
+ //
+ // These are snapshot reads rather than the surfaces' own hooks on purpose:
+ // `useOnboardingCardVisible` would run a second fresh-project probe (an IPC
+ // round-trip plus an `/api/documents` fetch) for an answer already latched in
+ // the store by the time a two-week-old install is being evaluated.
+ const blocked =
+ (onboarding.initialized && !onboarding.dismissed && !onboarding.completed) ||
+ notices.length > 0;
+
+ // Pass the raw page set, not a count: the hook counts at most once per
+ // session, on the render that makes the launch decision, so the O(pages) walk
+ // never runs on every sidebar render. `ready` gates that decision on the cold
+ // load finishing, so it reads the real count rather than the empty set the
+ // provider starts with.
+ const visible = useFeedbackNudgeVisible({
+ pages: pageList?.pages ?? null,
+ ready: pageList != null && !pageList.loading,
+ blocked,
+ });
+
+ if (!visible) return null;
+ return <FeedbackCard onClose={() => feedbackNudgeStore.dismiss()} />;
+}
diff --git a/packages/app/src/components/FeedbackForm.tsx b/packages/app/src/components/FeedbackForm.tsx
index 55a757cfc..f34d25ef1 100644
--- a/packages/app/src/components/FeedbackForm.tsx
+++ b/packages/app/src/components/FeedbackForm.tsx
@@ -3,7 +3,7 @@ import type { MessageDescriptor } from '@lingui/core';
import { msg } from '@lingui/core/macro';
import { Trans, useLingui } from '@lingui/react/macro';
import { Paperclip, ThumbsDown, ThumbsUp, X } from 'lucide-react';
-import { type FC, useEffect, useRef, useState } from 'react';
+import { type FC, type ReactNode, useEffect, useRef, useState } from 'react';
import { useForm, useWatch } from 'react-hook-form';
import { toast } from 'sonner';
import { z } from 'zod';
@@ -85,11 +85,27 @@ const AttachmentImagePreview: FC<{ file: File }> = ({ file }) => {
export const FeedbackForm = ({
onSuccess,
source = 'resources_menu',
+ compact,
+ title,
+ onDismiss,
+ className,
}: {
/** Called after a confirmed submit (e.g. to close the dialog). */
onSuccess?: () => void;
/** Which in-app surface opened the form; sent for analytics attribution. */
source?: string;
+ /**
+ * Tighten spacing and type for narrow surfaces — the sidebar footer card sits
+ * at `--sidebar-width` (~256px), where the dialog's rhythm overflows. Mirrors
+ * `SubscribeForm`'s `compactSubmit` seam: additive and default-off, so the
+ * dialog rendering is byte-identical to before.
+ */
+ compact?: boolean;
+ /** Heading rendered above the form. Omitted surfaces supply their own (the dialog uses DialogTitle). */
+ title?: ReactNode;
+ /** When provided, renders a close (X) button beside the title. */
+ onDismiss?: () => void;
+ className?: string;
}) => {
const { t } = useLingui();
const fileInputRef = useRef<HTMLInputElement>(null);
@@ -133,6 +149,16 @@ export const FeedbackForm = ({
});
const rating = useWatch({ control: form.control, name: 'rating' });
+
+ /**
+ * Compact surfaces reveal the rest of the form only once a rating is picked.
+ * `rating` is required by the schema, so showing the message box, the email
+ * opt-in, and Send before it is answered offers a control that cannot
+ * succeed — on the sidebar card, which the user never asked for, that dead
+ * end costs more than the reveal does. The dialog is opened deliberately and
+ * has no height pressure, so it stays fully expanded.
+ */
+ const showBeyondRating = !compact || rating != null;
const shareEmail = useWatch({ control: form.control, name: 'shareEmail' });
// Attachments are driven directly off form state (not a FormField) so the
@@ -187,7 +213,27 @@ export const FeedbackForm = ({
return (
<Form {...form}>
- <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-5">
+ <form
+ onSubmit={form.handleSubmit(onSubmit)}
+ className={cn(compact ? 'space-y-3' : 'space-y-5', className)}
+ >
+ {(title || onDismiss) && (
+ <div className="flex items-start justify-between gap-2">
+ {title ? <p className="font-medium text-1sm">{title}</p> : <span />}
+ {onDismiss ? (
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon"
+ onClick={onDismiss}
+ aria-label={t`Close`}
+ className="-mr-1.5 -mt-1 size-7 shrink-0 text-muted-foreground opacity-60"
+ >
+ <X className="size-4" />
+ </Button>
+ ) : null}
+ </div>
+ )}
{/* Rating — single choice, drives whether the reason pills show. */}
<FormField
control={form.control}
@@ -199,6 +245,11 @@ export const FeedbackForm = ({
type="single"
variant="outline"
spacing={2}
+ // The Good/Not great options carry their own labels; the group
+ // itself needs a name so a screen reader announces what the
+ // radios are for. The visible heading is a plain <p>, not a
+ // programmatic label, so this can't be aria-labelledby to it.
+ aria-label={t`Rate your experience`}
value={field.value ?? ''}
onValueChange={(value) => {
if (!value) return;
@@ -211,14 +262,22 @@ export const FeedbackForm = ({
>
<ToggleGroupItem
value="positive"
- className={`h-auto flex-1 justify-center gap-2 py-2 ${selectedStateClassName}`}
+ className={cn(
+ 'h-auto flex-1 justify-center py-2',
+ compact ? 'gap-1.5 text-xs' : 'gap-2',
+ selectedStateClassName,
+ )}
>
<ThumbsUp className="size-4" />
<Trans>Good</Trans>
</ToggleGroupItem>
<ToggleGroupItem
value="negative"
- className={`h-auto flex-1 justify-center gap-2 py-2 ${selectedStateClassName}`}
+ className={cn(
+ 'h-auto flex-1 justify-center py-2',
+ compact ? 'gap-1.5 text-xs' : 'gap-2',
+ selectedStateClassName,
+ )}
>
<ThumbsDown className="size-4" />
<Trans>Not great</Trans>
@@ -229,181 +288,191 @@ export const FeedbackForm = ({
</FormItem>
)}
/>
- <div className="space-y-3">
- {/* Reason pills — only shown when the "Not great" rating is selected. */}
- {rating === 'negative' && (
- <FormField
- control={form.control}
- name="reasons"
- render={({ field }) => (
- <FormItem>
- <FormLabel>
- <Trans>What got in the way?</Trans>
- </FormLabel>
- <FormControl>
- <ToggleGroup
- type="multiple"
- variant="outline"
- spacing={2}
- value={field.value}
- onValueChange={field.onChange}
- className="w-full flex-wrap justify-start"
- >
- {REASONS.map((reason) => (
- <ToggleGroupItem
- key={reason.value}
- value={reason.value}
- className={pillClassName}
+ {showBeyondRating && (
+ <>
+ <div className="space-y-3">
+ {/* Reason pills — only shown when the "Not great" rating is selected. */}
+ {rating === 'negative' && (
+ <FormField
+ control={form.control}
+ name="reasons"
+ render={({ field }) => (
+ <FormItem>
+ <FormLabel>
+ <Trans>What got in the way?</Trans>
+ </FormLabel>
+ <FormControl>
+ <ToggleGroup
+ type="multiple"
+ variant="outline"
+ spacing={2}
+ value={field.value}
+ onValueChange={field.onChange}
+ className="w-full flex-wrap justify-start"
>
- {t(reason.label)}
- </ToggleGroupItem>
- ))}
- </ToggleGroup>
- </FormControl>
- </FormItem>
+ {REASONS.map((reason) => (
+ <ToggleGroupItem
+ key={reason.value}
+ value={reason.value}
+ className={pillClassName}
+ >
+ {t(reason.label)}
+ </ToggleGroupItem>
+ ))}
+ </ToggleGroup>
+ </FormControl>
+ </FormItem>
+ )}
+ />
)}
- />
- )}
- {/* Message with the attach button tucked into its bottom-left corner —
+ {/* Message with the attach button tucked into its bottom-left corner —
a real sibling button positioned over the textarea, not inside it —
and the attachment previews rendered below. */}
- <div className="space-y-2">
- <FormField
- control={form.control}
- name="message"
- render={({ field }) => (
- <FormItem>
- <FormControl>
- <div className="relative">
- <Textarea
- {...field}
- placeholder={t`Tell us more (optional)`}
- className="min-h-20 resize-none pb-9"
- />
- <Tooltip>
- {/* Disabled buttons emit no pointer events, so the tooltip
+ <div className="space-y-2">
+ <FormField
+ control={form.control}
+ name="message"
+ render={({ field }) => (
+ <FormItem>
+ <FormControl>
+ <div className="relative">
+ <Textarea
+ {...field}
+ placeholder={t`Tell us more (optional)`}
+ className={cn('resize-none pb-9', compact ? 'min-h-16' : 'min-h-20')}
+ />
+ <Tooltip>
+ {/* Disabled buttons emit no pointer events, so the tooltip
trigger sits on a wrapping span (shadcn's documented
pattern); the button itself is truly disabled at the cap. */}
- <TooltipTrigger asChild>
- <span
- className={cn(
- 'absolute bottom-1.5 left-1.5 inline-flex',
- atMaxAttachments && 'cursor-not-allowed',
- )}
- >
- <Button
- type="button"
- variant="ghost"
- size="icon"
- disabled={atMaxAttachments}
- onClick={() => fileInputRef.current?.click()}
- className="size-7 text-muted-foreground"
- >
- <Paperclip className="size-4" />
- <span className="sr-only">
- <Trans>Attach images</Trans>
+ <TooltipTrigger asChild>
+ <span
+ className={cn(
+ 'absolute bottom-1.5 left-1.5 inline-flex',
+ atMaxAttachments && 'cursor-not-allowed',
+ )}
+ >
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon"
+ disabled={atMaxAttachments}
+ onClick={() => fileInputRef.current?.click()}
+ className="size-7 text-muted-foreground"
+ >
+ <Paperclip className="size-4" />
+ <span className="sr-only">
+ <Trans>Attach images</Trans>
+ </span>
+ </Button>
</span>
- </Button>
- </span>
- </TooltipTrigger>
- <TooltipContent>
- {atMaxAttachments ? (
- <Trans>Maximum {MAX_ATTACHMENTS} attachments</Trans>
- ) : (
- <Trans>Attach images</Trans>
- )}
- </TooltipContent>
- </Tooltip>
- <Input
- ref={fileInputRef}
- type="file"
- accept={ACCEPTED_IMAGE_TYPES.join(',')}
- multiple
- className="hidden"
- onChange={(e) => {
- setAttachments(mergeAttachments(attachments, e.target.files));
- // Reset so re-picking the same file re-fires onChange.
- e.target.value = '';
- }}
- />
- </div>
- </FormControl>
- </FormItem>
- )}
- />
+ </TooltipTrigger>
+ <TooltipContent>
+ {atMaxAttachments ? (
+ <Trans>Maximum {MAX_ATTACHMENTS} attachments</Trans>
+ ) : (
+ <Trans>Attach images</Trans>
+ )}
+ </TooltipContent>
+ </Tooltip>
+ <Input
+ ref={fileInputRef}
+ type="file"
+ accept={ACCEPTED_IMAGE_TYPES.join(',')}
+ multiple
+ className="hidden"
+ onChange={(e) => {
+ setAttachments(mergeAttachments(attachments, e.target.files));
+ // Reset so re-picking the same file re-fires onChange.
+ e.target.value = '';
+ }}
+ />
+ </div>
+ </FormControl>
+ </FormItem>
+ )}
+ />
- {attachments.length > 0 && (
- <AttachmentGroup>
- {attachments.map((file, index) => (
- <Attachment key={`${file.name}:${file.size}`} size="xs">
- <AttachmentMedia variant="image">
- <AttachmentImagePreview file={file} />
- </AttachmentMedia>
- <AttachmentContent>
- <AttachmentTitle>{file.name}</AttachmentTitle>
- <AttachmentDescription>{formatFileSize(file.size)}</AttachmentDescription>
- </AttachmentContent>
- <AttachmentActions>
- <AttachmentAction
- type="button"
- aria-label={t`Remove ${file.name}`}
- onClick={() => setAttachments(attachments.filter((_, i) => i !== index))}
- >
- <X className="size-3.5" />
- </AttachmentAction>
- </AttachmentActions>
- </Attachment>
- ))}
- </AttachmentGroup>
- )}
+ {attachments.length > 0 && (
+ <AttachmentGroup>
+ {attachments.map((file, index) => (
+ <Attachment key={`${file.name}:${file.size}`} size="xs">
+ <AttachmentMedia variant="image">
+ <AttachmentImagePreview file={file} />
+ </AttachmentMedia>
+ <AttachmentContent>
+ <AttachmentTitle>{file.name}</AttachmentTitle>
+ <AttachmentDescription>{formatFileSize(file.size)}</AttachmentDescription>
+ </AttachmentContent>
+ <AttachmentActions>
+ <AttachmentAction
+ type="button"
+ aria-label={t`Remove ${file.name}`}
+ onClick={() =>
+ setAttachments(attachments.filter((_, i) => i !== index))
+ }
+ >
+ <X className="size-3.5" />
+ </AttachmentAction>
+ </AttachmentActions>
+ </Attachment>
+ ))}
+ </AttachmentGroup>
+ )}
- {attachmentsError?.message && (
- <p className="text-destructive text-sm">{attachmentsError.message}</p>
- )}
- </div>
- </div>
- <div className="space-y-2">
- {/* Email opt-in — the address field only appears once checked. */}
- <FormField
- control={form.control}
- name="shareEmail"
- render={({ field }) => (
- <FormItem className="flex flex-row items-center gap-2 space-y-0">
- <FormControl>
- <Checkbox
- checked={field.value}
- onCheckedChange={(checked) => field.onChange(checked === true)}
- />
- </FormControl>
- <FormLabel className="font-normal">
- <Trans>Share your email for followups</Trans>
- </FormLabel>
- </FormItem>
- )}
- />
+ {attachmentsError?.message && (
+ <p className="text-destructive text-sm">{attachmentsError.message}</p>
+ )}
+ </div>
+ </div>
+ <div className="space-y-2">
+ {/* Email opt-in — the address field only appears once checked. */}
+ <FormField
+ control={form.control}
+ name="shareEmail"
+ render={({ field }) => (
+ <FormItem className="flex flex-row items-center gap-2 space-y-0">
+ <FormControl>
+ <Checkbox
+ checked={field.value}
+ onCheckedChange={(checked) => field.onChange(checked === true)}
+ />
+ </FormControl>
+ <FormLabel className="font-normal">
+ <Trans>Share your email for followups</Trans>
+ </FormLabel>
+ </FormItem>
+ )}
+ />
- {shareEmail && (
- <FormField
- control={form.control}
- name="email"
- render={({ field }) => (
- <FormItem>
- <FormControl>
- <Input {...field} type="email" placeholder={t`[email protected]`} />
- </FormControl>
- <FormMessage />
- </FormItem>
+ {shareEmail && (
+ <FormField
+ control={form.control}
+ name="email"
+ render={({ field }) => (
+ <FormItem>
+ <FormControl>
+ <Input {...field} type="email" placeholder={t`[email protected]`} />
+ </FormControl>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
)}
- />
- )}
- </div>
+ </div>
- <div className="flex justify-end">
- <Button type="submit" disabled={form.formState.isSubmitting}>
- {form.formState.isSubmitting ? <Trans>Sending</Trans> : <Trans>Send</Trans>}
- </Button>
- </div>
+ <div className="flex justify-end">
+ <Button
+ type="submit"
+ size={compact ? 'sm' : 'default'}
+ disabled={form.formState.isSubmitting}
+ >
+ {form.formState.isSubmitting ? <Trans>Sending</Trans> : <Trans>Send</Trans>}
+ </Button>
+ </div>
+ </>
+ )}
</form>
</Form>
);
diff --git a/packages/app/src/components/FeedbackFormDialog.dom.test.tsx b/packages/app/src/components/FeedbackFormDialog.dom.test.tsx
new file mode 100644
index 000000000..ce3e96e21
--- /dev/null
+++ b/packages/app/src/components/FeedbackFormDialog.dom.test.tsx
@@ -0,0 +1,62 @@
+/**
+ * Regression guard for the dialog surface of `FeedbackForm`.
+ *
+ * The sidebar card added a `compact` variant that reveals the form only once a
+ * rating is picked. That gating is deliberately card-only: the dialog is opened
+ * on purpose and has no height pressure, so it stays fully expanded. Nothing
+ * else covers the dialog, so without this a future tweak to the shared form
+ * could collapse it and no test would notice.
+ */
+
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, test } from 'vitest';
+import { TooltipProvider } from '@/components/ui/tooltip';
+import { FeedbackFormDialog } from './FeedbackFormDialog';
+
+function renderDialog(props: Partial<React.ComponentProps<typeof FeedbackFormDialog>> = {}) {
+ render(
+ <TooltipProvider>
+ <FeedbackFormDialog open onOpenChange={() => {}} source="test" {...props} />
+ </TooltipProvider>,
+ );
+}
+
+/**
+ * The dialog body is a `lazy()` boundary, so the first test in the file pays
+ * the dynamic-import cost — more than the 1000 ms `findBy*` default allows.
+ * Later tests hit the module cache and resolve immediately.
+ */
+const findFormBody = () => screen.findByRole('radio', { name: 'Good' }, { timeout: 5000 });
+
+describe('FeedbackFormDialog', () => {
+ afterEach(() => cleanup());
+
+ test('keeps its own title rather than the card heading', async () => {
+ renderDialog();
+ // The body lazy-loads, so wait on it before asserting the shell.
+ expect(await findFormBody()).toBeTruthy();
+
+ expect(screen.getByText('How do you like OpenKnowledge?')).toBeTruthy();
+ expect(screen.queryByText("Tell us how it's going")).toBeNull();
+ });
+
+ test('exposes an onSuccess seam so a caller can record that feedback was given', () => {
+ // The proactive card's cross-suppression rides this prop: HelpPopover
+ // passes `() => feedbackNudgeStore.dismiss()`, so feedback given through
+ // the Resources menu stops the card from asking the same person again.
+ // Without the prop there is nowhere to hang that, which is the gap this
+ // pins shut. The submit path itself needs a live /api/feedback, so this
+ // asserts the seam exists and is optional rather than driving a send.
+ expect(() => renderDialog({ onSuccess: () => {} })).not.toThrow();
+ expect(() => renderDialog()).not.toThrow();
+ });
+
+ test('renders the whole form up front, with no rating picked', async () => {
+ renderDialog();
+ await findFormBody();
+
+ expect(screen.getByRole('button', { name: 'Send' })).toBeTruthy();
+ expect(screen.getByPlaceholderText('Tell us more (optional)')).toBeTruthy();
+ expect(screen.getByRole('checkbox', { name: 'Share your email for followups' })).toBeTruthy();
+ });
+});
diff --git a/packages/app/src/components/FeedbackFormDialog.tsx b/packages/app/src/components/FeedbackFormDialog.tsx
index a059c877a..fea66fc10 100644
--- a/packages/app/src/components/FeedbackFormDialog.tsx
+++ b/packages/app/src/components/FeedbackFormDialog.tsx
@@ -14,11 +14,18 @@ export const FeedbackFormDialog = ({
open,
onOpenChange,
source,
+ onSuccess,
}: {
open: boolean;
onOpenChange: (open: boolean) => void;
/** Which in-app surface opened the form; forwarded for analytics attribution. */
source?: string;
+ /**
+ * Fired after a confirmed submit, in addition to closing the dialog. Lets a
+ * caller record that feedback was given from this surface — see the
+ * proactive card's suppression in HelpPopover.
+ */
+ onSuccess?: () => void;
}) => {
return (
<Dialog open={open} onOpenChange={onOpenChange}>
@@ -29,7 +36,13 @@ export const FeedbackFormDialog = ({
</DialogTitle>
</DialogHeader>
<Suspense fallback={null}>
- <FeedbackForm source={source} onSuccess={() => onOpenChange(false)} />
+ <FeedbackForm
+ source={source}
+ onSuccess={() => {
+ onOpenChange(false);
+ onSuccess?.();
+ }}
+ />
</Suspense>
</DialogContent>
</Dialog>
diff --git a/packages/app/src/components/FileSidebar.tsx b/packages/app/src/components/FileSidebar.tsx
index 83a5160c4..dbe1d4671 100644
--- a/packages/app/src/components/FileSidebar.tsx
+++ b/packages/app/src/components/FileSidebar.tsx
@@ -23,6 +23,7 @@ import {
import { ErrorBoundary } from 'react-error-boundary';
import { toast } from 'sonner';
import { ConflictsSection } from '@/components/ConflictsSection';
+import { FeedbackCardMount } from '@/components/FeedbackCard';
import { FileTree, type FileTreeHandle } from '@/components/FileTree';
import { defaultInitialDir, hasOkPathSegment } from '@/components/file-tree-utils';
import { OpenInAgentEmptySpaceSubmenu } from '@/components/handoff/OpenInAgentEmptySpaceSubmenu';
@@ -1123,6 +1124,10 @@ function FileSidebarInner({ onOpenSearch }: FileSidebarProps) {
<SidebarFooter className="px-0">
<OnboardingCardMount />
<UpdateNotices />
+ {/* Self-gates on device-local state (two weeks since first boot,
+ enough documents) and on the two surfaces above, so it never
+ stacks a third ask into this footer. */}
+ <FeedbackCardMount />
{typeof window !== 'undefined' && window.okDesktop ? (
<SidebarMenu>
<SidebarMenuItem>
diff --git a/packages/app/src/components/HelpPopover.tsx b/packages/app/src/components/HelpPopover.tsx
index d86dfe279..189de0528 100644
--- a/packages/app/src/components/HelpPopover.tsx
+++ b/packages/app/src/components/HelpPopover.tsx
@@ -11,6 +11,7 @@ import { Button } from '@/components/ui/button';
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
import { dispatchExternalLinkClick } from '@/lib/external-link';
+import { feedbackNudgeStore } from '@/lib/feedback-nudge-store';
import { DISCORD_INVITE_URL, GITHUB_REPO_URL, X_PROFILE_URL } from '@/lib/social-links';
import { subscribeCardStore } from '@/lib/subscribe-card-store';
import { cn } from '@/lib/utils';
@@ -275,7 +276,14 @@ export const HelpPopover: FC = () => {
select. Report-a-bug is desktop-only — gated on the same bridge as
its trigger row. */}
{hasDesktopBridge && <ReportBugDialog open={reportBugOpen} onOpenChange={setReportBugOpen} />}
- <FeedbackFormDialog open={feedbackOpen} onOpenChange={setFeedbackOpen} />
+ <FeedbackFormDialog
+ open={feedbackOpen}
+ onOpenChange={setFeedbackOpen}
+ // Feedback given here also satisfies the proactive card's suppression
+ // flag — one round of feedback, from any surface, stops the nudge.
+ // Same contract as the subscribe card above.
+ onSuccess={() => feedbackNudgeStore.dismiss()}
+ />
</>
);
};
diff --git a/packages/app/src/hooks/use-feedback-nudge.dom.test.tsx b/packages/app/src/hooks/use-feedback-nudge.dom.test.tsx
new file mode 100644
index 000000000..3bb58ada9
--- /dev/null
+++ b/packages/app/src/hooks/use-feedback-nudge.dom.test.tsx
@@ -0,0 +1,278 @@
+/**
+ * Behavioral tests for `useFeedbackNudgeVisible` — the visibility latch behind
+ * the sidebar-footer feedback card.
+ *
+ * Mounts the hook through a trivial harness over a real store backed by
+ * in-memory storage, so both halves of the contract are pinned: when the card
+ * takes its one session, and that it never returns once shown or answered.
+ *
+ * Session scope matters here: a `FeedbackNudgeSession` object stands in for
+ * one JS context (one window, boot to reload). The same session across
+ * mounts = a React remount; a fresh session over the same storage = an app
+ * relaunch. Tests inject fresh sessions for isolation from the module default.
+ */
+
+import { act, cleanup, render } from '@testing-library/react';
+import { afterEach, describe, expect, test } from 'vitest';
+import {
+ createFeedbackNudgeStore,
+ FEEDBACK_NUDGE_MIN_AGE_MS,
+ FEEDBACK_NUDGE_MIN_DOCS,
+ type FeedbackNudgeStorage,
+ type FeedbackNudgeStore,
+} from '@/lib/feedback-nudge-store';
+import {
+ createFeedbackNudgeSession,
+ type FeedbackNudgeSession,
+ useFeedbackNudgeVisible,
+} from './use-feedback-nudge';
+
+const NOW = 1_800_000_000_000;
+/** `firstSeenAt` old enough that the two-week gate has run at `NOW`. */
+const RIPE = NOW - FEEDBACK_NUDGE_MIN_AGE_MS;
+
+/** A page set of `n` ordinary (non-`.ok`) documents. */
+function docs(n: number): Set<string> {
+ return new Set(Array.from({ length: n }, (_, i) => `doc-${i}`));
+}
+
+function persistentStorage(): FeedbackNudgeStorage {
+ const data = new Map<string, string>();
+ return {
+ getItem: (key) => data.get(key) ?? null,
+ setItem: (key, value) => {
+ data.set(key, value);
+ },
+ };
+}
+
+/** One JS context's worth of session state. */
+function freshSession(): FeedbackNudgeSession {
+ return createFeedbackNudgeSession();
+}
+
+/**
+ * A store whose two-week clock has already run — an install that predates this
+ * session by a fortnight — over storage that survives a remount.
+ */
+function ripeStore(storage: FeedbackNudgeStorage = persistentStorage()): FeedbackNudgeStore {
+ const store = createFeedbackNudgeStore(storage);
+ store.recordFirstSeen(RIPE);
+ return store;
+}
+
+function Harness({
+ store,
+ session,
+ pages = docs(FEEDBACK_NUDGE_MIN_DOCS),
+ ready = true,
+ blocked = false,
+}: {
+ store: FeedbackNudgeStore;
+ session: FeedbackNudgeSession;
+ pages?: Set<string> | null;
+ ready?: boolean;
+ blocked?: boolean;
+}) {
+ const visible = useFeedbackNudgeVisible({
+ pages,
+ ready,
+ blocked,
+ store,
+ session,
+ now: () => NOW,
+ });
+ return <div data-testid="visible">{String(visible)}</div>;
+}
+
+const shown = (view: { getByTestId: (id: string) => HTMLElement }) =>
+ view.getByTestId('visible').textContent;
+
+describe('useFeedbackNudgeVisible', () => {
+ afterEach(() => cleanup());
+
+ test('shows when both gates pass at launch, and latches shownAt', () => {
+ const store = ripeStore();
+ const view = render(<Harness store={store} session={freshSession()} />);
+
+ expect(shown(view)).toBe('true');
+ expect(store.getSnapshot().shownAt).toBe(NOW);
+ });
+
+ test('stays visible after shownAt latches', () => {
+ // Stamping `shownAt` this session must not fold back into the prior-session
+ // guard and hide the card it just decided to show.
+ const store = ripeStore();
+ const session = freshSession();
+ const view = render(<Harness store={store} session={session} />);
+ expect(shown(view)).toBe('true');
+
+ view.rerender(
+ <Harness store={store} session={session} pages={docs(FEEDBACK_NUDGE_MIN_DOCS + 3)} />,
+ );
+ expect(shown(view)).toBe('true');
+ });
+
+ test('a showing card SURVIVES a React remount within the same session', () => {
+ // The shadcn Sidebar tree remounts transparently (theme toggles, width
+ // changes — see update-notices-store's doc block, which exists for this
+ // exact reason). The remounted hook must re-adopt the session's show
+ // rather than read its own `shownAt` as a prior session's and vanish.
+ const store = ripeStore();
+ const session = freshSession(); // same JS context throughout
+ const first = render(<Harness store={store} session={session} />);
+ expect(shown(first)).toBe('true');
+
+ first.unmount();
+ const second = render(<Harness store={store} session={session} />);
+ expect(shown(second)).toBe('true'); // still up — remount is not a relaunch
+ });
+
+ test('hides as soon as the user answers, and never returns', () => {
+ const store = ripeStore();
+ const session = freshSession();
+ const view = render(<Harness store={store} session={session} />);
+ expect(shown(view)).toBe('true');
+
+ act(() => store.dismiss());
+ expect(shown(view)).toBe('false');
+
+ view.unmount();
+ // Same session (remount) — dismissed stays dismissed.
+ const remounted = render(<Harness store={store} session={session} />);
+ expect(shown(remounted)).toBe('false');
+ });
+
+ test('shown once, ever: a fresh session after being shown does not re-show', () => {
+ // The persistence-backed store carries `shownAt` into the next launch. This
+ // is the "ignored, quit, relaunched" case — it must NOT come back. A
+ // relaunch = new store instance AND new session object over the same disk.
+ const storage = persistentStorage();
+ const first = ripeStore(storage);
+ expect(shown(render(<Harness store={first} session={freshSession()} />))).toBe('true');
+ cleanup();
+
+ const relaunchedStore = createFeedbackNudgeStore(storage);
+ const relaunched = render(<Harness store={relaunchedStore} session={freshSession()} />);
+ expect(shown(relaunched)).toBe('false');
+ });
+
+ test('does not show before the two-week clock has run', () => {
+ const store = createFeedbackNudgeStore(persistentStorage());
+ store.recordFirstSeen(RIPE + 1);
+ const view = render(<Harness store={store} session={freshSession()} />);
+
+ expect(shown(view)).toBe('false');
+ expect(store.getSnapshot().shownAt).toBeNull();
+ });
+
+ test('does not show below the document threshold', () => {
+ const store = ripeStore();
+ const view = render(
+ <Harness store={store} session={freshSession()} pages={docs(FEEDBACK_NUDGE_MIN_DOCS - 1)} />,
+ );
+
+ expect(shown(view)).toBe('false');
+ expect(store.getSnapshot().shownAt).toBeNull();
+ });
+
+ test('waits for the page list to load before deciding', () => {
+ // At launch the provider starts with an empty set and loading=true. The
+ // card must not read that empty set as "0 docs, ineligible" and latch.
+ const store = ripeStore();
+ const session = freshSession();
+ const view = render(
+ <Harness store={store} session={session} pages={new Set()} ready={false} />,
+ );
+ expect(shown(view)).toBe('false');
+ expect(store.getSnapshot().shownAt).toBeNull();
+
+ view.rerender(
+ <Harness store={store} session={session} pages={docs(FEEDBACK_NUDGE_MIN_DOCS)} ready />,
+ );
+ expect(shown(view)).toBe('true');
+ });
+
+ test('null page set fails closed', () => {
+ const store = ripeStore();
+ const view = render(<Harness store={store} session={freshSession()} pages={null} />);
+ expect(shown(view)).toBe('false');
+ expect(store.getSnapshot().shownAt).toBeNull();
+ });
+
+ test('evaluated at launch, not on the fly: crossing the threshold mid-session does not fire', () => {
+ // Below threshold when the launch decision is made. A later live edit that
+ // pushes the count over ten must NOT surface the card this session — that
+ // is the "interrupt mid-writing" case we deliberately avoid.
+ const store = ripeStore();
+ const session = freshSession();
+ const view = render(<Harness store={store} session={session} pages={docs(4)} />);
+ expect(shown(view)).toBe('false');
+
+ view.rerender(<Harness store={store} session={session} pages={docs(11)} />);
+ expect(shown(view)).toBe('false');
+ expect(store.getSnapshot().shownAt).toBeNull();
+ });
+
+ test('a below-threshold count at the ready-flip latches the decision for the session', () => {
+ // The launch decision latches when the page list loads, BEFORE the
+ // eligibility check — so a load that settles under the threshold spends the
+ // session's one evaluation. Guards against moving the latch inside the
+ // eligible branch, which would let a later mid-session doc-count climb pop
+ // the card in. Distinct from the test above: there the count is already
+ // loaded; here it is the ready-flip itself that lands below threshold.
+ const store = ripeStore();
+ const session = freshSession();
+ const view = render(<Harness store={store} session={session} pages={docs(4)} ready={false} />);
+ expect(shown(view)).toBe('false');
+
+ view.rerender(<Harness store={store} session={session} pages={docs(4)} ready />);
+ expect(shown(view)).toBe('false');
+ expect(store.getSnapshot().shownAt).toBeNull();
+
+ view.rerender(
+ <Harness store={store} session={session} pages={docs(FEEDBACK_NUDGE_MIN_DOCS + 5)} ready />,
+ );
+ expect(shown(view)).toBe('false');
+ expect(store.getSnapshot().shownAt).toBeNull();
+ });
+
+ test('stamps firstSeenAt on a first-ever mount and stays hidden that session', () => {
+ const store = createFeedbackNudgeStore(persistentStorage());
+ const view = render(<Harness store={store} session={freshSession()} pages={docs(400)} />);
+
+ expect(store.getSnapshot().firstSeenAt).toBe(NOW);
+ expect(shown(view)).toBe('false');
+ });
+
+ test('blocked at launch defers to the next launch, not to later this session', () => {
+ // Another footer card owns the space at launch. Even when it clears in the
+ // same session, the feedback card must NOT pop in mid-work — it waits for
+ // the next launch.
+ const storage = persistentStorage();
+ const store = ripeStore(storage);
+ const session = freshSession();
+ const view = render(<Harness store={store} session={session} blocked />);
+ expect(shown(view)).toBe('false');
+ expect(store.getSnapshot().shownAt).toBeNull();
+
+ view.rerender(<Harness store={store} session={session} blocked={false} />);
+ expect(shown(view)).toBe('false'); // still hidden this session
+
+ // Next launch (fresh store + fresh session, same storage, no blocker).
+ cleanup();
+ const relaunchedStore = createFeedbackNudgeStore(storage);
+ relaunchedStore.recordFirstSeen(RIPE);
+ expect(shown(render(<Harness store={relaunchedStore} session={freshSession()} />))).toBe(
+ 'true',
+ );
+ });
+
+ test('a store that already recorded a show does not re-show', () => {
+ const store = ripeStore();
+ store.recordShown(NOW - 1);
+ const view = render(<Harness store={store} session={freshSession()} pages={docs(400)} />);
+
+ expect(shown(view)).toBe('false');
+ });
+});
diff --git a/packages/app/src/hooks/use-feedback-nudge.ts b/packages/app/src/hooks/use-feedback-nudge.ts
new file mode 100644
index 000000000..4f78444e9
--- /dev/null
+++ b/packages/app/src/hooks/use-feedback-nudge.ts
@@ -0,0 +1,161 @@
+/**
+ * Visibility predicate for the proactive feedback card in the sidebar footer.
+ *
+ * The card is for engaged users past the honeymoon window: two weeks since the
+ * first boot we can observe, and enough documents in the workspace. It gets
+ * exactly one session on screen, on that device, and never returns — whether
+ * the user answers it or ignores it.
+ *
+ * Two deliberate timing choices, both grounded in feedback-prompt research
+ * (NN/g "Task, then ask"; Apple/Firebase show-once precedents):
+ *
+ * - **Evaluated at launch, not on the fly.** Eligibility is decided once per
+ * session, when the workspace's document set has loaded — not the instant a
+ * live edit pushes the count across ten. Creating the tenth document is the
+ * start of a work chunk, the worst moment to surface a prompt; the card is
+ * simply present when the user next arrives instead of materializing mid-
+ * keystroke. The session's `latchEvaluated` call latches that one decision.
+ * - **Shown once, ever.** A prior session's `shownAt` suppresses the card for
+ * good. A fresh JS context starts with `session.isShown() === false`, and
+ * the eligibility predicate's `shownAt == null` clause rejects on a
+ * persisted show, so recording the show this session doesn't fold back
+ * into the guard.
+ *
+ * Gating inputs are parameters, not reads: `pages` and `ready` come from the
+ * page list and `blocked` from the other footer nudges, so the hook stays
+ * mountable in a DOM test without the page-list provider or the desktop bridge.
+ *
+ * Session state lives at MODULE scope, not in the component. The shadcn
+ * Sidebar tree this card mounts under "remounts transparently across theme
+ * toggles, sidebar width changes, and other parent-triggered re-mounts we
+ * don't control" (see `update-notices-store`, which exists for the same
+ * reason, and why the onboarding/subscribe cards derive visibility purely
+ * from their stores). Per-mount refs would make a remount read this
+ * session's just-recorded `shownAt` as "shown in a prior session" and
+ * permanently hide a card the user was looking at.
+ */
+
+import { useEffect, useState, useSyncExternalStore } from 'react';
+import {
+ countUserDocuments,
+ type FeedbackNudgeStore,
+ feedbackNudgeStore,
+ isFeedbackNudgeEligible,
+} from '@/lib/feedback-nudge-store';
+
+/** Forwarded to the feedback form for analytics attribution. */
+export const FEEDBACK_NUDGE_SOURCE = 'proactive_card';
+
+/**
+ * One app session's nudge decisions. A JS context (one window, boot to
+ * reload/quit) IS the session, so module scope survives React remounts and
+ * resets exactly when a session ends. Injectable so tests get isolation.
+ *
+ * Closure-backed methods rather than mutable fields: the React Compiler
+ * rejects direct property assignment on values reachable from a hook
+ * ("This value cannot be modified"), but latching through a method call is
+ * fine — the same shape as the store's `recordShown`.
+ */
+export interface FeedbackNudgeSession {
+ /** The single launch-time eligibility decision has been made. */
+ isEvaluated(): boolean;
+ /** The card took its session on screen in THIS JS context. */
+ isShown(): boolean;
+ /** Latch the launch decision (idempotent). */
+ latchEvaluated(): void;
+ /** Latch that the card is up this session (idempotent). */
+ latchShown(): void;
+}
+
+export function createFeedbackNudgeSession(): FeedbackNudgeSession {
+ let evaluated = false;
+ let shown = false;
+ return {
+ isEvaluated: () => evaluated,
+ isShown: () => shown,
+ latchEvaluated: () => {
+ evaluated = true;
+ },
+ latchShown: () => {
+ shown = true;
+ },
+ };
+}
+
+const appSession = createFeedbackNudgeSession();
+
+export interface UseFeedbackNudgeOptions {
+ /**
+ * The workspace's document set, or null when unknown (no page-list provider).
+ * Null fails closed: no set, no count, no card. `countUserDocuments` runs at
+ * most once per session — only on the render that makes the launch decision.
+ */
+ pages: ReadonlySet<string> | null;
+ /**
+ * True once the page list has finished its cold load. The launch decision
+ * waits for this so it reads the real document count, not the empty set the
+ * provider starts with.
+ */
+ ready: boolean;
+ /**
+ * True when another nudge surface owns the footer at launch. If set when the
+ * launch decision is made, the card stands down for the whole session and
+ * tries again next launch — it never pops in mid-session when the other card
+ * clears. (A notice that arrives AFTER the card is already showing does not
+ * hide it; `blocked` gates only the launch decision.)
+ */
+ blocked: boolean;
+ /** Injection seam for tests; production uses the singleton. */
+ store?: FeedbackNudgeStore;
+ /** Injection seam for tests; production uses the wall clock. */
+ now?: () => number;
+ /** Injection seam for tests; production uses the module session. */
+ session?: FeedbackNudgeSession;
+}
+
+export function useFeedbackNudgeVisible({
+ pages,
+ ready,
+ blocked,
+ store = feedbackNudgeStore,
+ now = Date.now,
+ session = appSession,
+}: UseFeedbackNudgeOptions): boolean {
+ const { dismissed } = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+
+ // Initialized from the session so a React remount re-adopts a card that is
+ // already up — module state is what survives the remount; this mirror only
+ // exists to make React re-render when the show first happens.
+ const [shownThisSession, setShownThisSession] = useState(session.isShown());
+
+ // Starts the two-week clock on the first boot that ever mounts this hook.
+ // Idempotent, so StrictMode and remounts are no-ops.
+ useEffect(() => {
+ store.recordFirstSeen(now());
+ }, [store, now]);
+
+ useEffect(() => {
+ // Session-scoped latch (module scope) rather than a per-mount ref: a
+ // remount must neither re-run the decision nor mistake this session's
+ // own `shownAt` for a prior session's.
+ if (session.isEvaluated()) return;
+ // The decision is made once, at launch, when the document set has loaded.
+ if (!ready || pages == null) return;
+ session.latchEvaluated();
+ // Another footer card owns the space at launch → defer to the next launch
+ // rather than pop in later this session when it clears. Latching above
+ // before this check is what makes "blocked at launch" mean "next time",
+ // not "the moment the other card goes away" — consistent with only ever
+ // surfacing the card at launch, never mid-work.
+ if (blocked) return;
+ // A prior session's show suppresses here via the predicate's
+ // `shownAt == null` clause — the session's shown latch is still unset in
+ // a fresh JS context, so no separate prior-session guard is needed.
+ if (!isFeedbackNudgeEligible(store.getSnapshot(), now(), countUserDocuments(pages))) return;
+ store.recordShown(now());
+ session.latchShown();
+ setShownThisSession(true);
+ }, [ready, blocked, pages, store, now, session]);
+
+ return shownThisSession && !dismissed;
+}
diff --git a/packages/app/src/lib/feedback-nudge-store.test.ts b/packages/app/src/lib/feedback-nudge-store.test.ts
new file mode 100644
index 000000000..4d15dc844
--- /dev/null
+++ b/packages/app/src/lib/feedback-nudge-store.test.ts
@@ -0,0 +1,272 @@
+import { describe, expect, test } from 'vitest';
+import {
+ countUserDocuments,
+ createFeedbackNudgeStore,
+ DEFAULT_FEEDBACK_NUDGE_STATE,
+ FEEDBACK_NUDGE_MIN_AGE_MS,
+ FEEDBACK_NUDGE_MIN_DOCS,
+ FEEDBACK_NUDGE_STORAGE_KEY,
+ type FeedbackNudgeState,
+ type FeedbackNudgeStorage,
+ isFeedbackNudgeEligible,
+ readPersistedState,
+ writePersistedState,
+} from './feedback-nudge-store.ts';
+
+function memoryStorage(initial: Record<string, string> = {}): FeedbackNudgeStorage & {
+ raw(): string | null;
+} {
+ const data = new Map(Object.entries(initial));
+ return {
+ getItem(key) {
+ return data.get(key) ?? null;
+ },
+ setItem(key, value) {
+ data.set(key, value);
+ },
+ raw() {
+ return data.get(FEEDBACK_NUDGE_STORAGE_KEY) ?? null;
+ },
+ };
+}
+
+function stateWith(overrides: Partial<FeedbackNudgeState>): FeedbackNudgeState {
+ return { ...DEFAULT_FEEDBACK_NUDGE_STATE, ...overrides };
+}
+
+const NOW = 1_800_000_000_000;
+/** A `firstSeenAt` exactly on the two-week boundary relative to `NOW`. */
+const RIPE = NOW - FEEDBACK_NUDGE_MIN_AGE_MS;
+
+describe('readPersistedState', () => {
+ test('absent key returns default', () => {
+ expect(readPersistedState(memoryStorage())).toEqual(DEFAULT_FEEDBACK_NUDGE_STATE);
+ });
+
+ test('round-trips the durable fields', () => {
+ const stored = { firstSeenAt: RIPE, shownAt: NOW, dismissed: true };
+ const s = memoryStorage({ [FEEDBACK_NUDGE_STORAGE_KEY]: JSON.stringify(stored) });
+ expect(readPersistedState(s)).toEqual(stored);
+ });
+
+ test('non-number timestamps and non-boolean flags coerce safely', () => {
+ const s = memoryStorage({
+ [FEEDBACK_NUDGE_STORAGE_KEY]: JSON.stringify({
+ firstSeenAt: '1800000000000',
+ shownAt: {},
+ dismissed: 1,
+ }),
+ });
+ expect(readPersistedState(s)).toEqual(DEFAULT_FEEDBACK_NUDGE_STATE);
+ });
+
+ test('non-positive and non-finite timestamps coerce to null, not to the epoch', () => {
+ // A stored `0` would otherwise read as "first seen at the epoch" and make
+ // the two-week gate pass on the spot.
+ for (const bad of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+ const s = memoryStorage({
+ [FEEDBACK_NUDGE_STORAGE_KEY]: JSON.stringify({ firstSeenAt: bad }),
+ });
+ expect(readPersistedState(s).firstSeenAt).toBeNull();
+ }
+ });
+
+ test('corrupt JSON falls back to default', () => {
+ const s = memoryStorage({ [FEEDBACK_NUDGE_STORAGE_KEY]: '{not valid json' });
+ expect(readPersistedState(s)).toEqual(DEFAULT_FEEDBACK_NUDGE_STATE);
+ });
+});
+
+describe('writePersistedState', () => {
+ test('persists the state verbatim', () => {
+ const s = memoryStorage();
+ writePersistedState({ firstSeenAt: RIPE, shownAt: null, dismissed: true }, s);
+ expect(JSON.parse(s.raw() as string)).toEqual({
+ firstSeenAt: RIPE,
+ shownAt: null,
+ dismissed: true,
+ });
+ });
+});
+
+describe('storage that refuses to write', () => {
+ // Quota exceeded / Safari private mode / SSR. `FeedbackNudgeStorage` is an
+ // injected parameter, so the throw comes from a real collaborator through
+ // the public interface rather than a mock inside the try — the assertions
+ // are on the promised outcome (the session survives and in-memory state
+ // still holds), not on the catch having fired.
+ function throwingStorage(): FeedbackNudgeStorage {
+ return {
+ getItem: () => null,
+ setItem: () => {
+ throw new DOMException('QuotaExceededError');
+ },
+ };
+ }
+
+ test('writePersistedState does not propagate the failure', () => {
+ expect(() =>
+ writePersistedState(DEFAULT_FEEDBACK_NUDGE_STATE, throwingStorage()),
+ ).not.toThrow();
+ });
+
+ test('the store still records the answer in memory for this session', () => {
+ const store = createFeedbackNudgeStore(throwingStorage());
+
+ expect(() => store.dismiss()).not.toThrow();
+ // The write was lost, but the user's answer must still hold until reload —
+ // otherwise a full-storage device re-shows the nudge within the session.
+ expect(store.getSnapshot().dismissed).toBe(true);
+ expect(isFeedbackNudgeEligible(store.getSnapshot(), NOW, 400)).toBe(false);
+ });
+});
+
+describe('countUserDocuments', () => {
+ test('counts ordinary docs at any depth', () => {
+ expect(countUserDocuments(new Set(['notes', 'brain/ideas', 'a/b/c/deep']))).toBe(3);
+ });
+
+ test('excludes the .ok substrate that /api/pages serves alongside real docs', () => {
+ const pages = new Set([
+ 'notes',
+ // Skills-as-content: every `ok init` project ships these.
+ '.ok/skills/project/SKILL',
+ '.ok/skills/project/references/linking',
+ // Starter-pack templates land in a nested `.ok/`.
+ 'brain/.ok/templates/article',
+ 'brain/.ok/frontmatter',
+ ]);
+ expect(countUserDocuments(pages)).toBe(1);
+ });
+
+ test('case-insensitive on the .ok segment, matching the file-tree predicate', () => {
+ expect(countUserDocuments(new Set(['.OK/skills/project/SKILL', 'notes']))).toBe(1);
+ });
+
+ test('a doc merely named "ok" is not substrate', () => {
+ expect(countUserDocuments(new Set(['ok', 'ok/notes', 'notes.ok']))).toBe(3);
+ });
+
+ test('empty set counts zero', () => {
+ expect(countUserDocuments(new Set())).toBe(0);
+ });
+});
+
+describe('isFeedbackNudgeEligible', () => {
+ test('eligible once both gates pass', () => {
+ expect(
+ isFeedbackNudgeEligible(stateWith({ firstSeenAt: RIPE }), NOW, FEEDBACK_NUDGE_MIN_DOCS),
+ ).toBe(true);
+ });
+
+ test('the default state is never eligible — firstSeenAt has not been stamped', () => {
+ expect(isFeedbackNudgeEligible(DEFAULT_FEEDBACK_NUDGE_STATE, NOW, 1000)).toBe(false);
+ });
+
+ test('not eligible one millisecond before the two-week boundary', () => {
+ expect(
+ isFeedbackNudgeEligible(stateWith({ firstSeenAt: RIPE + 1 }), NOW, FEEDBACK_NUDGE_MIN_DOCS),
+ ).toBe(false);
+ });
+
+ test('not eligible one document below the threshold', () => {
+ expect(
+ isFeedbackNudgeEligible(stateWith({ firstSeenAt: RIPE }), NOW, FEEDBACK_NUDGE_MIN_DOCS - 1),
+ ).toBe(false);
+ });
+
+ test('a comfortably old, well-populated workspace is eligible', () => {
+ expect(isFeedbackNudgeEligible(stateWith({ firstSeenAt: RIPE - 5_000 }), NOW, 400)).toBe(true);
+ });
+
+ test('never eligible once shown, regardless of how ripe the gates are', () => {
+ expect(
+ isFeedbackNudgeEligible(stateWith({ firstSeenAt: RIPE, shownAt: NOW - 1 }), NOW, 400),
+ ).toBe(false);
+ });
+
+ test('never eligible once dismissed', () => {
+ expect(
+ isFeedbackNudgeEligible(stateWith({ firstSeenAt: RIPE, dismissed: true }), NOW, 400),
+ ).toBe(false);
+ });
+});
+
+describe('createFeedbackNudgeStore', () => {
+ test('recordFirstSeen stamps once and never moves', () => {
+ const s = memoryStorage();
+ const store = createFeedbackNudgeStore(s);
+ store.recordFirstSeen(NOW);
+ store.recordFirstSeen(NOW + 90_000);
+ expect(store.getSnapshot().firstSeenAt).toBe(NOW);
+ expect(JSON.parse(s.raw() as string).firstSeenAt).toBe(NOW);
+ });
+
+ test('recordShown latches once', () => {
+ const store = createFeedbackNudgeStore(memoryStorage());
+ store.recordShown(NOW);
+ store.recordShown(NOW + 90_000);
+ expect(store.getSnapshot().shownAt).toBe(NOW);
+ });
+
+ test('dismiss latches and is idempotent', () => {
+ const store = createFeedbackNudgeStore(memoryStorage());
+ store.dismiss();
+ store.dismiss();
+ expect(store.getSnapshot().dismissed).toBe(true);
+ });
+
+ test('a fresh store over the same storage keeps the clock and stays suppressed', () => {
+ const s = memoryStorage();
+ const first = createFeedbackNudgeStore(s);
+ first.recordFirstSeen(RIPE);
+ first.recordShown(NOW);
+
+ const second = createFeedbackNudgeStore(s);
+ expect(second.getSnapshot().firstSeenAt).toBe(RIPE);
+ // The one-shot survives the reload: a new device session does not re-nag.
+ expect(isFeedbackNudgeEligible(second.getSnapshot(), NOW, 400)).toBe(false);
+ });
+
+ test('subscribe notifies listeners on real transitions only', () => {
+ const store = createFeedbackNudgeStore(memoryStorage());
+ let calls = 0;
+ const unsub = store.subscribe(() => {
+ calls++;
+ });
+ store.recordFirstSeen(NOW);
+ store.recordFirstSeen(NOW); // idempotent — no second notify
+ unsub();
+ store.dismiss(); // after unsub — not counted
+ expect(calls).toBe(1);
+ });
+
+ test('install re-reads storage written after construction', () => {
+ const s = memoryStorage();
+ const store = createFeedbackNudgeStore(s);
+ expect(store.getSnapshot().firstSeenAt).toBeNull();
+ writePersistedState(stateWith({ firstSeenAt: RIPE }), s);
+ store.install();
+ expect(store.getSnapshot().firstSeenAt).toBe(RIPE);
+ });
+
+ test('syncFromStorage adopts another window write and notifies', () => {
+ // Cross-window contract: a second window shares this storage. When it
+ // dismisses, this window's `storage` handler calls syncFromStorage, and the
+ // dismissal must land here so the card can clear without a reload.
+ const shared = memoryStorage();
+ const thisWindow = createFeedbackNudgeStore(shared);
+ let notified = 0;
+ thisWindow.subscribe(() => {
+ notified++;
+ });
+ expect(thisWindow.getSnapshot().dismissed).toBe(false);
+
+ const otherWindow = createFeedbackNudgeStore(shared);
+ otherWindow.dismiss(); // writes shared storage
+
+ thisWindow.syncFromStorage();
+ expect(thisWindow.getSnapshot().dismissed).toBe(true);
+ expect(notified).toBeGreaterThan(0);
+ });
+});
diff --git a/packages/app/src/lib/feedback-nudge-store.ts b/packages/app/src/lib/feedback-nudge-store.ts
new file mode 100644
index 000000000..feb60c588
--- /dev/null
+++ b/packages/app/src/lib/feedback-nudge-store.ts
@@ -0,0 +1,249 @@
+/**
+ * Feedback nudge store — device-local persistence for the one-time proactive
+ * feedback card. The card asks an engaged, past-the-honeymoon user how
+ * OpenKnowledge is going and opens the existing feedback form.
+ *
+ * Three persisted facts gate it:
+ * - `firstSeenAt` — epoch ms of the first boot that ever observed this store.
+ * Starts the two-week clock. Approximate by construction: there is no
+ * install timestamp anywhere in the product, so a user who installed months
+ * ago starts their clock on the first boot after this ships.
+ * - `shownAt` — when the card was first shown. Non-null suppresses
+ * forever: the card gets exactly one session on screen, then never returns,
+ * whether the user engaged with it or ignored it.
+ * - `dismissed` — the user answered (closed the card or closed the feedback
+ * form). Suppresses forever.
+ *
+ * Mirrors `subscribe-card-store`: a module-level singleton bound to React via
+ * `useSyncExternalStore`, mirrored to localStorage, re-read on construction.
+ * Cross-window sync follows `enabled-agents` — a `storage` event on the
+ * singleton re-reads persisted state so a dismiss in one window clears the card
+ * in every other open window without a reload.
+ */
+
+import { hasOkPathSegment } from '@/components/file-tree-utils';
+
+export const FEEDBACK_NUDGE_STORAGE_KEY = 'ok-feedback-nudge-v1';
+
+/** How long after first boot the nudge becomes eligible. */
+export const FEEDBACK_NUDGE_MIN_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+
+/** How many user documents the workspace must hold for the nudge to be eligible. */
+export const FEEDBACK_NUDGE_MIN_DOCS = 10;
+
+export interface FeedbackNudgeState {
+ /** Epoch ms of the first boot that observed this store; null until set. */
+ readonly firstSeenAt: number | null;
+ /** Epoch ms the card was first shown; null until it fires. */
+ readonly shownAt: number | null;
+ /** The user answered the nudge — card closed, or the feedback form closed. */
+ readonly dismissed: boolean;
+}
+
+export const DEFAULT_FEEDBACK_NUDGE_STATE: FeedbackNudgeState = {
+ firstSeenAt: null,
+ shownAt: null,
+ dismissed: false,
+};
+
+export interface FeedbackNudgeStorage {
+ getItem(key: string): string | null;
+ setItem(key: string, value: string): void;
+}
+
+export interface FeedbackNudgeStore {
+ getSnapshot(): FeedbackNudgeState;
+ subscribe(listener: () => void): () => void;
+ /** Start the two-week clock. No-op once `firstSeenAt` is set. */
+ recordFirstSeen(now: number): void;
+ /** Latch the one-shot show. No-op once `shownAt` is set. */
+ recordShown(now: number): void;
+ /** Persist that the user answered the nudge (idempotent). */
+ dismiss(): void;
+ /**
+ * Re-read persisted state and notify. Drives cross-window sync via the
+ * `storage` event; also the boot re-read behind `install`. No write.
+ */
+ syncFromStorage(): void;
+ /** Re-sync from storage at app boot. Idempotent. */
+ install(): void;
+}
+
+/**
+ * Documents the user would recognize as theirs. `/api/pages` serves the whole
+ * file index, and the skills-as-content carve-out puts `.ok/skills/**` markdown
+ * in it — every `ok init` project ships the `project` skill (a SKILL.md plus
+ * seven files under `references/`), so a brand-new empty project already reads
+ * as roughly ten "pages". Starter packs land their templates under
+ * `<folder>/.ok/templates/` too. Filtering on the `.ok` segment drops both, so
+ * the count reflects authored content rather than OK-managed substrate.
+ *
+ * `hasOkPathSegment` is the same predicate the file tree uses to decide what is
+ * OK-managed — one definition, so the count and the tree can't disagree.
+ */
+export function countUserDocuments(pages: ReadonlySet<string>): number {
+ let count = 0;
+ for (const docName of pages) {
+ if (!hasOkPathSegment(docName)) count++;
+ }
+ return count;
+}
+
+/**
+ * True when the card should take its one session: the user hasn't answered, it
+ * has never shown, the two-week clock has run, and the workspace holds enough
+ * documents.
+ *
+ * Pure — `now` and `docCount` are injected so the boundaries are testable and
+ * so no caller can accidentally evaluate against a clock the tests can't move.
+ */
+export function isFeedbackNudgeEligible(
+ state: FeedbackNudgeState,
+ now: number,
+ docCount: number,
+): boolean {
+ return (
+ !state.dismissed &&
+ state.shownAt == null &&
+ state.firstSeenAt != null &&
+ now - state.firstSeenAt >= FEEDBACK_NUDGE_MIN_AGE_MS &&
+ docCount >= FEEDBACK_NUDGE_MIN_DOCS
+ );
+}
+
+function asFlag(value: unknown): boolean {
+ return value === true;
+}
+
+/**
+ * Epoch-ms coercion. Rejects NaN/Infinity and non-positive values: a corrupt
+ * `0` or negative timestamp would read as "first seen at the epoch" and make
+ * the two-week gate pass instantly.
+ */
+function asEpochMs(value: unknown): number | null {
+ return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
+}
+
+/**
+ * Coerce arbitrary parsed JSON into a valid state. Every field defaults safely
+ * so partial, corrupt, or forward/backward-incompatible payloads degrade rather
+ * than throw.
+ */
+function coerceState(parsed: unknown): FeedbackNudgeState {
+ if (typeof parsed !== 'object' || parsed === null) return DEFAULT_FEEDBACK_NUDGE_STATE;
+ const obj = parsed as Record<string, unknown>;
+ return {
+ firstSeenAt: asEpochMs(obj.firstSeenAt),
+ shownAt: asEpochMs(obj.shownAt),
+ dismissed: asFlag(obj.dismissed),
+ };
+}
+
+export function readPersistedState(storage?: FeedbackNudgeStorage): FeedbackNudgeState {
+ try {
+ const s = storage ?? localStorage;
+ const raw = s.getItem(FEEDBACK_NUDGE_STORAGE_KEY);
+ if (raw == null) return DEFAULT_FEEDBACK_NUDGE_STATE;
+ return coerceState(JSON.parse(raw));
+ } catch (err) {
+ // Absent / throwing localStorage (SSR, Safari private mode, sandboxed
+ // iframe) or corrupt JSON — fall back to defaults so module init never
+ // crashes.
+ console.warn('[feedback-nudge-store] readPersistedState failed (corrupt/privacy/SSR)', err);
+ return DEFAULT_FEEDBACK_NUDGE_STATE;
+ }
+}
+
+export function writePersistedState(
+ state: FeedbackNudgeState,
+ storage?: FeedbackNudgeStorage,
+): void {
+ try {
+ const s = storage ?? localStorage;
+ s.setItem(FEEDBACK_NUDGE_STORAGE_KEY, JSON.stringify(state));
+ } catch (err) {
+ // Quota exceeded / privacy mode / SSR — in-memory state holds for the session.
+ console.warn('[feedback-nudge-store] writePersistedState failed (quota/privacy/SSR)', err);
+ }
+}
+
+export function createFeedbackNudgeStore(storage?: FeedbackNudgeStorage): FeedbackNudgeStore {
+ let state = readPersistedState(storage);
+ const listeners = new Set<() => void>();
+ let installed = false;
+
+ function notify(): void {
+ for (const listener of listeners) listener();
+ }
+
+ function commit(next: FeedbackNudgeState): void {
+ state = next;
+ writePersistedState(state, storage);
+ notify();
+ }
+
+ function syncFromStorage(): void {
+ // Adopt whatever another window (or the boot re-read) persisted. Notify
+ // unconditionally — a no-op notify is cheap, and skipping it would need a
+ // deep compare of the state we just read.
+ state = readPersistedState(storage);
+ notify();
+ }
+
+ return {
+ getSnapshot(): FeedbackNudgeState {
+ return state;
+ },
+
+ subscribe(listener): () => void {
+ listeners.add(listener);
+ return () => {
+ listeners.delete(listener);
+ };
+ },
+
+ recordFirstSeen(now): void {
+ if (state.firstSeenAt != null) return;
+ commit({ ...state, firstSeenAt: now });
+ },
+
+ recordShown(now): void {
+ if (state.shownAt != null) return;
+ commit({ ...state, shownAt: now });
+ },
+
+ dismiss(): void {
+ if (state.dismissed) return;
+ commit({ ...state, dismissed: true });
+ },
+
+ syncFromStorage,
+
+ install(): void {
+ if (installed) return;
+ installed = true;
+ // Re-read at boot in case the singleton was constructed before storage
+ // was reachable (module graph import order).
+ syncFromStorage();
+ },
+ };
+}
+
+export const feedbackNudgeStore: FeedbackNudgeStore = createFeedbackNudgeStore();
+
+// Cross-window sync: when another window writes the nudge key, adopt it here so
+// a dismiss over there clears the card here without a reload. The `storage`
+// event only fires in OTHER windows, so the writing window is already current
+// via its own `commit`. `event.key === null` covers `localStorage.clear()`.
+// Mirrors `enabled-agents` / `registered-agents`.
+if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+ window.addEventListener('storage', (event) => {
+ if (event.key === FEEDBACK_NUDGE_STORAGE_KEY || event.key === null) {
+ feedbackNudgeStore.syncFromStorage();
+ }
+ });
+}
+
+export function installFeedbackNudgeStore(): void {
+ feedbackNudgeStore.install();
+}
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index 00990a797..c4caacda6 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -2632,6 +2632,7 @@
"rageVb": ["Custom HTML with a live preview pane (sandboxed iframe)."],
"rdU729": ["Layout"],
"rfFpcF": ["Remove ", ["chip"]],
+ "rg7hNd": ["Rate your experience"],
"rgPqOw": ["Convert the current block to a paragraph."],
"riqekz": ["Suggestion menu navigation"],
"rlUzXK": ["Could not validate folder. Please try again."],
@@ -2643,6 +2644,7 @@
"rwrPbS": ["Component boundary navigation"],
"s-MGs7": ["Resources"],
"s-XOaI": ["File name"],
+ "s0-xF4": ["Tell us how it's going"],
"s061i4": ["Relative path"],
"s0IDhW": ["This file could not be found."],
"s0J_k9": [["0", "plural", { "one": ["#", " key"], "other": ["#", " keys"] }]],
@@ -2733,6 +2735,7 @@
"u3YnKw": ["Could not construct share URL."],
"u3wRF-": ["Published"],
"u5Utjn": [["0"], " needs ", ["1"]],
+ "u5hSeG": ["Share feedback"],
"u6Hp4N": ["Markdown"],
"u7H-Wn": ["Show panel (", ["panelShortcutLabel"], ")"],
"u7U_Ij": ["Link the selected text, or edit the link under the caret."],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index c5cb4ceb9..9dda539f4 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -1700,6 +1700,7 @@ msgid "Cloning..."
msgstr "Cloning..."
#: src/components/EditorTabs.tsx
+#: src/components/FeedbackForm.tsx
#: src/components/InstallInClaudeDesktopDialog.tsx
#: src/components/ReportBugDialogBody.tsx
#: src/components/SeedDialog.tsx
@@ -6747,6 +6748,10 @@ msgstr "Pushing"
msgid "Quote"
msgstr "Quote"
+#: src/components/FeedbackForm.tsx
+msgid "Rate your experience"
+msgstr "Rate your experience"
+
#: src/components/AuthModal.tsx
msgid "Re-authenticate with GitHub"
msgstr "Re-authenticate with GitHub"
@@ -7749,6 +7754,10 @@ msgstr "Share"
msgid "Share doc"
msgstr "Share doc"
+#: src/components/FeedbackCard.tsx
+msgid "Share feedback"
+msgstr "Share feedback"
+
#: src/components/ShareButton.tsx
msgid "Share folder"
msgstr "Share folder"
@@ -8472,6 +8481,10 @@ msgstr "Teaches coding agents in this project to read and write through OpenKnow
msgid "Team Wiki"
msgstr "Team Wiki"
+#: src/components/FeedbackCard.tsx
+msgid "Tell us how it's going"
+msgstr "Tell us how it's going"
+
#: src/components/FeedbackForm.tsx
msgid "Tell us more (optional)"
msgstr "Tell us more (optional)"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 13540564a..4a966c1f3 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -2632,6 +2632,7 @@
"rageVb": ["Ćũśţōḿ ĤŢḾĹ ŵĩţĥ à ĺĩvē ƥŕēvĩēŵ ƥàńē (śàńďƀōxēď ĩƒŕàḿē)."],
"rdU729": ["Ĺàŷōũţ"],
"rfFpcF": ["Ŕēḿōvē ", ["chip"]],
+ "rg7hNd": ["Ŕàţē ŷōũŕ ēxƥēŕĩēńćē"],
"rgPqOw": ["Ćōńvēŕţ ţĥē ćũŕŕēńţ ƀĺōćķ ţō à ƥàŕàĝŕàƥĥ."],
"riqekz": ["Śũĝĝēśţĩōń ḿēńũ ńàvĩĝàţĩōń"],
"rlUzXK": ["Ćōũĺď ńōţ vàĺĩďàţē ƒōĺďēŕ. Ƥĺēàśē ţŕŷ àĝàĩń."],
@@ -2643,6 +2644,7 @@
"rwrPbS": ["Ćōḿƥōńēńţ ƀōũńďàŕŷ ńàvĩĝàţĩōń"],
"s-MGs7": ["Ŕēśōũŕćēś"],
"s-XOaI": ["Ƒĩĺē ńàḿē"],
+ "s0-xF4": ["Ţēĺĺ ũś ĥōŵ ĩţ'ś ĝōĩńĝ"],
"s061i4": ["Ŕēĺàţĩvē ƥàţĥ"],
"s0IDhW": ["Ţĥĩś ƒĩĺē ćōũĺď ńōţ ƀē ƒōũńď."],
"s0J_k9": [["0", "plural", { "one": ["#", " ķēŷ"], "other": ["#", " ķēŷś"] }]],
@@ -2733,6 +2735,7 @@
"u3YnKw": ["Ćōũĺď ńōţ ćōńśţŕũćţ śĥàŕē ŨŔĹ."],
"u3wRF-": ["Ƥũƀĺĩśĥēď"],
"u5Utjn": [["0"], " ńēēďś ", ["1"]],
+ "u5hSeG": ["Śĥàŕē ƒēēďƀàćķ"],
"u6Hp4N": ["Ḿàŕķďōŵń"],
"u7H-Wn": ["Śĥōŵ ƥàńēĺ (", ["panelShortcutLabel"], ")"],
"u7U_Ij": ["Ĺĩńķ ţĥē śēĺēćţēď ţēxţ, ōŕ ēďĩţ ţĥē ĺĩńķ ũńďēŕ ţĥē ćàŕēţ."],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index 719dc2857..edfcc18b5 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -1696,6 +1696,7 @@ msgid "Cloning..."
msgstr ""
#: src/components/EditorTabs.tsx
+#: src/components/FeedbackForm.tsx
#: src/components/InstallInClaudeDesktopDialog.tsx
#: src/components/ReportBugDialogBody.tsx
#: src/components/SeedDialog.tsx
@@ -6743,6 +6744,10 @@ msgstr ""
msgid "Quote"
msgstr ""
+#: src/components/FeedbackForm.tsx
+msgid "Rate your experience"
+msgstr ""
+
#: src/components/AuthModal.tsx
msgid "Re-authenticate with GitHub"
msgstr ""
@@ -7745,6 +7750,10 @@ msgstr ""
msgid "Share doc"
msgstr ""
+#: src/components/FeedbackCard.tsx
+msgid "Share feedback"
+msgstr ""
+
#: src/components/ShareButton.tsx
msgid "Share folder"
msgstr ""
@@ -8468,6 +8477,10 @@ msgstr ""
msgid "Team Wiki"
msgstr ""
+#: src/components/FeedbackCard.tsx
+msgid "Tell us how it's going"
+msgstr ""
+
#: src/components/FeedbackForm.tsx
msgid "Tell us more (optional)"
msgstr ""
diff --git a/packages/app/src/main.tsx b/packages/app/src/main.tsx
index d0165db00..2b387a349 100644
--- a/packages/app/src/main.tsx
+++ b/packages/app/src/main.tsx
@@ -37,6 +37,7 @@ import { useHydrateRegisteredAgentMeta } from '@/lib/acp/catalog';
import { installClientFetchWrapper } from '@/lib/client-fetch';
import { installConsentListener } from '@/lib/consent-store';
import { installCrashInviteListener } from '@/lib/crash-invite-store';
+import { installFeedbackNudgeStore } from '@/lib/feedback-nudge-store';
// Side-effect import: loads + activates the i18n catalog before first render.
import { i18n } from '@/lib/i18n';
import { installClientLogForwarder } from '@/lib/install-client-log-forwarder';
@@ -121,6 +122,11 @@ installOnboardingCardStore();
// paint. Device-local; no-op in web/CLI and SSR where localStorage is absent.
installSubscribeCardStore();
+// Hydrate the proactive-feedback nudge store, same rationale again. The
+// `firstSeenAt` clock this carries is the two-week gate on the feedback toast,
+// so it must be readable before the controller mounts and stamps it.
+installFeedbackNudgeStore();
+
// Desktop-only: track whether an auto-update relaunch is in flight (the same
// `ok:update:relaunching` / `ok:update:relaunch-failed` events the notice
// bridge consumes) so connectivity-sensitive panels can show a calm