@flamingo-stack/openframe-frontend-core 0.0.672 → 0.0.673-2406.7239.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.672",
+  "version": "0.0.673-2406.7239.1",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -229,6 +229,12 @@
       "require": "./dist/utils/humanity-signals.cjs",
       "default": "./dist/utils/humanity-signals.js"
     },
+    "./utils/form-rescue": {
+      "types": "./dist/utils/form-rescue.d.ts",
+      "import": "./dist/utils/form-rescue.js",
+      "require": "./dist/utils/form-rescue.cjs",
+      "default": "./dist/utils/form-rescue.js"
+    },
     "./utils/platform-identity": {
       "types": "./dist/utils/platform-identity.d.ts",
       "import": "./dist/utils/platform-identity.js",

package/src/components/case-studies/share-experience-section.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import type React from 'react';
+import { RESCUE_FORMS } from '../../utils/form-rescue';
 import { ContactForm, type ContactFormProps } from '../contact';
 import { G2Icon, CapterraIcon, TrustpilotIcon, GetAppIcon } from '../icons';
 import { BenefitCard, BenefitCardGrid } from '../ui';
@@ -93,6 +94,7 @@ const DEFAULT_CONTACT_FORM_PROPS = {
   buttonVariant: 'outline' as ContactFormProps['buttonVariant'],
   buttonClassName: 'w-full',
   successToastMessage: "Thank you! We'll reach out to schedule your case study.",
+  rescue: RESCUE_FORMS.caseStudyPitch,
 } satisfies Partial<ContactFormProps>;
 
 export function ShareExperienceSection({

package/src/components/contact/contact-form.tsx

@@ -22,10 +22,11 @@
  */
 
 import { zodResolver } from '@hookform/resolvers/zod';
-import { useState, type ReactNode } from 'react';
+import { useMemo, useState, type ReactNode } from 'react';
 import { useForm, Controller } from 'react-hook-form';
 import { useContactSubmission } from '../../hooks/use-contact-submission';
 import { useHumanitySignals } from '../../hooks/use-humanity-signals';
+import { useRescuedForm } from '../../hooks/use-rescued-form';
 import {
   ContactSchema,
   type ContactFormData,
@@ -33,6 +34,7 @@ import {
   referralSourceOptions,
   defaultHelpCategoryOptions,
 } from '../../schemas/contact-schema';
+import type { FormRescueDefinition } from '../../utils/form-rescue';
 import { HUBSPOT_DO_NOT_COLLECT_FORM_PROPS } from '../../utils/hubspot-collected-forms';
 import { ChatAttachmentAddButton, ChatAttachmentChipStrip } from '../chat/chat-attachment-bar';
 import { useChatAttachments } from '../chat/hooks/use-chat-attachments';
@@ -130,6 +132,11 @@ export interface ContactFormProps {
   submitSuccessLabel?: string;
   successRedirectUrl?: string;
   successToastMessage?: string;
+  /** Form rescue (a half-filled form is saved so the team can follow up): the
+   *  form's definition (`RESCUE_FORMS.contact`, or the host's own
+   *  `defineRescueForm`). OPT-IN: omitted or `null` saves nothing, so a host that
+   *  has not chosen rescue never starts storing what visitors type. */
+  rescue?: FormRescueDefinition | null;
 }
 
 export function ContactForm({
@@ -155,6 +162,7 @@ export function ContactForm({
   submitSuccessLabel = 'Message Sent!',
   successRedirectUrl = '/blog#community',
   successToastMessage = 'Redirecting you to join our community...',
+  rescue: rescueForm = null,
 }: ContactFormProps = {}) {
   // Attachments staging — same hook the chat composer + ticket
   // detail-drawer composer use. Files upload to Supabase as soon as
@@ -185,13 +193,7 @@ export function ContactForm({
   // own their own UX (no "Message Sent!" button-label flicker).
   const isSuccess = onCustomSubmit ? false : builtInSubmission.isSuccess;
 
-  const {
-    register,
-    handleSubmit,
-    control,
-    formState: { errors },
-    reset,
-  } = useForm<ContactFormData>({
+  const form = useForm<ContactFormData>({
     resolver: zodResolver(ContactSchema),
     defaultValues: {
       ...(prefilledReason && { helpCategory: prefilledReason }),
@@ -201,12 +203,30 @@ export function ContactForm({
       ...defaultValuesProp,
     },
   });
+  const {
+    register,
+    handleSubmit,
+    control,
+    formState: { errors },
+    reset,
+  } = form;
+
+  // Form rescue: only the fields the visitor can see are tracked, so a hidden
+  // prefilled value (a signed-in email, a fixed category) is never sent.
+  const rescueFieldNames = useMemo(
+    () =>
+      (['name', 'email', 'companySize', 'referralSource', 'helpCategory', 'message'] as const).filter(
+        field => !hideFields.includes(field),
+      ),
+    [hideFields],
+  );
+  const rescue = useRescuedForm(form, { rescue: rescueForm, fields: rescueFieldNames, getSignals });
 
   const handleFormSubmit = async (data: ContactFormData) => {
     if (isSubmitting) return;
     if (attachmentsEnabled && attachments.hasInflightUploads) return;
     try {
-      const payload = { ...data, ...(rdtCid && { rdt_cid: rdtCid }), ...getSignals() };
+      const payload = { ...data, ...(rdtCid && { rdt_cid: rdtCid }), ...getSignals(), ...rescue.submitFields() };
       const readyAttachments = attachmentsEnabled ? attachments.readyAttachments : [];
       if (onCustomSubmit) {
         setCustomSubmitting(true);
@@ -218,6 +238,7 @@ export function ContactForm({
       } else {
         await builtInSubmission.submit(payload);
       }
+      rescue.complete();
       onSubmitSuccess?.();
       reset();
       resetSignals();
@@ -346,7 +367,7 @@ export function ContactForm({
                   control={control}
                   name="companySize"
                   render={({ field }) => (
-                    <Select onValueChange={field.onChange} defaultValue={field.value}>
+                    <Select onValueChange={field.onChange} value={field.value ?? ''}>
                       <SelectTrigger
                         id="companySize"
                         aria-label="Company Size"
@@ -378,7 +399,7 @@ export function ContactForm({
                   control={control}
                   name="referralSource"
                   render={({ field }) => (
-                    <Select onValueChange={field.onChange} defaultValue={field.value}>
+                    <Select onValueChange={field.onChange} value={field.value ?? ''}>
                       <SelectTrigger
                         id="referralSource"
                         aria-label="Referral Source"
@@ -416,7 +437,7 @@ export function ContactForm({
               control={control}
               name="helpCategory"
               render={({ field }) => (
-                <Select onValueChange={field.onChange} defaultValue={field.value}>
+                <Select onValueChange={field.onChange} value={field.value ?? ''}>
                   <SelectTrigger
                     id="helpCategory"
                     aria-label="Help Category"

package/src/components/features/waitlist-form.tsx

@@ -5,10 +5,12 @@ import type { CountryCode } from 'libphonenumber-js';
 import { useEffect, useState } from 'react';
 import type { KeyboardEvent } from 'react';
 import { useIsHydrated } from '../../hooks/ui/use-is-hydrated';
+import { useFormRescue } from '../../hooks/use-form-rescue';
 import { useHumanitySignals } from '../../hooks/use-humanity-signals';
 import { useToast } from '../../hooks/use-toast';
 import { cn } from '../../utils/cn';
 import { formatPhoneE164 } from '../../utils/country-phone-utils';
+import type { FormRescueDefinition } from '../../utils/form-rescue';
 import { hasGenericEmailDomain } from '../../utils/generic-domain-utils';
 import type { HumanitySignals } from '../../utils/humanity-signals';
 import { OpenFrameLogo } from '../icons';
@@ -30,7 +32,14 @@ export interface WaitlistFormProps {
    * POST body. Must throw on failure (toast is handled by the form). `signals`
    * is optional for backward compatibility with older callers.
    */
-  onRegister: (email: string, phone?: string, signals?: HumanitySignals) => Promise<void>;
+  /** `rescue` carries the form-rescue keys (`form_attempt_id`, …) to merge into the
+   *  POST body, so the host closes the half-filled draft this submit completes. */
+  onRegister: (
+    email: string,
+    phone?: string,
+    signals?: HumanitySignals,
+    rescue?: Record<string, string>,
+  ) => Promise<void>;
   /** Whether a registration request is currently in flight */
   isSubmitting?: boolean;
   /** Whether registration completed successfully */
@@ -57,6 +66,8 @@ export interface WaitlistFormProps {
   privacyPolicyUrl?: string;
   /** SMS consent text shown below the checkbox label */
   consentText?: string;
+  /** Form rescue (save a half-filled form for follow-up), e.g. `RESCUE_FORMS.waitlist`. OPT-IN: omitted or `null` saves nothing. */
+  rescue?: FormRescueDefinition | null;
 }
 
 /**
@@ -90,6 +101,7 @@ export function WaitlistForm({
   invalidPhoneHint = 'Invalid phone number format.',
   termsOfServiceUrl,
   privacyPolicyUrl,
+  rescue: rescueForm = null,
   consentText = 'I agree to receive recurring automated text messages at the phone number provided. Msg & data rates may apply. Msg frequency varies. Reply HELP for help and STOP to cancel.',
 }: WaitlistFormProps) {
   const [email, setEmail] = useState(defaultEmail);
@@ -101,6 +113,18 @@ export function WaitlistForm({
   const isClient = useIsHydrated();
   const [isPhoneInvalid, setIsPhoneInvalid] = useState(false);
   const [showConsentError, setShowConsentError] = useState(false);
+  const rescue = useFormRescue({
+    form: rescueForm,
+    // The phone is reported as filled only; its value never leaves the form early.
+    fieldNames: ['email', 'phone'],
+    getSignals,
+    onRestore: values => {
+      if (values.email) setEmail(current => current || values.email);
+    },
+  });
+  useEffect(() => {
+    rescue.track({ email, phone }, null);
+  }, [email, phone, rescue]);
 
   const isMailDomainGeneric = hasGenericEmailDomain(email);
 
@@ -160,7 +184,8 @@ export function WaitlistForm({
     const finalPhone = phone ? formatPhoneE164(phone, countryCode) : undefined;
 
     try {
-      await onRegister(email, finalPhone, getSignals());
+      await onRegister(email, finalPhone, getSignals(), rescue.submitFields());
+      rescue.complete();
       resetSignals();
     } catch {
       // caller's onRegister should handle its own error toasts if needed

package/src/components/help-center-pages/trust-center-sections.tsx

@@ -34,6 +34,7 @@ import {
   type TrustFrameworkMonitoringEntry,
 } from '../../types/trust-center';
 import { getFlagFromCountryName } from '../../utils/country-phone-utils';
+import { RESCUE_FORMS } from '../../utils/form-rescue';
 import { STICKY_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav';
 import { brandLogoForName } from '../chat/utils/icon-library';
 import { ContactForm } from '../contact/contact-form';
@@ -443,6 +444,7 @@ export function DocumentRequestModal({
               with access, usually within one business day.
             </p>
             <ContactForm
+              rescue={RESCUE_FORMS.trustCenterRequest}
               title=""
               noBorder
               noPadding

package/src/components/meeting-scheduler/booking-form.tsx

@@ -4,7 +4,8 @@ import { zodResolver } from '@hookform/resolvers/zod';
 import { Fragment, useEffect, useMemo, useState } from 'react';
 import type { FormEvent, ReactNode, Ref } from 'react';
 import { useForm, Controller } from 'react-hook-form';
-import type { Control, UseFormRegister } from 'react-hook-form';
+import type { Control, Path, UseFormRegister } from 'react-hook-form';
+import { useRescuedForm } from '../../hooks/use-rescued-form';
 import {
   BUILT_IN_BOOKING_FIELDS,
   type BuiltInBookingFieldName,
@@ -22,6 +23,7 @@ import {
   type BookingFormValues,
 } from '../../schemas/meeting-booking-schema';
 import { cn } from '../../utils/cn';
+import type { FormRescueDefinition } from '../../utils/form-rescue';
 import { HUBSPOT_DO_NOT_COLLECT_FORM_PROPS } from '../../utils/hubspot-collected-forms';
 import {
   Button,
@@ -370,6 +372,11 @@ export interface BookingFormProps {
   /** From useHumanitySignals — parent owns the instance so it can resetSignals(). */
   honeypotInputProps: { ref: Ref<HTMLInputElement>; name: string };
   getSignals: () => Record<string, string | number>;
+  /** Form rescue for this form (`RESCUE_FORMS.meetingBooking`); `null` or omitted saves nothing.
+   *  The attempt's keys ride the payload handed to `onSubmit`, so the parent closes it after
+   *  the booking commits (`completeFormRescue`), in details-first too, where this form has
+   *  unmounted by then. */
+  rescue?: FormRescueDefinition | null;
 }
 
 /**
@@ -402,6 +409,7 @@ export function BookingForm({
   onSubmit,
   honeypotInputProps,
   getSignals,
+  rescue = null,
 }: BookingFormProps) {
   const { formFields, legalConsent } = availability;
   // Every declared question resolved to a control (`resolveFormFieldControl`) —
@@ -431,6 +439,7 @@ export function BookingForm({
     handleSubmit,
     setValue,
     getValues,
+    watch,
     formState: { errors },
   } = useForm<BookingFormValues>({
     resolver: zodResolver(schema),
@@ -479,6 +488,24 @@ export function BookingForm({
     );
   }, [consentDefaults, priorConsents, getValues, setValue]);
 
+  // Form rescue: the built-ins by name, the declared questions under `formFields.<name>`.
+  const rescueFields = useMemo(
+    () => [...BUILT_IN_BOOKING_FIELDS.map(field => field.name), ...supportedFields.map(field => field.name)],
+    [supportedFields],
+  );
+  const formRescue = useRescuedForm(
+    { watch, getValues, setValue },
+    {
+      rescue,
+      fields: rescueFields,
+      getSignals,
+      fieldPath: name =>
+        (BUILT_IN_BOOKING_FIELDS.some(field => field.name === name)
+          ? name
+          : `formFields.${name}`) as Path<BookingFormValues>,
+    },
+  );
+
   const submitValid = handleSubmit(async data => {
     if (consentMissing) return; // the error is already on screen — see `submit`
     if (deferSlot) {
@@ -486,7 +513,7 @@ export function BookingForm({
       // must do so synchronously in this call — this form and its honeypot are
       // still mounted here, and `getSignals()` reads a detached ref once they
       // unmount, which would silently disable the decoy.
-      await onSubmit({ ...data, meetingId, [HOST_CONSENT_KEY]: consented });
+      await onSubmit({ ...data, meetingId, [HOST_CONSENT_KEY]: consented, ...formRescue.submitFields() });
       return;
     }
     await onSubmit({
@@ -497,6 +524,7 @@ export function BookingForm({
       durationMs,
       timezone,
       ...getSignals(),
+      ...formRescue.submitFields(),
     });
   });
 

package/src/components/meeting-scheduler/index.tsx

@@ -42,6 +42,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { ComponentType, ReactNode } from 'react';
 import { useIsHydrated } from '../../hooks/ui/use-is-hydrated';
+import { completeFormRescue } from '../../hooks/use-form-rescue';
 import { useHumanitySignals } from '../../hooks/use-humanity-signals';
 import { BOOKING_IN_FLIGHT_MESSAGE, useMeetingBooking } from '../../hooks/use-meeting-booking';
 import { useToast } from '../../hooks/use-toast';
@@ -53,6 +54,7 @@ import {
   type MeetingHost,
 } from '../../schemas/meeting-booking-schema';
 import { cn } from '../../utils/cn';
+import { FORM_RESCUE_ATTEMPT_FIELD, type FormRescueDefinition } from '../../utils/form-rescue';
 import { formatDurationCompact, formatDateWithTimezone } from '../../utils/format';
 import { Alert, AlertDescription, Button } from '../ui';
 import { BookingForm, BookingFormSkeleton, DEFAULT_SUBMIT_LABEL, type BookingFormProps } from './booking-form';
@@ -150,6 +152,9 @@ export interface HubSpotMeetingSchedulerProps {
    * can pass it across the RSC boundary where a component cannot.
    */
   detailsFormProps?: Pick<BookingFormProps, 'fieldRows' | 'consent'>;
+  /** Form rescue for the details form (`RESCUE_FORMS.meetingBooking`). OPT-IN:
+   *  omitted or `null` saves nothing. */
+  rescue?: FormRescueDefinition | null;
 }
 
 type Step = 'slot' | 'details' | 'confirmed';
@@ -403,6 +408,7 @@ export function HubSpotMeetingScheduler({
   flow = DEFAULT_SCHEDULER_FLOW,
   detailsForm: DetailsForm = BookingForm,
   detailsFormProps,
+  rescue = null,
 }: HubSpotMeetingSchedulerProps) {
   const {
     availability,
@@ -642,6 +648,8 @@ export function HubSpotMeetingScheduler({
         return;
       }
       if (result.ok && result.confirmation) {
+        // The details form may have unmounted (details-first); its attempt id rides the payload.
+        completeFormRescue(rescue, payload[FORM_RESCUE_ATTEMPT_FIELD]);
         setConfirmation(result.confirmation);
         setStep('confirmed');
         onBooked?.(result.confirmation);
@@ -681,7 +689,7 @@ export function HubSpotMeetingScheduler({
         });
       }
     },
-    [book, bookingError, detailsFirst, onBooked, refetchAvailability, resetSignals, toast],
+    [book, bookingError, detailsFirst, onBooked, refetchAvailability, rescue, resetSignals, toast],
   );
 
   const escapeHatch = fallbackUrl ? (
@@ -867,6 +875,7 @@ export function HubSpotMeetingScheduler({
                 onSubmit={detailsFirst ? stashDetails : handleSubmit}
                 honeypotInputProps={honeypotInputProps}
                 getSignals={getSignals}
+                rescue={rescue}
               />
             </div>
           ) : (

package/src/components/tickets/help-center-create-form.tsx

@@ -205,6 +205,8 @@ export function HelpCenterCreateForm({
 
   return (
     <ContactForm
+      // A signed-in support ticket, not a lead: nothing to rescue.
+      rescue={null}
       title="Open a new ticket"
       footerText="The support team typically responds within one business day."
       hideFields={['name', 'email', 'companySize', 'referralSource', 'helpCategory']}

package/src/contexts/endpoints-runtime-context.tsx

@@ -34,6 +34,11 @@ export interface EndpointsRuntime {
   };
   /** POST contact-form submission. */
   contactUrl: string;
+  /** Base of the host's form-rescue draft endpoints: `POST <base>` saves a
+   *  half-filled public form (upsert by `attempt_id`), `GET <base>/resume/<token>` reads one
+   *  back for a resume link (`useFormRescue`). OPTIONAL: a host without them
+   *  omits it and forms keep only this device's local draft. */
+  formDraftsUrl?: string;
   /** GET base of the host's private-storage view proxy
    *  (`<base>/<bucket>/<object>`). `ClaudeEmbed` derives artifact mirror
    *  urls under it (`<base>/design-briefs/<uuid>.html`). OPTIONAL: a host

package/src/hooks/__tests__/use-form-rescue.test.tsx

@@ -0,0 +1,189 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest';
+
+import { EndpointsRuntimeContext, type EndpointsRuntime } from '../../contexts/endpoints-runtime-context';
+import { FORM_RESCUE_DEBOUNCE_MS, RESCUE_FORMS } from '../../utils/form-rescue';
+import { useFormRescue } from '../use-form-rescue';
+
+/**
+ * The hook's contract is a network and privacy contract, so it is asserted on
+ * the fetch spy: one debounced save per burst of typing, only allowlisted
+ * values in the body, no save before anything is filled, no analytics event
+ * carrying a value, and a submit that closes the attempt it saved.
+ */
+
+const runtime: EndpointsRuntime = {
+  announcementsUrl: '/api/announcements',
+  accessCode: { validateUrl: '/v', consumeUrl: '/c' },
+  contactUrl: '/api/contact',
+  formDraftsUrl: '/api/contact/drafts',
+};
+
+function wrapper({ children }: { children: ReactNode }) {
+  return <EndpointsRuntimeContext.Provider value={runtime}>{children}</EndpointsRuntimeContext.Provider>;
+}
+
+const FIELDS = ['name', 'email', 'message'] as const;
+
+let fetchSpy: Mock<(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>>;
+let captures: Array<{ event: string; props: Record<string, unknown> }>;
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  window.localStorage.clear();
+  fetchSpy = vi.fn((_input: RequestInfo | URL, _init?: RequestInit) =>
+    Promise.resolve(new Response(JSON.stringify({ status: 'started' }), { status: 202 })),
+  );
+  vi.stubGlobal('fetch', fetchSpy);
+  captures = [];
+  (window as unknown as { posthog: unknown }).posthog = {
+    capture: (event: string, props: Record<string, unknown>) => captures.push({ event, props }),
+  };
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  delete (window as unknown as { posthog?: unknown }).posthog;
+});
+
+interface SentBody {
+  attempt_id: string;
+  [key: string]: unknown;
+}
+
+function sentBodies(): Array<{ url: string; body: SentBody }> {
+  return fetchSpy.mock.calls
+    .filter(([, init]) => init?.method === 'POST')
+    .map(([url, init]) => ({ url: String(url), body: JSON.parse(String(init?.body)) as SentBody }));
+}
+
+describe('useFormRescue', () => {
+  it('debounces one save per burst with allowlisted values only', () => {
+    const { result } = renderHook(() => useFormRescue({ form: RESCUE_FORMS.contact, fieldNames: FIELDS }), { wrapper });
+
+    act(() => {
+      result.current.track({ name: 'Al', email: '', message: '' }, 'name');
+      result.current.track({ name: 'Alex', email: 'alex@northwind-it.com', message: 'secret text' }, 'message');
+    });
+    expect(sentBodies()).toHaveLength(0);
+
+    act(() => {
+      vi.advanceTimersByTime(FORM_RESCUE_DEBOUNCE_MS);
+    });
+    const sent = sentBodies();
+    expect(sent).toHaveLength(1);
+    expect(sent[0].url).toBe('/api/contact/drafts');
+    expect(sent[0].body.attempt_id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(sent[0].body).toMatchObject({
+      form_id: 'contact',
+      values: { name: 'Alex', email: 'alex@northwind-it.com' },
+      fields_filled: ['name', 'email', 'message'],
+      last_field: 'message',
+      completion_pct: 100,
+    });
+    expect(JSON.stringify(sent[0].body)).not.toContain('secret text');
+  });
+
+  it('sends nothing until a field is filled', () => {
+    const { result } = renderHook(() => useFormRescue({ form: RESCUE_FORMS.contact, fieldNames: FIELDS }), { wrapper });
+    act(() => {
+      result.current.track({ name: '', email: '', message: '' }, 'name');
+      vi.advanceTimersByTime(FORM_RESCUE_DEBOUNCE_MS * 2);
+    });
+    expect(sentBodies()).toHaveLength(0);
+  });
+
+  it('never puts a field value into an analytics event', () => {
+    const { result } = renderHook(() => useFormRescue({ form: RESCUE_FORMS.contact, fieldNames: FIELDS }), { wrapper });
+    act(() => {
+      result.current.track({ name: 'Alex', email: 'alex@northwind-it.com', message: '' }, 'email');
+      vi.advanceTimersByTime(FORM_RESCUE_DEBOUNCE_MS);
+    });
+    expect(captures.map(c => c.event)).toEqual(['form_started', 'form_lead_captured', 'form_progress']);
+    const serialized = JSON.stringify(captures);
+    expect(serialized).not.toContain('alex@northwind-it.com');
+    expect(serialized).not.toContain('Alex"');
+  });
+
+  it('carries the saved attempt into the submit and starts a fresh one after', () => {
+    const { result } = renderHook(() => useFormRescue({ form: RESCUE_FORMS.contact, fieldNames: FIELDS }), { wrapper });
+    act(() => {
+      result.current.track({ name: 'Alex', email: '', message: '' }, 'name');
+      vi.advanceTimersByTime(FORM_RESCUE_DEBOUNCE_MS);
+    });
+    const savedId = sentBodies()[0].body.attempt_id;
+    expect(result.current.submitFields()).toEqual({ form_attempt_id: savedId });
+
+    act(() => result.current.complete());
+    expect(window.localStorage.getItem('form-rescue:v1:contact')).toBeNull();
+    expect(result.current.submitFields().form_attempt_id).not.toBe(savedId);
+  });
+
+  it('restores this device’s draft and keeps its attempt', () => {
+    window.localStorage.setItem(
+      'form-rescue:v1:contact',
+      JSON.stringify({
+        attemptId: '6f1c2a7e-3b9d-4e21-9a4f-0c8d5e7b1a22',
+        values: { email: 'alex@northwind-it.com', password: 'never' },
+        savedAt: Date.now(),
+      }),
+    );
+    const onRestore = vi.fn();
+    const { result } = renderHook(() => useFormRescue({ form: RESCUE_FORMS.contact, fieldNames: FIELDS, onRestore }), {
+      wrapper,
+    });
+    expect(onRestore).toHaveBeenCalledWith({ email: 'alex@northwind-it.com' });
+    expect(result.current.submitFields()).toEqual({ form_attempt_id: '6f1c2a7e-3b9d-4e21-9a4f-0c8d5e7b1a22' });
+  });
+
+  it('prefills from a resume link and sends its token with the submit', async () => {
+    vi.useRealTimers();
+    // vitest.setup replaces `window.location` with a plain object; set its search directly.
+    const location = window.location as unknown as { search: string; pathname: string };
+    location.pathname = '/contact';
+    location.search = '?resume=k3Xq9vT2mB7wYp1sLr8dQa';
+    fetchSpy.mockImplementation(() =>
+      Promise.resolve(
+        new Response(JSON.stringify({ form_id: 'contact', values: { email: 'alex@northwind-it.com' } }), {
+          status: 200,
+        }),
+      ),
+    );
+    const onRestore = vi.fn();
+    const { result } = renderHook(() => useFormRescue({ form: RESCUE_FORMS.contact, fieldNames: FIELDS, onRestore }), {
+      wrapper,
+    });
+    await waitFor(() => expect(onRestore).toHaveBeenCalledWith({ email: 'alex@northwind-it.com' }));
+    expect(String(fetchSpy.mock.calls[0][0])).toBe('/api/contact/drafts/resume/k3Xq9vT2mB7wYp1sLr8dQa');
+    expect(result.current.submitFields()).toMatchObject({ form_resume_token: 'k3Xq9vT2mB7wYp1sLr8dQa' });
+    expect(captures.map(c => c.event)).toContain('form_resumed');
+    location.pathname = '/';
+    location.search = '';
+  });
+
+  it('does nothing when rescue is off', () => {
+    const { result } = renderHook(() => useFormRescue({ form: null, fieldNames: FIELDS }), { wrapper });
+    act(() => {
+      result.current.track({ name: 'Alex', email: 'alex@northwind-it.com', message: '' }, 'name');
+      vi.advanceTimersByTime(FORM_RESCUE_DEBOUNCE_MS);
+    });
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(result.current.submitFields()).toEqual({});
+  });
+
+  it('saves once more with keepalive when the tab is hidden', () => {
+    const { result } = renderHook(() => useFormRescue({ form: RESCUE_FORMS.contact, fieldNames: FIELDS }), { wrapper });
+    act(() => {
+      result.current.track({ name: 'Alex', email: '', message: '' }, 'name');
+    });
+    act(() => {
+      window.dispatchEvent(new Event('pagehide'));
+    });
+    const puts = fetchSpy.mock.calls.filter(([, init]) => init?.method === 'POST');
+    expect(puts).toHaveLength(1);
+    expect(puts[0][1]?.keepalive).toBe(true);
+    expect(captures.map(c => c.event)).toContain('form_abandoned');
+  });
+});