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

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

@@ -0,0 +1,91 @@
+import { act, renderHook } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { useForm } from 'react-hook-form';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { EndpointsRuntimeContext, type EndpointsRuntime } from '../../contexts/endpoints-runtime-context';
+import { FORM_RESCUE_DEBOUNCE_MS, RESCUE_FORMS } from '../../utils/form-rescue';
+import { useRescuedForm } from '../use-rescued-form';
+
+/**
+ * The generic react-hook-form adapter is what every rescued form uses, so its
+ * contract is tested once here: edits are tracked (nested answers too), a
+ * restored draft fills only EMPTY fields, and hidden fields are never sent.
+ */
+
+const runtime: EndpointsRuntime = {
+  announcementsUrl: '/a',
+  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>;
+}
+
+interface Values {
+  name: string;
+  email: string;
+  formFields: { company: string };
+  secret: string;
+}
+
+function useFixture(defaults: Partial<Values> = {}) {
+  const form = useForm<Values>({
+    defaultValues: { name: '', email: '', formFields: { company: '' }, secret: 'hidden', ...defaults },
+  });
+  const rescue = useRescuedForm(form, {
+    rescue: RESCUE_FORMS.meetingBooking,
+    fields: ['name', 'email', 'company'],
+    fieldPath: name => (name === 'company' ? 'formFields.company' : (name as 'name' | 'email')),
+  });
+  return { form, rescue };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  window.localStorage.clear();
+  vi.stubGlobal(
+    'fetch',
+    vi.fn((_input: RequestInfo | URL, _init?: RequestInit) => Promise.resolve(new Response('{}', { status: 202 }))),
+  );
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe('useRescuedForm', () => {
+  it('tracks edits, nested answers included, and never a hidden field', () => {
+    const { result } = renderHook(() => useFixture(), { wrapper });
+    act(() => {
+      result.current.form.setValue('email', 'alex@northwind-it.com');
+      result.current.form.setValue('formFields.company', 'Northwind IT');
+      vi.advanceTimersByTime(FORM_RESCUE_DEBOUNCE_MS);
+    });
+    const calls = vi.mocked(fetch).mock.calls;
+    expect(calls).toHaveLength(1);
+    const body = JSON.parse(String(calls[0][1]?.body)) as { values: Record<string, string>; form_id: string };
+    expect(body.form_id).toBe('meeting_booking');
+    expect(body.values).toEqual({ email: 'alex@northwind-it.com', company: 'Northwind IT' });
+    expect(JSON.stringify(body)).not.toContain('hidden');
+  });
+
+  it('restores a local draft into empty fields only, at their real paths', () => {
+    window.localStorage.setItem(
+      'form-rescue:v1:meeting_booking',
+      JSON.stringify({
+        attemptId: '6f1c2a7e-3b9d-4e21-9a4f-0c8d5e7b1a22',
+        values: { name: 'Alex', email: 'alex@northwind-it.com', company: 'Northwind IT' },
+        savedAt: Date.now(),
+      }),
+    );
+    const { result } = renderHook(() => useFixture({ name: 'Typed Already' }), { wrapper });
+    expect(result.current.form.getValues('name')).toBe('Typed Already');
+    expect(result.current.form.getValues('email')).toBe('alex@northwind-it.com');
+    expect(result.current.form.getValues('formFields.company')).toBe('Northwind IT');
+    expect(result.current.rescue.submitFields()).toEqual({ form_attempt_id: '6f1c2a7e-3b9d-4e21-9a4f-0c8d5e7b1a22' });
+  });
+});

package/src/hooks/index.ts

@@ -41,3 +41,7 @@ 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';
+export * from './use-rescued-form';

package/src/hooks/use-form-rescue.ts

@@ -0,0 +1,330 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useEndpointsRuntime } from '../contexts/endpoints-runtime-context';
+import { contentFetch } from '../utils/embed-content-fetch';
+import {
+  captureFormRescueEvent,
+  FORM_RESCUE_ATTEMPT_FIELD,
+  FORM_RESCUE_DEBOUNCE_MS,
+  FORM_RESCUE_EVENTS,
+  FORM_RESCUE_RESUME_FIELD,
+  FORM_RESCUE_RESUME_PARAM,
+  filledRescueFields,
+  isFormAttemptId,
+  isRescueEmail,
+  rescueCompletionPct,
+  sanitizeRescueFieldName,
+  sanitizeRescueValues,
+  type FormDraftProgress,
+  type FormDraftResumeResponse,
+  type FormDraftSaveRequest,
+  type FormRescueDefinition,
+} from '../utils/form-rescue';
+
+/** A local draft older than this is ignored and replaced. */
+const LOCAL_DRAFT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const STORAGE_PREFIX = 'form-rescue:v1:';
+const UTM_KEYS = ['source', 'medium', 'campaign', 'content', 'term'] as const;
+
+interface LocalDraft {
+  attemptId: string;
+  values: Record<string, string>;
+  savedAt: number;
+}
+
+export interface UseFormRescueOptions {
+  /** Which form this is (`defineRescueForm`); `null` turns rescue off. */
+  form: FormRescueDefinition | null;
+  /** Every field the visitor can see. Hidden fields are never listed, so never sent. */
+  fieldNames: readonly string[];
+  /** Called once after mount with values from a resume link, else from this device's local draft. */
+  onRestore?: (values: Record<string, string>) => void;
+  /** The form's humanity signals, so the draft endpoint can run the same bot gate as the submit. */
+  getSignals?: () => Record<string, string | number>;
+}
+
+export interface FormRescueHandle {
+  /** Report the form's current values after a change (`lastField` = the field just edited). */
+  track: (values: Record<string, unknown>, lastField?: string | null) => void;
+  /** Keys to spread into the SUBMIT body so the host closes this attempt's draft. */
+  submitFields: () => Record<string, string>;
+  /** Call after a successful submit: clears the local draft and starts a fresh attempt. */
+  complete: () => void;
+}
+
+function newAttemptId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  // RFC 4122 v4 from getRandomValues for older browsers.
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function readLocalDraft(formId: string): LocalDraft | null {
+  try {
+    const raw = window.localStorage.getItem(STORAGE_PREFIX + formId);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<LocalDraft>;
+    if (!isFormAttemptId(parsed.attemptId) || typeof parsed.savedAt !== 'number') return null;
+    if (Date.now() - parsed.savedAt > LOCAL_DRAFT_TTL_MS) return null;
+    return { attemptId: parsed.attemptId, values: sanitizeRescueValues(parsed.values), savedAt: parsed.savedAt };
+  } catch {
+    return null;
+  }
+}
+
+function writeLocalDraft(formId: string, draft: LocalDraft): void {
+  try {
+    window.localStorage.setItem(STORAGE_PREFIX + formId, JSON.stringify(draft));
+  } catch {
+    // Storage full or blocked: the server draft still works.
+  }
+}
+
+function clearLocalDraft(formId: string): void {
+  try {
+    window.localStorage.removeItem(STORAGE_PREFIX + formId);
+  } catch {
+    // Nothing to clear.
+  }
+}
+
+/**
+ * Close a rescue attempt after a successful submit, for a form that has already
+ * unmounted by then (the meeting scheduler's details-first flow): clears this
+ * device's draft and reports the submit. The hook's `complete` calls it too.
+ */
+export function completeFormRescue(form: FormRescueDefinition | null, attemptId?: unknown): void {
+  if (!form || typeof window === 'undefined') return;
+  const local = readLocalDraft(form.id);
+  captureFormRescueEvent(FORM_RESCUE_EVENTS.submitted, {
+    form_id: form.id,
+    attempt_id: isFormAttemptId(attemptId) ? attemptId : (local?.attemptId ?? null),
+  });
+  clearLocalDraft(form.id);
+}
+
+function readUtm(): FormDraftSaveRequest['utm'] {
+  try {
+    const params = new URLSearchParams(window.location.search);
+    const utm: NonNullable<FormDraftSaveRequest['utm']> = {};
+    for (const key of UTM_KEYS) {
+      const value = params.get(`utm_${key}`);
+      if (value) utm[key] = value.slice(0, 200);
+    }
+    return Object.keys(utm).length ? utm : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * useFormRescue — saves a public form's progress so a visitor who leaves
+ * before submitting can be followed up with, and restores it when they return.
+ *
+ * Every public lead form calls it the same way (next to `useHumanitySignals`):
+ *
+ *   const rescue = useFormRescue({ form: RESCUE_FORMS.waitlist, fieldNames, onRestore, getSignals })
+ *   // on change: rescue.track(values, changedField)
+ *   // submit:    body = { ...data, ...getSignals(), ...rescue.submitFields() }
+ *   // success:   rescue.complete()
+ *
+ * Saves go to the host's `EndpointsRuntime.formDraftsUrl` (debounced, plus one
+ * final keepalive save when the tab is hidden). A host that does not provide
+ * the url gets the local draft only. Nothing here can block or delay a submit:
+ * every network and storage call is fire-and-forget and swallows its errors.
+ */
+export function useFormRescue({ form, fieldNames, onRestore, getSignals }: UseFormRescueOptions): FormRescueHandle {
+  const draftsUrl = useEndpointsRuntime()?.formDraftsUrl;
+  const formId = form?.id ?? null;
+
+  const attemptIdRef = useRef<string | null>(null);
+  const resumeTokenRef = useRef<string | null>(null);
+  const latestRef = useRef<FormDraftProgress | null>(null);
+  const dirtyRef = useRef(false);
+  const startedRef = useRef(false);
+  const leadCapturedRef = useRef(false);
+  const completedRef = useRef(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Callers pass inline arrays and callbacks; read them through refs so the
+  // returned handle stays stable and effects run once. Written in an effect
+  // (declared first, so it runs before the restore below), never during render.
+  const fieldNamesRef = useRef(fieldNames);
+  const onRestoreRef = useRef(onRestore);
+  const getSignalsRef = useRef(getSignals);
+  useEffect(() => {
+    fieldNamesRef.current = fieldNames;
+    onRestoreRef.current = onRestore;
+    getSignalsRef.current = getSignals;
+  });
+
+  const attemptId = useCallback((): string => {
+    if (!attemptIdRef.current) attemptIdRef.current = newAttemptId();
+    return attemptIdRef.current;
+  }, []);
+
+  const send = useCallback(
+    (keepalive: boolean) => {
+      if (!formId || !draftsUrl || !dirtyRef.current || completedRef.current || !latestRef.current) return;
+      dirtyRef.current = false;
+      const body: FormDraftSaveRequest = {
+        attempt_id: attemptId(),
+        form_id: formId,
+        ...latestRef.current,
+        source_path: typeof window !== 'undefined' ? window.location.pathname : '/',
+        utm: readUtm(),
+      };
+      try {
+        void contentFetch(draftsUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ ...body, ...(getSignalsRef.current?.() ?? {}) }),
+          keepalive,
+        }).catch(() => undefined);
+      } catch {
+        // A failed save is retried by the next change.
+      }
+      captureFormRescueEvent(FORM_RESCUE_EVENTS.progress, {
+        form_id: formId,
+        attempt_id: attemptId(),
+        fields_filled: body.fields_filled,
+        last_field: body.last_field,
+        completion_pct: body.completion_pct,
+      });
+    },
+    [attemptId, draftsUrl, formId],
+  );
+
+  // Restore once on mount: a resume link wins over this device's local draft.
+  useEffect(() => {
+    if (!formId || typeof window === 'undefined') return undefined;
+    let cancelled = false;
+    const token = new URLSearchParams(window.location.search).get(FORM_RESCUE_RESUME_PARAM);
+
+    const restoreLocal = () => {
+      const local = readLocalDraft(formId);
+      if (!local) return;
+      attemptIdRef.current = local.attemptId;
+      if (Object.keys(local.values).length) onRestoreRef.current?.(local.values);
+    };
+
+    if (token && draftsUrl && /^[A-Za-z0-9_-]{16,128}$/.test(token)) {
+      contentFetch(`${draftsUrl}/resume/${encodeURIComponent(token)}`)
+        .then(async res => (res.ok ? ((await res.json()) as FormDraftResumeResponse) : null))
+        .then(data => {
+          if (cancelled) return;
+          if (!data || data.form_id !== formId) {
+            restoreLocal();
+            return;
+          }
+          resumeTokenRef.current = token;
+          onRestoreRef.current?.(sanitizeRescueValues(data.values));
+          captureFormRescueEvent(FORM_RESCUE_EVENTS.resumed, { form_id: formId, attempt_id: attemptId() });
+        })
+        .catch(() => {
+          if (!cancelled) restoreLocal();
+        });
+    } else {
+      restoreLocal();
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [attemptId, draftsUrl, formId]);
+
+  // Final save when the visitor hides or leaves the tab.
+  useEffect(() => {
+    if (!formId || typeof document === 'undefined') return undefined;
+    const onHide = () => {
+      if (completedRef.current || !startedRef.current) return;
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+      send(true);
+      captureFormRescueEvent(FORM_RESCUE_EVENTS.abandoned, {
+        form_id: formId,
+        attempt_id: attemptId(),
+        last_field: latestRef.current?.last_field ?? null,
+        completion_pct: latestRef.current?.completion_pct ?? 0,
+      });
+    };
+    const onVisibility = () => {
+      if (document.visibilityState === 'hidden') onHide();
+    };
+    document.addEventListener('visibilitychange', onVisibility);
+    window.addEventListener('pagehide', onHide);
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibility);
+      window.removeEventListener('pagehide', onHide);
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [attemptId, formId, send]);
+
+  const track = useCallback(
+    (values: Record<string, unknown>, lastField?: string | null) => {
+      if (!formId || completedRef.current) return;
+      const names = fieldNamesRef.current;
+      const visible: Record<string, unknown> = {};
+      for (const name of names) visible[name] = values[name];
+      const filled = filledRescueFields(visible, names);
+      if (!filled.length) return;
+
+      if (!startedRef.current) {
+        startedRef.current = true;
+        captureFormRescueEvent(FORM_RESCUE_EVENTS.started, { form_id: formId, attempt_id: attemptId() });
+      }
+      const clean = sanitizeRescueValues(visible);
+      if (!leadCapturedRef.current && isRescueEmail(clean.email)) {
+        leadCapturedRef.current = true;
+        captureFormRescueEvent(FORM_RESCUE_EVENTS.leadCaptured, { form_id: formId, attempt_id: attemptId() });
+      }
+      latestRef.current = {
+        values: clean,
+        fields_filled: filled,
+        last_field: sanitizeRescueFieldName(lastField),
+        completion_pct: rescueCompletionPct(filled.length, names.length),
+      };
+      dirtyRef.current = true;
+      writeLocalDraft(formId, { attemptId: attemptId(), values: clean, savedAt: Date.now() });
+
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        send(false);
+      }, FORM_RESCUE_DEBOUNCE_MS);
+    },
+    [attemptId, formId, send],
+  );
+
+  const submitFields = useCallback((): Record<string, string> => {
+    if (!formId) return {};
+    return {
+      [FORM_RESCUE_ATTEMPT_FIELD]: attemptId(),
+      ...(resumeTokenRef.current ? { [FORM_RESCUE_RESUME_FIELD]: resumeTokenRef.current } : {}),
+    };
+  }, [attemptId, formId]);
+
+  const complete = useCallback(() => {
+    if (!formId) return;
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    completeFormRescue(form, attemptId());
+    // A fresh attempt for a second submission from the same page.
+    attemptIdRef.current = null;
+    resumeTokenRef.current = null;
+    latestRef.current = null;
+    dirtyRef.current = false;
+    startedRef.current = false;
+    leadCapturedRef.current = false;
+  }, [attemptId, form, formId]);
+
+  return useMemo(() => ({ track, submitFields, complete }), [track, submitFields, complete]);
+}

