feat: CAPTCHA, hidden tracking field, preview fix, tests + CI (#70)

* feat: CAPTCHA, hidden tracking field, preview fix, tests + CI

- fix(admin): Preview modal scrolls internally instead of overflowing
  on tall forms (flex: 1 / minHeight: 0 / alignItems: flex-start).
- feat(captcha): per-form CAPTCHA (Cloudflare Turnstile or Google
  reCAPTCHA v2). Server-side verify (fail-closed), secret key never
  exposed to the browser, CSP relaxed for the provider on the public
  page, client guard blocks submit without a token. Saving is blocked
  when a provider is chosen without keys; keys reset on provider change.
- feat(fields): hidden tracking field — captures a URL query param
  (e.g. utm_source) or a default value, stored with the submission and
  included in CSV export. Never rendered visibly.
- feat(admin): "Test & learn regex" help link on pattern validation.
- refactor(admin): drop the redundant Actions column in the submissions
  inbox (the whole row already opens the detail drawer).
- test: Vitest + seed tests for verifyCaptcha (fail-closed), public
  schema secret-key stripping, and field validation.
- ci: run the test suite in CI.

devDeps: vitest; zod pinned to align the transitive ai/zod-v4
resolution for local symlinked plugin dev (not shipped — files: ["dist"]).

* fix(ci): regenerate package-lock so npm ci is in sync

* fix(ci): additive lockfile (keep original dep versions, add vitest/zod)

* fix: address review — hidden field tab leak, CSP script-src, captcha fail-closed + timeout

* feat(captcha): validate secret key in settings + honest public-form failure message

Author: devCluna

.github/workflows/ci.yml

@@ -29,6 +29,9 @@ jobs:
       - name: Type check (admin)
         run: npm run test:ts:front
 
+      - name: Run tests
+        run: npm test
+
       - name: Build
         run: npm run build
 

admin/src/api.ts

@@ -35,6 +35,11 @@ export function useFormsApi() {
       return data;
     },
 
+    async testCaptcha(provider: string, secretKey: string): Promise<{ ok: boolean; reason?: string }> {
+      const { data } = await post(`${BASE}/captcha/test`, { provider, secretKey });
+      return data;
+    },
+
     async getSubmissions(formId: number, query: Record<string, any> = {}) {
       const params = new URLSearchParams(query as any).toString();
       const { data } = await get(`${BASE}/submissions/${formId}${params ? `?${params}` : ''}`);

admin/src/components/FieldSettingsPanel.tsx

@@ -98,6 +98,7 @@ function Seg({ value, onChange }: { value: 'full' | 'half'; onChange: (v: 'full'
 export function FieldSettingsPanel({ field, onChange }: Props) {
   ensureStyle();
   const deco = isDecorative(field.type);
+  const isHidden = field.type === 'hidden';
   const [tab, setTab] = useState<'general' | 'validation'>('general');
   const update = (patch: Partial<FormField>) => onChange({ ...field, ...patch });
 
@@ -151,10 +152,21 @@ export function FieldSettingsPanel({ field, onChange }: Props) {
 
       <div style={{ display: 'flex', gap: 2, padding: '12px 18px 0', borderBottom: `1px solid ${C.n150}` }}>
         {tabBtn('general', 'General')}
-        {!deco && tabBtn('validation', 'Validation')}
+        {!deco && !isHidden && tabBtn('validation', 'Validation')}
       </div>
 
-      {(tab === 'general' || deco) && (
+      {isHidden && (
+        <div style={{ padding: 18, display: 'flex', flexDirection: 'column', gap: 16 }}>
+          <div style={{ font: `400 12px ${FF}`, color: C.n500, lineHeight: 1.5 }}>
+            A hidden tracking field. It never shows on the form but its value is stored with every submission — ideal for UTM parameters, referrers or campaign IDs.
+          </div>
+          <TextField label="Name (technical)" value={field.name} onChange={(v) => update({ name: v })} mono hint="Key stored with each submission (e.g. utm_source)." />
+          <TextField label="Prefill from URL parameter" value={field.queryParam || ''} onChange={(v) => update({ queryParam: v })} mono placeholder="utm_source" hint="If the form URL has ?utm_source=… its value is captured automatically." />
+          <TextField label="Default value" value={String(field.defaultValue ?? '')} onChange={(v) => update({ defaultValue: v })} hint="Used when the URL parameter above is absent." />
+        </div>
+      )}
+
+      {(tab === 'general' || deco) && !isHidden && (
         <div style={{ padding: 18, display: 'flex', flexDirection: 'column', gap: 16 }}>
           <TextField label={deco ? (field.type === 'divider' ? 'Label (internal)' : 'Text') : 'Label'} value={field.label} onChange={(v) => update({ label: v })} />
 
@@ -198,7 +210,7 @@ export function FieldSettingsPanel({ field, onChange }: Props) {
         </div>
       )}
 
-      {tab === 'validation' && !deco && (
+      {tab === 'validation' && !deco && !isHidden && (
         <div style={{ padding: 18, display: 'flex', flexDirection: 'column', gap: 12 }}>
           {/* Required — flag + custom message */}
           <div style={{ border: `1px solid ${C.n200}`, borderRadius: 5, padding: 11, display: 'flex', flexDirection: 'column', gap: 8, background: C.n0 }}>
@@ -241,6 +253,11 @@ export function FieldSettingsPanel({ field, onChange }: Props) {
                     {hasValue && (
                       <input className="sfb-inp" placeholder={rule.type === 'pattern' ? '^[a-z0-9]+$' : 'Value'} value={String(rule.value ?? '')} onChange={(e) => updateValidation(i, { value: e.target.value })} style={{ ...inpStyle, ...(rule.type === 'pattern' ? { fontFamily: 'ui-monospace, Menlo, monospace', fontSize: 12 } : {}) }} />
                     )}
+                    {rule.type === 'pattern' && (
+                      <a href="https://regex101.com/" target="_blank" rel="noopener noreferrer" style={{ font: `500 11px ${FF}`, color: C.p600, textDecoration: 'none' }}>
+                        Test &amp; learn regex ↗
+                      </a>
+                    )}
                     <input className="sfb-inp" placeholder="Custom error message (optional)" value={rule.message || ''} onChange={(e) => updateValidation(i, { message: e.target.value })} style={inpStyle} />
                   </div>
                 );

admin/src/components/FormPreview.tsx

@@ -308,7 +308,7 @@ export function FormPreview({ title, description, fields, settings, open, onClos
         </div>
 
         {/* body */}
-        <div style={{ background: '#f5f5f9', overflowY: 'auto', display: 'flex', justifyContent: 'center', padding: 24 }}>
+        <div style={{ background: '#f5f5f9', flex: 1, minHeight: 0, overflowY: 'auto', display: 'flex', justifyContent: 'center', alignItems: 'flex-start', padding: 24 }}>
           <div style={{ width: '100%', background: '#fff', border: '1px solid #eaeaef', borderRadius: 12, padding: '32px 32px 28px' }}>
             <h1 style={{ fontSize: 22, fontWeight: 700, color: TOKEN.text, margin: '0 0 8px' }}>{title}</h1>
             {description && <p style={{ fontSize: 14, color: TOKEN.sub, margin: '0 0 22px', lineHeight: 1.55 }}>{description}</p>}

admin/src/pages/FormBuilderPage.tsx

@@ -23,6 +23,7 @@ const DEFAULT_SETTINGS: FormSettings = {
   redirectUrl: '',
   customCss: '',
   publicPage: false,
+  captcha: { provider: 'none', siteKey: '', secretKey: '' },
 };
 
 // Order-insensitive stringify so key ordering in stored JSON doesn't create false diffs.
@@ -95,8 +96,36 @@ function SettingsDrawer({ initialDescription, initialSettings, slug, publishedAt
   // edits stay in a local buffer — they only reach the form on "Save settings"
   const [description, setDescription] = useState(initialDescription);
   const [settings, setSettings] = useState<FormSettings>(initialSettings);
+  const [captchaErr, setCaptchaErr] = useState('');
+  const [testing, setTesting] = useState(false);
+  const [testResult, setTestResult] = useState<{ ok: boolean; reason?: string } | null>(null);
+  const api = useFormsApi();
   const patch = (p: Partial<FormSettings>) => setSettings((s) => ({ ...s, ...p }));
   const onCancel = onClose;
+
+  const testCaptcha = async () => {
+    if (!settings.captcha) return;
+    setTesting(true);
+    setTestResult(null);
+    try {
+      const r = await api.testCaptcha(settings.captcha.provider, settings.captcha.secretKey);
+      setTestResult(r);
+    } catch {
+      setTestResult({ ok: false, reason: 'Test request failed' });
+    } finally {
+      setTesting(false);
+    }
+  };
+
+  const handleSave = () => {
+    const cap = settings.captcha;
+    if (cap && cap.provider !== 'none' && (!cap.siteKey?.trim() || !cap.secretKey?.trim())) {
+      setCaptchaErr('Enter both the site key and secret key, or set CAPTCHA to None.');
+      return;
+    }
+    setCaptchaErr('');
+    onSave(description, settings);
+  };
   const url = slug ? `${window.location.origin}/api/${PLUGIN_ID}/page/${slug}` : '';
   const live = !!publishedAt;
 
@@ -159,6 +188,46 @@ function SettingsDrawer({ initialDescription, initialSettings, slug, publishedAt
                 <input value={String(settings.maxSubmissionsPerHour ?? '')} onChange={(e) => patch({ maxSubmissionsPerHour: Number(e.target.value.replace(/[^0-9]/g, '')) || 0 })} style={{ ...dInp, width: 120 }} />
               </div>
             )}
+
+            <div style={{ marginTop: 16 }}>
+              <label style={dLbl}>CAPTCHA</label>
+              <select
+                value={settings.captcha?.provider || 'none'}
+                onChange={(e) => { setCaptchaErr(''); patch({ captcha: { provider: e.target.value as any, siteKey: '', secretKey: '' } }); }}
+                style={{ ...dInp, cursor: 'pointer' }}
+              >
+                <option value="none">None</option>
+                <option value="turnstile">Cloudflare Turnstile</option>
+                <option value="recaptcha">Google reCAPTCHA v2</option>
+              </select>
+              <div style={dHint}>Human-verification challenge required before a submission is accepted.</div>
+            </div>
+            {settings.captcha && settings.captcha.provider !== 'none' && (
+              <>
+                <div style={{ marginTop: 12 }}>
+                  <label style={dLbl}>Site key</label>
+                  <input value={settings.captcha.siteKey} onChange={(e) => patch({ captcha: { ...settings.captcha!, siteKey: e.target.value } })} placeholder="Public — sent to the browser" style={{ ...dInp, fontFamily: 'ui-monospace, Menlo, monospace', fontSize: 12 }} />
+                </div>
+                <div style={{ marginTop: 12 }}>
+                  <label style={dLbl}>Secret key</label>
+                  <input type="password" value={settings.captcha.secretKey} onChange={(e) => { setTestResult(null); patch({ captcha: { ...settings.captcha!, secretKey: e.target.value } }); }} placeholder="Private — kept server-side, never exposed" style={{ ...dInp, fontFamily: 'ui-monospace, Menlo, monospace', fontSize: 12 }} />
+                </div>
+                <div style={{ marginTop: 10, display: 'flex', alignItems: 'center', gap: 10 }}>
+                  <button type="button" onClick={testCaptcha} disabled={testing || !settings.captcha.secretKey.trim()} style={{ height: 30, padding: '0 12px', borderRadius: 4, border: `1px solid ${C.n200}`, background: C.n0, color: C.n800, font: `600 12px ${FF}`, cursor: testing || !settings.captcha.secretKey.trim() ? 'not-allowed' : 'pointer', opacity: testing || !settings.captcha.secretKey.trim() ? 0.5 : 1 }}>
+                    {testing ? 'Testing…' : 'Test secret key'}
+                  </button>
+                  {testResult && (
+                    <span style={{ font: `600 12px ${FF}`, color: testResult.ok ? C.suc600 : C.dng600 }}>
+                      {testResult.ok ? '✓ Secret key valid' : `✗ ${testResult.reason || 'Invalid'}`}
+                    </span>
+                  )}
+                </div>
+                <div style={{ ...dHint, marginTop: 6 }}>
+                  Note: the site key can only be checked on the live form — an invalid site key shows no widget there.
+                </div>
+                {captchaErr && <div style={{ marginTop: 10, font: `500 12px ${FF}`, color: C.dng600 }}>{captchaErr}</div>}
+              </>
+            )}
           </div>
 
           <div style={{ padding: '20px 0' }}>
@@ -170,7 +239,7 @@ function SettingsDrawer({ initialDescription, initialSettings, slug, publishedAt
 
         <div style={{ padding: '16px 24px', borderTop: `1px solid ${C.n150}`, display: 'flex', justifyContent: 'flex-end', gap: 8 }}>
           <HeaderBtn variant="ghost" onClick={onCancel}>Cancel</HeaderBtn>
-          <HeaderBtn variant="pri" onClick={() => onSave(description, settings)}>Save settings</HeaderBtn>
+          <HeaderBtn variant="pri" onClick={handleSave}>Save settings</HeaderBtn>
         </div>
       </div>
     </>

admin/src/pages/SubmissionsPage.tsx

@@ -311,7 +311,6 @@ export function SubmissionsPage() {
                   {shownColumns.map((c) => (
                     <Th key={c.name}><Typography variant="sigma">{c.label}</Typography></Th>
                   ))}
-                  <Th><Typography variant="sigma">Actions</Typography></Th>
                 </Tr>
               </Thead>
               <Tbody>
@@ -334,9 +333,6 @@ export function SubmissionsPage() {
                         </Td>
                       );
                     })}
-                    <Td onClick={(e: React.MouseEvent) => e.stopPropagation()}>
-                      <button type="button" onClick={() => setSelectedId(sub.id)} style={{ width: 28, height: 28, borderRadius: 4, border: `1px solid ${C.n200}`, background: C.n0, color: C.n500, cursor: 'pointer' }}>›</button>
-                    </Td>
                   </Tr>
                 ))}
               </Tbody>

admin/src/types.ts

@@ -36,6 +36,7 @@ export interface FormField {
   placeholder?: string;
   helpText?: string;
   defaultValue?: any;
+  queryParam?: string;
   required: boolean;
   order: number;
   width: 'full' | 'half';
@@ -66,6 +67,11 @@ export interface FormSettings {
   redirectUrl: string;
   customCss: string;
   publicPage: boolean;
+  captcha?: {
+    provider: 'none' | 'turnstile' | 'recaptcha';
+    siteKey: string;
+    secretKey: string;
+  };
 }
 
 export interface Form {

admin/src/ui.ts

@@ -35,6 +35,7 @@ export const FIELD_CATEGORIES: { cat: string; items: FieldMeta[] }[] = [
     { type: 'url', name: 'URL', cat: 'Basic' },
     { type: 'password', name: 'Password', cat: 'Basic' },
     { type: 'textarea', name: 'Textarea', cat: 'Basic' },
+    { type: 'hidden', name: 'Hidden', cat: 'Basic' },
   ]},
   { cat: 'Choice', items: [
     { type: 'select', name: 'Select', cat: 'Choice' },
@@ -70,7 +71,7 @@ const ICON_COMPONENTS: Partial<Record<FieldType, React.ComponentType<any>>> = {
   'checkbox-group': ListPlus, date: Calendar, time: Clock,
 };
 const GLYPHS: Partial<Record<FieldType, string>> = {
-  text: 'T', radio: '◉', heading: 'H', paragraph: '¶', divider: '—',
+  text: 'T', radio: '◉', heading: 'H', paragraph: '¶', divider: '—', hidden: '⊘',
 };
 
 export function FieldIcon({ type, size = 16 }: { type: FieldType; size?: number }) {