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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.672",
+  "version": "0.0.673-2406.7238.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

@@ -93,6 +93,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.",
+  rescueFormId: 'case_study_pitch',
 } satisfies Partial<ContactFormProps>;
 
 export function ShareExperienceSection({

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

@@ -22,9 +22,10 @@
  */
 
 import { zodResolver } from '@hookform/resolvers/zod';
-import { useState, type ReactNode } from 'react';
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
 import { useForm, Controller } from 'react-hook-form';
 import { useContactSubmission } from '../../hooks/use-contact-submission';
+import { useFormRescue } from '../../hooks/use-form-rescue';
 import { useHumanitySignals } from '../../hooks/use-humanity-signals';
 import {
   ContactSchema,
@@ -33,6 +34,7 @@ import {
   referralSourceOptions,
   defaultHelpCategoryOptions,
 } from '../../schemas/contact-schema';
+import type { FormRescueFormId } 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,10 @@ export interface ContactFormProps {
   submitSuccessLabel?: string;
   successRedirectUrl?: string;
   successToastMessage?: string;
+  /** Which public form this is, for form rescue (a half-filled form is saved so
+   *  the team can follow up). OPT-IN: omitted or `null` saves nothing, so a host
+   *  that has not chosen rescue never starts storing what visitors type. */
+  rescueFormId?: FormRescueFormId | null;
 }
 
 export function ContactForm({
@@ -155,6 +161,7 @@ export function ContactForm({
   submitSuccessLabel = 'Message Sent!',
   successRedirectUrl = '/blog#community',
   successToastMessage = 'Redirecting you to join our community...',
+  rescueFormId = null,
 }: ContactFormProps = {}) {
   // Attachments staging — same hook the chat composer + ticket
   // detail-drawer composer use. Files upload to Supabase as soon as
@@ -191,6 +198,9 @@ export function ContactForm({
     control,
     formState: { errors },
     reset,
+    watch,
+    getValues,
+    setValue,
   } = useForm<ContactFormData>({
     resolver: zodResolver(ContactSchema),
     defaultValues: {
@@ -202,11 +212,36 @@ export function ContactForm({
     },
   });
 
+  // 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 = useFormRescue({
+    formId: rescueFormId,
+    fieldNames: rescueFieldNames,
+    getSignals,
+    onRestore: values => {
+      for (const field of rescueFieldNames) {
+        const value = values[field];
+        if (value && !getValues(field)) setValue(field, value);
+      }
+    },
+  });
+  useEffect(() => {
+    const subscription = watch((values, { name }) => rescue.track(values, name));
+    return () => subscription.unsubscribe();
+  }, [watch, rescue]);
+
   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 +253,7 @@ export function ContactForm({
       } else {
         await builtInSubmission.submit(payload);
       }
+      rescue.complete();
       onSubmitSuccess?.();
       reset();
       resetSignals();

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 { FormRescueFormId } 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). OPT-IN: omitted or `null` saves nothing. */
+  rescueFormId?: FormRescueFormId | null;
 }
 
 /**
@@ -90,6 +101,7 @@ export function WaitlistForm({
   invalidPhoneHint = 'Invalid phone number format.',
   termsOfServiceUrl,
   privacyPolicyUrl,
+  rescueFormId = 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({
+    formId: rescueFormId,
+    // 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

@@ -443,6 +443,7 @@ export function DocumentRequestModal({
               with access, usually within one business day.
             </p>
             <ContactForm
+              rescueFormId="trust_center_request"
               title=""
               noBorder
               noPadding

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

@@ -370,6 +370,9 @@ export interface BookingFormProps {
   /** From useHumanitySignals — parent owns the instance so it can resetSignals(). */
   honeypotInputProps: { ref: Ref<HTMLInputElement>; name: string };
   getSignals: () => Record<string, string | number>;
+  /** Called on every edit with the answers flattened (declared questions beside
+   *  the built-ins) and the edited field's name — the parent's form rescue. */
+  onValuesChange?: (values: Record<string, unknown>, changedField: string | null) => void;
 }
 
 /**
@@ -402,6 +405,7 @@ export function BookingForm({
   onSubmit,
   honeypotInputProps,
   getSignals,
+  onValuesChange,
 }: BookingFormProps) {
   const { formFields, legalConsent } = availability;
   // Every declared question resolved to a control (`resolveFormFieldControl`) —
@@ -431,6 +435,7 @@ export function BookingForm({
     handleSubmit,
     setValue,
     getValues,
+    watch,
     formState: { errors },
   } = useForm<BookingFormValues>({
     resolver: zodResolver(schema),
@@ -479,6 +484,15 @@ export function BookingForm({
     );
   }, [consentDefaults, priorConsents, getValues, setValue]);
 
+  useEffect(() => {
+    if (!onValuesChange) return undefined;
+    const subscription = watch((values, { name }) => {
+      const answers = (values.formFields ?? {}) as Record<string, unknown>;
+      onValuesChange({ ...values, ...answers }, name ? name.replace(/^formFields\./, '') : null);
+    });
+    return () => subscription.unsubscribe();
+  }, [watch, onValuesChange]);
+
   const submitValid = handleSubmit(async data => {
     if (consentMissing) return; // the error is already on screen — see `submit`
     if (deferSlot) {

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

@@ -42,17 +42,21 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { ComponentType, ReactNode } 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 { BOOKING_IN_FLIGHT_MESSAGE, useMeetingBooking } from '../../hooks/use-meeting-booking';
 import { useToast } from '../../hooks/use-toast';
 import {
   blocksNativeBooking,
+  BUILT_IN_BOOKING_FIELDS,
+  normalizeFormFields,
   type BookingConfirmation,
   type MeetingAvailability,
   type MeetingBookingErrorCode,
   type MeetingHost,
 } from '../../schemas/meeting-booking-schema';
 import { cn } from '../../utils/cn';
+import type { FormRescueFormId } 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 +154,9 @@ export interface HubSpotMeetingSchedulerProps {
    * can pass it across the RSC boundary where a component cannot.
    */
   detailsFormProps?: Pick<BookingFormProps, 'fieldRows' | 'consent'>;
+  /** Form rescue (save the half-filled booking form for follow-up). OPT-IN:
+   *  omitted or `null` saves nothing. */
+  rescueFormId?: FormRescueFormId | null;
 }
 
 type Step = 'slot' | 'details' | 'confirmed';
@@ -403,6 +410,7 @@ export function HubSpotMeetingScheduler({
   flow = DEFAULT_SCHEDULER_FLOW,
   detailsForm: DetailsForm = BookingForm,
   detailsFormProps,
+  rescueFormId = null,
 }: HubSpotMeetingSchedulerProps) {
   const {
     availability,
@@ -492,6 +500,30 @@ export function HubSpotMeetingScheduler({
   const { honeypotInputProps, getSignals, resetSignals } = useHumanitySignals();
   const { toast } = useToast();
 
+  // Form rescue lives HERE, not in the form: in details-first the form unmounts
+  // before the POST, and the attempt must survive it. The form reports edits
+  // (`onValuesChange`); a restored draft remounts it with the answers seeded.
+  const rescueFieldNames = useMemo(
+    () => [
+      ...BUILT_IN_BOOKING_FIELDS.map(field => field.name),
+      ...normalizeFormFields(availability?.formFields ?? []).map(field => field.name),
+    ],
+    [availability?.formFields],
+  );
+  const [restored, setRestored] = useState<{ version: number; values: Record<string, unknown> } | null>(null);
+  const rescue = useFormRescue({
+    formId: rescueFormId,
+    fieldNames: rescueFieldNames,
+    getSignals,
+    onRestore: values => {
+      const { email, firstName, lastName, ...answers } = values;
+      setRestored(prev => ({
+        version: (prev?.version ?? 0) + 1,
+        values: { email: email ?? '', firstName: firstName ?? '', lastName: lastName ?? '', formFields: answers },
+      }));
+    },
+  });
+
   // Reset the machine when the host switches links. Adjusted while rendering —
   // React's documented pattern for a prop-driven reset — so the swapped-in link
   // never paints a frame of the previous link's chosen day, slot or
@@ -634,7 +666,7 @@ export function HubSpotMeetingScheduler({
       // visible SLOT_TAKEN alert on its way to being ignored.
       const priorError = bookingError;
       setBookingError(null);
-      const result = await book(payload);
+      const result = await book({ ...payload, ...rescue.submitFields() });
 
       // Not an error: the hook's in-flight guard. No toast, no step change.
       if (!result.ok && result.message === BOOKING_IN_FLIGHT_MESSAGE) {
@@ -642,6 +674,7 @@ export function HubSpotMeetingScheduler({
         return;
       }
       if (result.ok && result.confirmation) {
+        rescue.complete();
         setConfirmation(result.confirmation);
         setStep('confirmed');
         onBooked?.(result.confirmation);
@@ -681,7 +714,7 @@ export function HubSpotMeetingScheduler({
         });
       }
     },
-    [book, bookingError, detailsFirst, onBooked, refetchAvailability, resetSignals, toast],
+    [book, bookingError, detailsFirst, onBooked, refetchAvailability, rescue, resetSignals, toast],
   );
 
   const escapeHatch = fallbackUrl ? (
@@ -853,6 +886,7 @@ export function HubSpotMeetingScheduler({
                 </p>
               )}
               <DetailsForm
+                key={restored?.version ?? 0}
                 {...detailsFormProps}
                 availability={availability}
                 meetingId={meetingId}
@@ -862,11 +896,12 @@ export function HubSpotMeetingScheduler({
                 deferSlot={detailsFirst}
                 submitLabel={preset.submitLabel}
                 footerNote={preset.footerNote}
-                initialValues={detailsFirst ? stash?.payload : undefined}
+                initialValues={(detailsFirst ? stash?.payload : undefined) ?? restored?.values}
                 isSubmitting={isSubmitting}
                 onSubmit={detailsFirst ? stashDetails : handleSubmit}
                 honeypotInputProps={honeypotInputProps}
                 getSignals={getSignals}
+                onValuesChange={rescue.track}
               />
             </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.
+      rescueFormId={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 } 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({ formId: '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({ formId: '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({ formId: '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({ formId: '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({ formId: '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({ formId: '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({ formId: 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({ formId: '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');
+  });
+});

package/src/hooks/index.ts

@@ -41,3 +41,6 @@ export * from './use-scroll-to-hash';
 // Invisible bot-protection client primitive (honeypot ref + submit-timing).
 // Pairs with the server-safe decision fn in `utils/humanity-signals`.
 export * from './use-humanity-signals';
+// Saves a half-filled public form so a visitor who leaves can be followed up with.
+// Pairs with the server-safe rules in `utils/form-rescue`.
+export * from './use-form-rescue';