package/src/hooks/use-rescued-form.ts

@@ -0,0 +1,71 @@
+'use client';
+
+import { useEffect } from 'react';
+import type { FieldValues, Path, PathValue, UseFormReturn } from 'react-hook-form';
+import type { FormRescueDefinition } from '../utils/form-rescue';
+import { useFormRescue, type FormRescueHandle } from './use-form-rescue';
+
+export interface UseRescuedFormOptions<T extends FieldValues> {
+  /** The form's definition (`defineRescueForm` / `RESCUE_FORMS`); `null` turns rescue off. */
+  rescue: FormRescueDefinition | null;
+  /** The fields the visitor can see, by the name a draft stores them under. Hidden fields are never listed. */
+  fields: readonly string[];
+  /** The form's humanity signals, so draft saves pass the same bot gate as the submit. */
+  getSignals?: () => Record<string, string | number>;
+  /** Where a stored field lives in the form, when it is nested (`company` → `formFields.company`). Default: the same name. */
+  fieldPath?: (name: string) => Path<T>;
+}
+
+/** One level of nesting flattened (`{ formFields: { company } }` → `{ company }`), so nested answers read like top-level ones. */
+function flattenOneLevel(values: Record<string, unknown>): Record<string, unknown> {
+  const flat: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(values)) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) Object.assign(flat, value);
+    else flat[key] = value;
+  }
+  return flat;
+}
+
+/**
+ * useRescuedForm — form rescue for ANY react-hook-form form, in one call.
+ *
+ * Wires what every rescued form needs so no form hand-rolls it: every edit is
+ * tracked (`watch`), a resume link or this device's draft fills the empty
+ * fields (`setValue`), and the handle's `submitFields()` / `complete()` close
+ * the attempt on submit. A form that is not react-hook-form uses
+ * `useFormRescue` directly.
+ *
+ *   const rescue = useRescuedForm(form, { rescue: RESCUE_FORMS.contact, fields, getSignals })
+ *   // submit:  body = { ...data, ...getSignals(), ...rescue.submitFields() }
+ *   // success: rescue.complete()
+ */
+export function useRescuedForm<T extends FieldValues>(
+  form: Pick<UseFormReturn<T>, 'watch' | 'getValues' | 'setValue'>,
+  { rescue, fields, getSignals, fieldPath }: UseRescuedFormOptions<T>,
+): FormRescueHandle {
+  const { watch, getValues, setValue } = form;
+
+  const handle = useFormRescue({
+    form: rescue,
+    fieldNames: fields,
+    getSignals,
+    onRestore: values => {
+      for (const name of fields) {
+        const value = values[name];
+        if (!value) continue;
+        const path = fieldPath ? fieldPath(name) : (name as Path<T>);
+        // Only an empty field is filled: never overwrite what the visitor typed.
+        if (!getValues(path)) setValue(path, value as PathValue<T, Path<T>>, { shouldDirty: true });
+      }
+    },
+  });
+
+  useEffect(() => {
+    const subscription = watch((values, { name }) => {
+      handle.track(flattenOneLevel(values), name ? (name.split('.').pop() ?? null) : null);
+    });
+    return () => subscription.unsubscribe();
+  }, [watch, handle]);
+
+  return handle;
+}

