@duffcloudservices/site-forms 0.5.0 → 0.7.0

package/dist/site-forms.css

@@ -1 +1 @@
-.dcs-form{display:grid;gap:1.5rem;width:100%}.dcs-form__header{display:grid;gap:.5rem}.dcs-form__title{margin:0;font-size:clamp(1.875rem,2vw + 1.25rem,2.5rem);font-weight:700;line-height:1.1}.dcs-form__description{margin:0;font-size:1rem;line-height:1.6}.dcs-form__progress{font-size:.95rem}.dcs-form__fields{display:grid;gap:1rem}.dcs-form-field{display:grid;gap:.5rem}.dcs-form-field__label{display:inline-flex;align-items:center;gap:.2rem;font-size:.95rem;font-weight:600;line-height:1.4}.dcs-form-field__required{font-weight:700}.dcs-form-input{width:100%;min-height:3rem;padding:.75rem .95rem;font:inherit;line-height:1.5;color:inherit;background:#fffffff5;border:1px solid rgba(15,23,42,.16);border-radius:.875rem;box-shadow:0 1px 2px #0f172a14;transition:border-color .15s ease,box-shadow .15s ease,background-color .15s ease}.dcs-form-input::placeholder{color:#475569bf}.dcs-form-input:hover{border-color:#2563eb61}.dcs-form-input:focus,.dcs-form-input:focus-visible{outline:none;border-color:#2563ebbf;box-shadow:0 0 0 4px #3b82f62e}.dcs-form-input[aria-invalid=true]{border-color:#dc2626b8;box-shadow:0 0 0 4px #f871712e}.dcs-form-textarea{min-height:10rem;resize:vertical}.dcs-form-file{min-height:3.25rem;padding:.5rem .75rem;cursor:pointer}.dcs-form-file::file-selector-button{margin:0 .85rem 0 0;border:0;border-radius:9999px;padding:.65rem 1rem;font:inherit;font-weight:700;line-height:1;color:#fff;background:linear-gradient(135deg,#1d4ed8,#2563eb);box-shadow:0 8px 18px #2563eb33;cursor:pointer;transition:transform .15s ease,box-shadow .15s ease,opacity .15s ease}.dcs-form-file:hover::file-selector-button{transform:translateY(-1px);box-shadow:0 10px 22px #2563eb42}.dcs-form-file:disabled,.dcs-form-file:disabled::file-selector-button{cursor:not-allowed;opacity:.7}.dcs-form-file__status{margin:-.15rem 0 0;font-size:.78rem;font-weight:700;letter-spacing:.03em;color:#475569d1;text-transform:uppercase}.dcs-form-file-preview-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(9rem,1fr));gap:.85rem}.dcs-form-file-preview{position:relative;overflow:hidden;display:grid;gap:.65rem;padding:.65rem;border:1px solid rgba(15,23,42,.12);border-radius:1rem;background:linear-gradient(180deg,#fffffff0,#f8fafce6),radial-gradient(circle at top left,rgba(37,99,235,.1),transparent 40%);box-shadow:0 12px 28px #0f172a1a}.dcs-form-file-preview__image,.dcs-form-file-preview__placeholder{width:100%;aspect-ratio:4 / 3;border-radius:.75rem;background:#0f172a14}.dcs-form-file-preview__image{object-fit:cover}.dcs-form-file-preview__placeholder{display:grid;place-items:center;font-size:.8rem;font-weight:800;letter-spacing:.08em;color:#475569cc;text-transform:uppercase}.dcs-form-file-preview__meta{min-width:0;display:grid;gap:.1rem}.dcs-form-file-preview__name{overflow:hidden;font-size:.85rem;font-weight:700;line-height:1.35;text-overflow:ellipsis;white-space:nowrap}.dcs-form-file-preview__size{font-size:.75rem;color:#475569db}.dcs-form-file-preview__remove{appearance:none;justify-self:start;border:1px solid rgba(185,28,28,.2);border-radius:9999px;padding:.4rem .75rem;font:inherit;font-size:.75rem;font-weight:800;line-height:1;color:#991b1b;background:#fef2f2f2;cursor:pointer;transition:transform .15s ease,border-color .15s ease,background-color .15s ease}.dcs-form-file-preview__remove:hover{transform:translateY(-1px);border-color:#b91c1c6b;background:#fff}.dcs-form-select{appearance:none}.dcs-form-field__help,.dcs-form-field__error,.dcs-form__submit-error{margin:0;font-size:.875rem;line-height:1.5}.dcs-form-field__error,.dcs-form__submit-error{color:#b91c1c}.dcs-form__submit-error{padding:.85rem 1rem;border:1px solid rgba(220,38,38,.28);border-radius:.875rem;background:#fef2f2eb}.dcs-form__actions{display:flex;flex-wrap:wrap;gap:.75rem}.dcs-form__btn{appearance:none;border:0;border-radius:9999px;padding:.85rem 1.5rem;font:inherit;font-weight:700;line-height:1;cursor:pointer;transition:transform .15s ease,box-shadow .15s ease,opacity .15s ease}.dcs-form__btn:hover{transform:translateY(-1px)}.dcs-form__btn:focus,.dcs-form__btn:focus-visible{outline:none;box-shadow:0 0 0 4px #3b82f638}.dcs-form__btn:disabled{opacity:.7;cursor:not-allowed;transform:none}.dcs-form__btn--submit,.dcs-form__btn--next{color:#fff;background:linear-gradient(135deg,#1d4ed8,#2563eb);box-shadow:0 10px 24px #2563eb38}.dcs-form__btn--prev{color:#0f172a;background:#ffffffeb;box-shadow:0 8px 20px #0f172a1f}.dcs-form-checkbox-group,.dcs-form-radio-group{display:grid;gap:.75rem}.dcs-form-checkbox,.dcs-form-radio,.dcs-form-checkbox-single{display:flex;align-items:flex-start;gap:.65rem}.dcs-form-checkbox-single input,.dcs-form-checkbox input,.dcs-form-radio input{margin-top:.2rem}.dcs-form-section{display:grid;gap:.4rem}.dcs-form-section__heading,.dcs-form-section__help,.dcs-form--missing p,.dcs-form--success p{margin:0}@media(min-width:768px){.dcs-form__fields{grid-template-columns:repeat(2,minmax(0,1fr));gap:1.25rem}.dcs-form-field--width-half{grid-column:span 1}.dcs-form-field--width-full,.dcs-form-field--width-auto,.dcs-form-field--textarea,.dcs-form-field--checkbox,.dcs-form-field--checkbox-group,.dcs-form-field--radio,.dcs-form-field--section-heading,.dcs-form-field--html-block,.dcs-form-field--file{grid-column:1 / -1}}
+.dcs-form{display:grid;gap:1.5rem;width:100%}.dcs-form__header{display:grid;gap:.5rem}.dcs-form__title{margin:0;font-size:clamp(1.875rem,2vw + 1.25rem,2.5rem);font-weight:700;line-height:1.1}.dcs-form__description{margin:0;font-size:1rem;line-height:1.6}.dcs-form__progress{font-size:.95rem}.dcs-form__fields{display:grid;gap:1rem}.dcs-form__phi-guidance{margin:0;padding:.7rem .9rem;font-size:.9rem;line-height:1.55;color:inherit;background:#0f172a0b;border:1px solid rgba(15,23,42,.1);border-left:3px solid rgba(37,99,235,.6);border-radius:.625rem}.dcs-form__phi-guidance strong{font-weight:650}.dcs-form-field{display:grid;gap:.5rem}.dcs-form-field__label{display:inline-flex;align-items:center;gap:.2rem;font-size:.95rem;font-weight:600;line-height:1.4}.dcs-form-field__required{font-weight:700}.dcs-form-input{width:100%;min-height:3rem;padding:.75rem .95rem;font:inherit;line-height:1.5;color:inherit;background:#fffffff5;border:1px solid rgba(15,23,42,.16);border-radius:.875rem;box-shadow:0 1px 2px #0f172a14;transition:border-color .15s ease,box-shadow .15s ease,background-color .15s ease}.dcs-form-input::placeholder{color:#475569bf}.dcs-form-input:hover{border-color:#2563eb61}.dcs-form-input:focus,.dcs-form-input:focus-visible{outline:none;border-color:#2563ebbf;box-shadow:0 0 0 4px #3b82f62e}.dcs-form-input[aria-invalid=true]{border-color:#dc2626b8;box-shadow:0 0 0 4px #f871712e}.dcs-form-textarea{min-height:10rem;resize:vertical}.dcs-form-file{min-height:3.25rem;padding:.5rem .75rem;cursor:pointer}.dcs-form-file::file-selector-button{margin:0 .85rem 0 0;border:0;border-radius:9999px;padding:.65rem 1rem;font:inherit;font-weight:700;line-height:1;color:#fff;background:linear-gradient(135deg,#1d4ed8,#2563eb);box-shadow:0 8px 18px #2563eb33;cursor:pointer;transition:transform .15s ease,box-shadow .15s ease,opacity .15s ease}.dcs-form-file:hover::file-selector-button{transform:translateY(-1px);box-shadow:0 10px 22px #2563eb42}.dcs-form-file:disabled,.dcs-form-file:disabled::file-selector-button{cursor:not-allowed;opacity:.7}.dcs-form-file__status{margin:-.15rem 0 0;font-size:.78rem;font-weight:700;letter-spacing:.03em;color:#475569d1;text-transform:uppercase}.dcs-form-file-preview-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(9rem,1fr));gap:.85rem}.dcs-form-file-preview{position:relative;overflow:hidden;display:grid;gap:.65rem;padding:.65rem;border:1px solid rgba(15,23,42,.12);border-radius:1rem;background:linear-gradient(180deg,#fffffff0,#f8fafce6),radial-gradient(circle at top left,rgba(37,99,235,.1),transparent 40%);box-shadow:0 12px 28px #0f172a1a}.dcs-form-file-preview__image,.dcs-form-file-preview__placeholder{width:100%;aspect-ratio:4 / 3;border-radius:.75rem;background:#0f172a14}.dcs-form-file-preview__image{object-fit:cover}.dcs-form-file-preview__placeholder{display:grid;place-items:center;font-size:.8rem;font-weight:800;letter-spacing:.08em;color:#475569cc;text-transform:uppercase}.dcs-form-file-preview__meta{min-width:0;display:grid;gap:.1rem}.dcs-form-file-preview__name{overflow:hidden;font-size:.85rem;font-weight:700;line-height:1.35;text-overflow:ellipsis;white-space:nowrap}.dcs-form-file-preview__size{font-size:.75rem;color:#475569db}.dcs-form-file-preview__remove{appearance:none;justify-self:start;border:1px solid rgba(185,28,28,.2);border-radius:9999px;padding:.4rem .75rem;font:inherit;font-size:.75rem;font-weight:800;line-height:1;color:#991b1b;background:#fef2f2f2;cursor:pointer;transition:transform .15s ease,border-color .15s ease,background-color .15s ease}.dcs-form-file-preview__remove:hover{transform:translateY(-1px);border-color:#b91c1c6b;background:#fff}.dcs-form-select{appearance:none}.dcs-form-field__help,.dcs-form-field__error,.dcs-form__submit-error{margin:0;font-size:.875rem;line-height:1.5}.dcs-form-field__error,.dcs-form__submit-error{color:#b91c1c}.dcs-form__submit-error{padding:.85rem 1rem;border:1px solid rgba(220,38,38,.28);border-radius:.875rem;background:#fef2f2eb}.dcs-form__actions{display:flex;flex-wrap:wrap;gap:.75rem}.dcs-form__btn{appearance:none;border:0;border-radius:9999px;padding:.85rem 1.5rem;font:inherit;font-weight:700;line-height:1;cursor:pointer;transition:transform .15s ease,box-shadow .15s ease,opacity .15s ease}.dcs-form__btn:hover{transform:translateY(-1px)}.dcs-form__btn:focus,.dcs-form__btn:focus-visible{outline:none;box-shadow:0 0 0 4px #3b82f638}.dcs-form__btn:disabled{opacity:.7;cursor:not-allowed;transform:none}.dcs-form__btn--submit,.dcs-form__btn--next{color:#fff;background:linear-gradient(135deg,#1d4ed8,#2563eb);box-shadow:0 10px 24px #2563eb38}.dcs-form__btn--prev{color:#0f172a;background:#ffffffeb;box-shadow:0 8px 20px #0f172a1f}.dcs-form-checkbox-group,.dcs-form-radio-group{display:grid;gap:.75rem}.dcs-form-checkbox,.dcs-form-radio,.dcs-form-checkbox-single{display:flex;align-items:flex-start;gap:.65rem}.dcs-form-checkbox-single input,.dcs-form-checkbox input,.dcs-form-radio input{margin-top:.2rem}.dcs-form-section{display:grid;gap:.4rem}.dcs-form-section__heading,.dcs-form-section__help,.dcs-form--missing p,.dcs-form--success p{margin:0}@media(min-width:768px){.dcs-form__fields{grid-template-columns:repeat(2,minmax(0,1fr));gap:1.25rem}.dcs-form-field--width-half{grid-column:span 1}.dcs-form__phi-guidance,.dcs-form-field--width-full,.dcs-form-field--width-auto,.dcs-form-field--textarea,.dcs-form-field--checkbox,.dcs-form-field--checkbox-group,.dcs-form-field--radio,.dcs-form-field--section-heading,.dcs-form-field--html-block,.dcs-form-field--file{grid-column:1 / -1}}

package/dist/types.d.ts

@@ -113,4 +113,20 @@ export interface DcsFormSubmitError {
     payload: DcsFormSubmitPayload;
     error: Error;
     status?: number;
+    /**
+     * True when the server answered 2xx but the body was NOT JSON — i.e. the POST
+     * was answered by something that is not the DCS API (SPA shell, proxy
+     * interstitial, gateway page) and the submission was NOT stored. Additive and
+     * optional: the pre-existing error contract is unchanged (C-301).
+     */
+    nonJsonResponse?: boolean;
+    /**
+     * True when the server answered 2xx with valid JSON that is NOT the endpoint's
+     * receipt (C-310). Distinct from `nonJsonResponse` because the remedies differ:
+     * that one means "the POST was answered by something else — check routing",
+     * this one means "the API answered, but with nothing that proves a row exists
+     * — check the endpoint contract against the receipt predicate". Additive and
+     * optional; the pre-existing error contract is unchanged.
+     */
+    unconfirmedReceipt?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duffcloudservices/site-forms",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Shared <DcsForm/> runtime for DCS customer sites — renders managed form definitions from .dcs/forms/<formId>.yaml",
   "type": "module",
   "files": [

package/src/DcsForm.vue

@@ -9,6 +9,10 @@ import type {
 import { useUiSound } from '@dcs/ui/sound'
 import { useDcsForm } from './composables/useDcsForm'
 import { submitFormValues } from './composables/useFormSubmission'
+import {
+  PHI_GUIDANCE_COPY,
+  fetchSiteHandlesPhi,
+} from './composables/useSitePhiPosture'
 import { warnIfInvalid } from './schema/validate'
 import { loadFormDefinitions } from './loaders/yaml'
 
@@ -180,6 +184,41 @@ function fieldComponent(field: PortalFormField) {
   }
 }
 
+// ── PHI guidance (C-415) ────────────────────────────────────────────────────
+// Default-ON for HIPAA-mode tenants (Q-393(b)); there is no per-site opt-in
+// prop, because a site-local switch could disagree with the tenant's real HIPAA
+// posture and the whole point of the C-352 predicate is that exactly one thing
+// decides. Starts false and flips only when the platform says so, so nothing
+// renders on the 11 non-PHI sites in the fleet.
+const siteHandlesPhi = ref(false)
+
+const showPhiGuidance = computed(
+  () => siteHandlesPhi.value && !!definition.value,
+)
+
+/**
+ * Where the guidance sits: immediately above the first FREE-TEXT field the
+ * visitor will actually type prose into. Guidance parked at the top of a long
+ * form is guidance nobody reads; this puts it in the line of sight of the box
+ * that can carry PHI (on KEPT's contact form, the required `message` textarea).
+ * Falls back to the top of the visible fields when a form/step has no free-text
+ * field — a HIPAA-mode tenant's structured intake is still health information.
+ */
+const phiGuidanceIndex = computed(() => {
+  const idx = form.visibleFields.value.findIndex(
+    (f) =>
+      f.type === 'textarea' || f.role === 'message' || f.role === 'summary',
+  )
+  return idx >= 0 ? idx : 0
+})
+
+onMounted(async () => {
+  siteHandlesPhi.value = await fetchSiteHandlesPhi({
+    apiBase: apiBase.value,
+    siteSlug: resolvedSiteSlug.value,
+  })
+})
+
 const formEl = ref<HTMLFormElement | null>(null)
 
 defineExpose({
@@ -281,17 +320,29 @@ onMounted(() => {
     </div>
 
     <div class="dcs-form__fields">
-      <component
-        :is="fieldComponent(field)"
-        v-for="field in form.visibleFields.value"
+      <template
+        v-for="(field, index) in form.visibleFields.value"
         :key="field.id"
-        :field="field"
-        :attachment-policy="safeDefinition.attachmentPolicy"
-        :model-value="form.values[field.id]"
-        :error="form.errors.value[field.id]"
-        @update:model-value="(v: unknown) => form.setValue(field.id, v)"
-        @blur="form.touch(field.id)"
-      />
+      >
+        <p
+          v-if="showPhiGuidance && index === phiGuidanceIndex"
+          class="dcs-form__phi-guidance"
+          data-form-phi-guidance
+          role="note"
+        >
+          <strong>{{ PHI_GUIDANCE_COPY.lead }}</strong>
+          {{ PHI_GUIDANCE_COPY.detail }}
+        </p>
+        <component
+          :is="fieldComponent(field)"
+          :field="field"
+          :attachment-policy="safeDefinition.attachmentPolicy"
+          :model-value="form.values[field.id]"
+          :error="form.errors.value[field.id]"
+          @update:model-value="(v: unknown) => form.setValue(field.id, v)"
+          @blur="form.touch(field.id)"
+        />
+      </template>
     </div>
 
     <div v-if="form.submitError.value" class="dcs-form__submit-error" role="alert">

package/src/__tests__/missing-form-error-surfacing.test.ts

@@ -65,8 +65,13 @@ describe('missing/misconfigured server form (Lamphere W6 repro)', () => {
     await wrapper.find('form').trigger('submit')
     await flushPromises()
 
-    // 4xx must not be retried — one POST only.
-    expect(fetchMock).toHaveBeenCalledTimes(1)
+    // 4xx must not be retried — one POST only. Counted over POSTs specifically:
+    // the mount also issues the C-415 form-compliance GET, and conflating the
+    // two would let a genuine retry regression hide behind the posture read.
+    const posts = fetchMock.mock.calls.filter(
+      ([, init]) => (init as RequestInit | undefined)?.method === 'POST',
+    )
+    expect(posts).toHaveLength(1)
 
     // The failure is loud: a rendered, role="alert" error block.
     const alert = wrapper.find('.dcs-form__submit-error')

package/src/__tests__/non-json-response.test.ts

@@ -0,0 +1,282 @@
+/**
+ * C-301 — a 2xx response whose body is NOT JSON must surface as a VISIBLE
+ * FAILURE, never as a successful submission.
+ *
+ * The defect: `safeJson()` returned `null` on any parse failure, so a POST that
+ * landed on a static host's SPA shell (HTTP 200 `text/html`) was indistinguishable
+ * from a quiet success. `<DcsForm>` showed the success state, played the success
+ * chime and emitted `submit-success` — while NOTHING was stored. Silent lead loss.
+ *
+ * These tests use real `Response` objects (not hand-rolled doubles) so the
+ * content-type header and the single-use body stream behave exactly as they do in
+ * a browser.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import DcsForm from '../DcsForm.vue'
+import { submitFormValues } from '../composables/useFormSubmission'
+import type { DcsFormSubmitError, PortalFormDefinition } from '../types'
+
+const def: PortalFormDefinition = {
+  formId: 'contact',
+  submission: { kind: 'lead' },
+  fields: [
+    { id: 'name', type: 'text', label: 'Name', required: true },
+    { id: 'email', type: 'email', label: 'Email', required: true },
+  ],
+}
+
+const SPA_SHELL =
+  '<!DOCTYPE html>\n<html lang="en">\n  <head><title>Site</title></head>\n  <body><div id="app"></div></body>\n</html>'
+
+/**
+ * The REAL managed-form success shape: `202` + `PublicSiteFormSubmissionResponse`
+ * (types.gen.ts:14845), written at
+ * server/internal/handlers/public_site_forms.go:509-524.
+ */
+const MANAGED_FORM_RECEIPT = {
+  id: '07438812886145977836-dd5a5baf3835082c',
+  status: 'accepted',
+  submittedAt: '2026-07-26T14:52:30Z',
+  message: 'Thanks — your form has been received.',
+  notificationQueued: true,
+}
+
+let consoleError: ReturnType<typeof vi.spyOn>
+beforeEach(() => {
+  consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+})
+afterEach(() => {
+  consoleError.mockRestore()
+})
+
+function respond(body: BodyInit | null, init: ResponseInit): typeof fetch {
+  return vi.fn().mockResolvedValue(new Response(body, init)) as unknown as typeof fetch
+}
+
+describe('C-301: non-JSON 2xx body is a failure, not a success', () => {
+  it('rejects a 200 text/html SPA-shell body (the lead-loss shape)', async () => {
+    const fetchImpl = respond(SPA_SHELL, {
+      status: 200,
+      headers: { 'content-type': 'text/html; charset=utf-8' },
+    })
+
+    await expect(
+      submitFormValues({
+        apiBase: '',
+        siteSlug: 'kept',
+        fetchImpl,
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toMatchObject({
+      status: 200,
+      nonJsonResponse: true,
+    })
+
+    // TERMINAL: never retried, so a lead can never be double-stored.
+    expect(fetchImpl).toHaveBeenCalledTimes(1)
+    // The diagnostic names the real cause for whoever reads the console.
+    expect(consoleError).toHaveBeenCalledTimes(1)
+    expect(String(consoleError.mock.calls[0][0])).toContain('did not reach the DCS API')
+  })
+
+  it('surfaces the failure in the DcsForm UI and never shows the success state', async () => {
+    const originalFetch = globalThis.fetch
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch = respond(SPA_SHELL, {
+      status: 200,
+      headers: { 'content-type': 'text/html' },
+    })
+
+    const wrapper = mount(DcsForm, {
+      props: { formId: 'contact', siteSlug: 'kept', definitionOverride: def, apiBase: '' },
+    })
+    await wrapper.find('[data-form-field-key="name"] input').setValue('Jane')
+    await wrapper.find('[data-form-field-key="email"] input').setValue('jane@example.com')
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(wrapper.emitted('submit-success')).toBeUndefined()
+    expect(wrapper.emitted('submit-error')?.length).toBe(1)
+    const emitted = wrapper.emitted('submit-error')?.[0]?.[0] as DcsFormSubmitError
+    expect(emitted.nonJsonResponse).toBe(true)
+    // Visitor-visible failure text, and no success confirmation anywhere.
+    expect(wrapper.text()).toContain('We could not confirm your message was received')
+    expect(wrapper.html()).not.toContain('data-form-success')
+
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch = originalFetch
+  })
+
+  it('rejects a 200 text/plain gateway message', async () => {
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: '',
+        fetchImpl: respond('Unable to resolve site from request', {
+          status: 200,
+          headers: { 'content-type': 'text/plain' },
+        }),
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toMatchObject({ nonJsonResponse: true })
+  })
+
+  it('rejects an HTML body even when the content-type claims JSON', async () => {
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl: respond(SPA_SHELL, {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }),
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toMatchObject({ nonJsonResponse: true })
+  })
+
+  // C-310: these two previously asserted `{status:'accepted', submissionId:'S-1'}`
+  // and `{status:'accepted'}` — neither is a shape the server can produce. The
+  // real contract is `PublicSiteFormSubmissionResponse` (id + status +
+  // submittedAt, types.gen.ts:14845), written at public_site_forms.go:509.
+  // Testing against an invented shape is how a client drifts away from its own
+  // API without any test going red.
+  it('UNCHANGED: a REAL managed-form receipt still resolves with the parsed response', async () => {
+    const receipt = MANAGED_FORM_RECEIPT
+    const result = await submitFormValues({
+      apiBase: 'https://api.example.com/api/v1',
+      siteSlug: 'kept',
+      fetchImpl: respond(JSON.stringify(receipt), {
+        status: 202,
+        headers: { 'content-type': 'application/json' },
+      }),
+      payload: { formId: 'contact', values: { name: 'Jane' } },
+    })
+    expect(result.response).toEqual(receipt)
+    expect(consoleError).not.toHaveBeenCalled()
+  })
+
+  it('UNCHANGED: a JSON receipt with no content-type header still resolves', async () => {
+    const result = await submitFormValues({
+      apiBase: 'https://api.example.com/api/v1',
+      siteSlug: 'kept',
+      fetchImpl: vi.fn().mockResolvedValue({
+        ok: true,
+        status: 202,
+        text: async () => JSON.stringify(MANAGED_FORM_RECEIPT),
+        headers: { get: () => null },
+      }) as unknown as typeof fetch,
+      payload: { formId: 'contact', values: { name: 'Jane' } },
+    })
+    expect(result.response).toEqual(MANAGED_FORM_RECEIPT)
+  })
+
+  // C-310 KILL-TEST for the removed 204 exemption. This case INVERTS: it used to
+  // assert "an empty 204 body still resolves as a quiet success" and passes on
+  // pre-C-310 code only in that inverted form. `204` proves the RESPONDER chose
+  // to send nothing; it proves nothing about whether the DCS API ran. All five
+  // guarded endpoints return a JSON receipt, so a bodyless 204 on a submission
+  // POST means something other than the API answered.
+  it('C-310: an empty 204 is a FAILURE — no guarded endpoint contracts 204', async () => {
+    const fetchImpl = respond(null, { status: 204 })
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl,
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toMatchObject({ status: 204, nonJsonResponse: true })
+    // TERMINAL: an unconfirmable submission must never be retried.
+    expect(fetchImpl).toHaveBeenCalledTimes(1)
+    expect(String(consoleError.mock.calls[0][0])).toContain('empty body')
+  })
+
+  // C-302 adversarial review (2026-07-26), caught before 0.6.0 was published.
+  // This case previously asserted "empty 200 = quiet success" — the inverse of
+  // what it should be. The C-301 sweep found misrouted fleet POSTs answering
+  // with EMPTY bodies, so that was the one lead-loss shape this guard was blind
+  // to. Emptiness is now trusted only when the STATUS says so (204).
+  it('C-302: an empty 200 body is a FAILURE — no DCS endpoint returns one', async () => {
+    const fetchImpl = respond('', { status: 200, headers: { 'content-type': 'text/html' } })
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl,
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toMatchObject({ status: 200, nonJsonResponse: true })
+    // TERMINAL: an unconfirmable submission must never be retried.
+    expect(fetchImpl).toHaveBeenCalledTimes(1)
+  })
+
+  it('C-302: a body-read rejection is a FAILURE, never a claimed success', async () => {
+    // Connection dropped after headers, mid-body — the canonical flaky-mobile
+    // case. The old guard swallowed this into '' and reported "sent".
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () => {
+        throw new TypeError('network error')
+      },
+      headers: { get: () => 'application/json' },
+    }) as unknown as typeof fetch
+
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl,
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toMatchObject({ status: 200, nonJsonResponse: true })
+    expect(fetchImpl).toHaveBeenCalledTimes(1)
+  })
+
+  it('UNCHANGED: a 4xx JSON error keeps the existing error contract (no retry)', async () => {
+    const fetchImpl = respond(JSON.stringify({ message: 'Missing required fields: email' }), {
+      status: 400,
+      headers: { 'content-type': 'application/json' },
+    })
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl,
+        payload: { formId: 'contact', values: {} },
+      }),
+    ).rejects.toMatchObject({ status: 400 })
+
+    try {
+      await submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl: respond(JSON.stringify({ message: 'nope' }), {
+          status: 400,
+          headers: { 'content-type': 'application/json' },
+        }),
+        payload: { formId: 'contact', values: {} },
+      })
+      expect.unreachable('should have thrown')
+    } catch (e) {
+      const err = e as DcsFormSubmitError
+      expect(err.error.message).toContain('Submission failed (400)')
+      expect(err.nonJsonResponse).toBeUndefined()
+    }
+  })
+
+  it('UNCHANGED: a 5xx still retries and then fails', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(new Response('boom', { status: 503 })) as unknown as typeof fetch
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl,
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toMatchObject({ status: 503 })
+    expect(fetchImpl).toHaveBeenCalledTimes(2)
+  })
+})