package/src/utils/__tests__/form-rescue.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  filledRescueFields,
+  isExcludedRescueField,
+  isRescueEmail,
+  rescueCompletionPct,
+  sanitizeRescueFieldName,
+  sanitizeRescueValues,
+  FORM_RESCUE_MAX_VALUE_CHARS,
+  RESCUE_FORMS,
+  defineRescueForm,
+  getRescueForm,
+  listRescueForms,
+} from '../form-rescue';
+
+/**
+ * These rules run on BOTH sides: the browser before a draft is sent and the
+ * host before it is stored. The cases are the ones the privacy contract rests
+ * on: nothing outside the allowlist is ever a value, and a credential field is
+ * never even reported by name.
+ */
+describe('sanitizeRescueValues', () => {
+  it('keeps only allowlisted contact fields, trimmed', () => {
+    expect(
+      sanitizeRescueValues({
+        email: '  alex@northwind-it.com ',
+        name: 'Alex',
+        company: 'Northwind IT',
+        message: 'free text never kept',
+        phone: '+15550100',
+        password: 'hunter2',
+        card_number: '4242424242424242',
+      }),
+    ).toEqual({ email: 'alex@northwind-it.com', name: 'Alex', company: 'Northwind IT' });
+  });
+
+  it('caps every value', () => {
+    const out = sanitizeRescueValues({ company: 'x'.repeat(500) });
+    expect(out.company).toHaveLength(FORM_RESCUE_MAX_VALUE_CHARS);
+  });
+
+  it('drops non-strings and empties', () => {
+    expect(sanitizeRescueValues({ email: 42, name: '   ', company: { a: 1 } })).toEqual({});
+    expect(sanitizeRescueValues(null)).toEqual({});
+  });
+});
+
+describe('filledRescueFields', () => {
+  it('reports visible filled fields by name, never credentials', () => {
+    expect(
+      filledRescueFields({ email: 'a@b.co', message: 'hi', password: 'x', companySize: '' }, [
+        'email',
+        'message',
+        'password',
+        'companySize',
+      ]),
+    ).toEqual(['email', 'message']);
+  });
+
+  it('counts a nested answer group as filled when any answer is', () => {
+    expect(filledRescueFields({ formFields: { a: '', b: 'yes' } }, ['formFields'])).toEqual(['formFields']);
+  });
+});
+
+describe('field and id checks', () => {
+  it('excludes credential and payment names', () => {
+    for (const name of [
+      'password',
+      'passcode',
+      'cardNumber',
+      'cvv',
+      'ssn',
+      'iban',
+      'apiToken',
+      'client_secret',
+      'otp',
+    ]) {
+      expect(isExcludedRescueField(name)).toBe(true);
+    }
+    for (const name of ['email', 'company', 'companySize', 'jobtitle']) {
+      expect(isExcludedRescueField(name)).toBe(false);
+    }
+  });
+
+  it('validates emails the way the contact table does', () => {
+    expect(isRescueEmail('alex@northwind-it.com')).toBe(true);
+    expect(isRescueEmail('alex@')).toBe(false);
+    expect(isRescueEmail(undefined)).toBe(false);
+  });
+
+  it('bounds field names', () => {
+    expect(sanitizeRescueFieldName('company_size')).toBe('company_size');
+    expect(sanitizeRescueFieldName('<script>')).toBeNull();
+    expect(sanitizeRescueFieldName('password')).toBeNull();
+  });
+
+  it('computes completion as a bounded percentage', () => {
+    expect(rescueCompletionPct(3, 4)).toBe(75);
+    expect(rescueCompletionPct(0, 0)).toBe(0);
+    expect(rescueCompletionPct(9, 4)).toBe(100);
+  });
+});
+
+describe('rescue form definitions', () => {
+  it('knows the lib forms and refuses unknown ids', () => {
+    expect(getRescueForm('contact')).toBe(RESCUE_FORMS.contact);
+    expect(getRescueForm('meeting_booking')?.label).toBe('Meeting booking');
+    expect(getRescueForm('anything_else')).toBeNull();
+    expect(getRescueForm(42)).toBeNull();
+  });
+
+  it('lets a host add its own form beside it, with no central list', () => {
+    const joinForm = defineRescueForm({ id: 'host_join', label: 'Join form' });
+    expect(getRescueForm('host_join')).toBe(joinForm);
+    expect(listRescueForms()).toContain(joinForm);
+  });
+
+  it('is idempotent for the same definition and refuses a conflicting one', () => {
+    expect(defineRescueForm({ id: 'contact', label: 'Contact form' })).toBe(RESCUE_FORMS.contact);
+    expect(() => defineRescueForm({ id: 'contact', label: 'Something else' })).toThrow(/already defined/);
+    expect(() => defineRescueForm({ id: 'Bad Id!', label: 'x' })).toThrow(/invalid form id/);
+  });
+});