@usgb/forms 1.0.0 → 1.0.2

package/README.md

@@ -2,28 +2,28 @@
 
 Shared lead and newsletter forms for the **PWA** (React) and **WordPress** (Web Component) hosts.
 
-You pick a predefined `formId`. The package owns fields, validation, consent copy, tracking keys, and layout. You own the submit endpoint, legal-document URLs, heading/CTA copy, and thank-you behavior.
+You pick a predefined `formId`. The package owns fields, validation, consent copy, tracking keys, and layout. You own the submit endpoint, legal-document URLs, heading/subheading/CTA copy, and thank-you behavior.
 
 ## What you get
 
-| Artifact      | Path / export                                                   | Who uses it                         |
-| ------------- | --------------------------------------------------------------- | ----------------------------------- |
-| React package | `@usgb/forms` → `dist/index.js`                                 | PWA / any React host                |
-| Stylesheet    | `@usgb/forms/usgb-forms.css`                                    | **Required** for React hosts        |
-| Web Component | `dist/usgb-forms.js` (also versioned `usgb-forms.<version>.js`) | WordPress and other non-React hosts |
-| Catalog       | `@usgb/forms/manifest` → `forms-manifest.json`                  | CMS pickers, docs, tooling          |
+| Artifact      | Path / export                                                                                              | Who uses it                         |
+| ------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| React package | `@usgb/forms` → `dist/index.js`                                                                            | PWA / any React host                |
+| Stylesheet    | `@usgb/forms/usgb-forms.css`                                                                               | **Required** for React hosts        |
+| Web Component | `dist/usgb-forms.js` (also versioned `usgb-forms.<version>.js`)                                            | WordPress and other non-React hosts |
+| Catalog       | `@usgb/forms/manifest` → `forms-manifest.json` (also versioned `forms-manifest.<version>.json` in `dist/`) | CMS pickers, Gutenberg, tooling     |
 
 The Web Component script injects the same CSS once on load. React hosts must import the stylesheet themselves.
 
 ## Mental model
 
-| You pass                         | Package already decided                                                               |
-| -------------------------------- | ------------------------------------------------------------------------------------- |
-| `formId`                         | Fields, required/optional rules, consent bundle, tracking set, layout family (`kind`) |
-| `adapter.submit`                 | Where the payload goes (never an attribute or hardcoded URL)                          |
-| `legalUrls` / `*-url`            | Hrefs for package-owned consent copy                                                  |
-| `heading`, `body`, `ctaLabel`    | Marketing copy around the form                                                        |
-| `successMessage` or `successUrl` | Thank-you UX after accept                                                             |
+| You pass                            | Package already decided                                                             |
+| ----------------------------------- | ----------------------------------------------------------------------------------- |
+| `formId`                            | Fields, required/optional rules, consent pins, tracking set, layout family (`kind`) |
+| `adapter.submit`                    | Where the payload goes (never an attribute or hardcoded URL)                        |
+| `legalUrls` / `*-url`               | Hrefs for package-owned consent copy                                                |
+| `heading`, `subheading`, `ctaLabel` | Marketing copy around the form                                                      |
+| `successMessage` or `successUrl`    | Thank-you UX after accept                                                           |
 
 Hosts **must not** invent field lists, consent wording, or tracking keys. New forms are new catalog entries in this package, not host-built schemas.
 
@@ -31,12 +31,13 @@ Use `listFormDefinitions()` (or the manifest) when a CMS needs a picker of avail
 
 ## Available forms
 
-| `formId`             | Kind         | Fields                                                    | Consent                        | Variants                                                |
-| -------------------- | ------------ | --------------------------------------------------------- | ------------------------------ | ------------------------------------------------------- |
-| `main-investors-kit` | `lead`       | First name, last name, email (required); phone (optional) | TCPA checkbox (`lead-tcpa` v1) | `dense`, `large`, `sidebar`, plus optional `two-column` |
-| `newsletter`         | `newsletter` | Email only                                                | None                           | None — omit `variants` / `variant`                      |
+| `formId`                    | Kind         | Fields                                                    | Consent                                                    | Variants                                                |
+| --------------------------- | ------------ | --------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------- |
+| `main-investors-kit`        | `lead`       | First name, last name, email (required); phone (optional) | Optional TCPA, marketing SMS, and terms/privacy checkboxes | `dense`, `large`, `sidebar`, plus optional `two-column` |
+| `main-investors-kit-notice` | `lead`       | Same as kit                                               | Clickwrap notice only (`lead-clickwrap` v1)                | `dense`, `large`, `sidebar`, plus optional `two-column` |
+| `newsletter`                | `newsletter` | Email only                                                | None                                                       | None — omit `variants` / `variant`                      |
 
-Appearances for both: `light` | `navy`.
+Appearances for every catalog form: `on-light` | `on-dark`. Appearance only recolors the form for readability on a light or dark host background — it never sets a background, padding, or radius. The host container owns those.
 
 `kind` is the layout family (lead grid vs inline newsletter row). The root exposes `data-kind` for CSS. Several catalog forms can share one kind (e.g. another lead kit that reuses the lead layout).
 
@@ -69,9 +70,40 @@ Load the built IIFE (styles inject themselves):
 <script src="https://cdn.example.com/usgb-forms/usgb-forms.1.0.0.js"></script>
 ```
 
-Exact CDN hostname, path, and versioning scheme are **TBD**. Prefer a versioned filename (`usgb-forms.<version>.js`) so hosts can pin releases.
+Exact CDN hostname, path, and versioning scheme are **TBD**. Prefer versioned filenames (`usgb-forms.<version>.js` and `forms-manifest.<version>.json`) so hosts can pin the script and the CMS picker to the same release. Gutenberg should load that matching manifest — not an unversioned “latest” file — when listing `formId`s.
 
-Until the package is published, you can still develop against a local checkout (`yarn add file:../usgb-forms` or `yarn link`).
+### Local development (hosts, unpublished)
+
+Hosts consume **built** artifacts (`dist/` and root `forms-manifest.json`), not `src/`. Clone this repo next to the host (or anywhere you can path to), then:
+
+```bash
+cd usgb-forms
+yarn install
+yarn build
+```
+
+Rebuild here whenever you change this package. The Vite playground (`yarn dev`) is only for package maintainers; it is not what PWA or WordPress load.
+
+**React / PWA.** Point the host at this repo with Yarn 1 `file:` (preferred — the path lives in the host `package.json`, no global link):
+
+```bash
+# from the PWA / React host, path adjusted to your layout
+yarn add file:../usgb-forms
+```
+
+Or set `"@usgb/forms": "file:../usgb-forms"` by hand and run `yarn install`. Imports stay the same (`@usgb/forms`, `@usgb/forms/usgb-forms.css`, `@usgb/forms/manifest`). After each `yarn build` in this repo, run `yarn install` (or `yarn upgrade @usgb/forms`) in the host so Yarn recopies the pack — `file:` does not live-reload.
+
+`yarn link` in this repo and `yarn link @usgb/forms` in the host also works, but it can resolve a second copy of React and break hooks. If that happens, alias `@usgb/forms` to the sibling folder in the host bundler instead of linking.
+
+**WordPress / Web Component.** Skip the CDN. After `yarn build`, load files from this repo:
+
+| Host need                | File in this repo                                               |
+| ------------------------ | --------------------------------------------------------------- |
+| Form script              | `dist/usgb-forms.js`                                            |
+| Pinned script (optional) | `dist/usgb-forms.<version>.js`                                  |
+| Gutenberg `formId` list  | `forms-manifest.json` (or `dist/forms-manifest.<version>.json`) |
+
+Copy those into the plugin on its build, or enqueue them from a local static server. A `file:` npm dependency is not required for the Web Component — only a URL (or filesystem path the plugin can enqueue) to the built JS and catalog JSON.
 
 ## React (PWA)
 
@@ -80,10 +112,10 @@ import { UsgbForm, createStubAdapter, PWA_LEGAL_URLS } from '@usgb/forms'
 import '@usgb/forms/usgb-forms.css'
 ;<UsgbForm
     formId="main-investors-kit"
-    appearance="navy"
+    appearance="on-dark"
     variants={['large', 'two-column']}
     heading="Get My Free Guide"
-    body="Enter your details to receive the Main Investors Kit."
+    subheading="Enter your details to receive the Main Investors Kit."
     ctaLabel="GET MY FREE GUIDE"
     source="cms-home"
     campaign="spring-kit"
@@ -104,7 +136,7 @@ Newsletter (no consent, no variants):
 ```tsx
 <UsgbForm
     formId="newsletter"
-    appearance="light"
+    appearance="on-light"
     heading="Subscribe"
     ctaLabel="SUBSCRIBE"
     adapter={yourHostAdapter}
@@ -117,10 +149,10 @@ Newsletter (no consent, no variants):
 | ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
 | `formId`                  | yes                        | Catalog key (`main-investors-kit`, `newsletter`, …)                                                 |
 | `adapter`                 | yes                        | `HostAdapter` with `host`, `getTrackingHints()`, `submit()`                                         |
-| `appearance`              | no                         | `light` (default) or `navy`                                                                         |
+| `appearance`              | no                         | `on-light` (default) or `on-dark`                                                                   |
 | `variants`                | no                         | Lead only. Default `['dense']`. One of `dense` \| `large` \| `sidebar`, optionally add `two-column` |
-| `heading` / `body`        | no                         | Title and supporting copy                                                                           |
-| `ctaLabel`                | no                         | Submit button label                                                                                 |
+| `heading` / `subheading`  | no                         | Title and supporting copy                                                                           |
+| `ctaLabel`                | no                         | Submit button label. Falls back to the catalog `ctaLabel` for that `formId`                         |
 | `source` / `campaign`     | no                         | Placement / campaign context in the payload                                                         |
 | `legalUrls`               | when consent requires them | Host CMS paths for legal links in consent copy                                                      |
 | `successMessage`          | no                         | Inline thank-you when `successUrl` is omitted                                                       |
@@ -138,9 +170,10 @@ Load one script. Styles are injected automatically.
 <usgb-form
     ```
     form-id="main-investors-kit"
-    appearance="navy"
+    appearance="on-dark"
     variant="large two-column"
     heading="Get My Free Guide"
+    subheading="Enter your details to receive the Main Investors Kit."
     cta="GET MY FREE GUIDE"
     source="cms-home"
     client-agreement-url="/client-agreement/"
@@ -187,7 +220,7 @@ Submit is **not** an attribute. Markup alone uses a stub adapter. Assign a real
 | `form-id`                                       | `formId`                                                      |
 | `appearance`                                    | `appearance`                                                  |
 | `variant`                                       | `variants` (space-separated)                                  |
-| `heading` / `body`                              | `heading` / `body`                                            |
+| `heading` / `subheading`                        | `heading` / `subheading`                                      |
 | `cta`                                           | `ctaLabel`                                                    |
 | `source` / `campaign`                           | `source` / `campaign`                                         |
 | `success-message` / `success-url`               | `successMessage` / `successUrl`                               |
@@ -211,19 +244,19 @@ interface HostAdapter {
 
 ### Payload shape (summary)
 
-Successful submits send a nested envelope: `formId`, `definitionVersion`, `submissionContractVersion`, `idempotencyKey`, `data` (field values), optional `consent`, and `context` (`host`, `source`, `campaign`, `page`, `tracking`). Exact field and tracking sets come from the form’s catalog entry.
+Successful submits send a nested envelope: `formId`, `definitionVersion`, `submissionContractVersion`, `idempotencyKey`, `data` (field values), optional `consents` (grant booleans, opt-in dates, and `*_consent_language` strings), and `context` (`host`, `source`, `campaign`, `page`, `tracking`). Exact field and tracking sets come from the form’s catalog entry.
 
 ## Consent and legal URLs
 
-Consent bundles are versioned and package-owned (checkboxes and/or clickwrap notices). Hosts only supply document **hrefs**.
+Consent policies are versioned and package-owned (checkboxes and/or clickwrap notices). Forms list zero or more pins (`definitionId` + `definitionVersion` + optional `required` for checkboxes). Hosts only supply document **hrefs**.
 
--   `main-investors-kit` uses `lead-tcpa` v1 and requires `clientAgreement` and `privacyPolicy`.
--   PWA Magento defaults: `PWA_LEGAL_URLS` → `/content/client-agreement`, `/content/privacy-policy`.
--   WordPress must pass every URL required by the selected consent. A consent form with a missing required URL **does not render**.
--   Checkbox values land in `consent.values` (and mirrored in `data`). Notices have no boolean field; the payload still records consent definition id/version.
--   Distinct legal wording requires a new consent id/version in this package — not freeform copy from the host.
-
-`LEAD_CLICKWRAP_V1` (“By clicking the button…”) is in the catalog and needs five legal URLs (`privacyPolicy`, `userAgreement`, `marketLossPolicy`, `electronicDisclaimer`, `termsOfSale`). It is not attached to a `formId` until that recipe is chosen.
+-   `main-investors-kit` pins `lead-tcpa`, `lead-sms`, and `lead-tospp` (all v1, optional checkboxes). It needs `userAgreement` and `privacyPolicy` for the terms/privacy copy.
+-   `main-investors-kit-notice` pins `lead-clickwrap` v1 (notice only). It needs the five clickwrap URLs.
+-   PWA Magento defaults (`PWA_LEGAL_URLS`): `/content/client-agreement`, `/content/privacy-policy`, `/content/user-agreement`, `/content/market-loss-policy`, `/content/electronic-disclaimer`, `/content/terms-of-sale`.
+-   WordPress must pass every URL required by the selected consents. A form with a missing required URL **does not render**.
+-   Checkbox grants land in `consents` only (`tcpa_form_consent_granted`, `sms_form_consent_granted`, `tospp_form_consent_granted`). The exact copy shown is `tcpa_consent_language` (and the matching keys for other policies), even when unchecked.
+-   Checking the TCPA box also adds `tcpa_form_opt_in_date` (YYYY-MM-DD). The notice form only sends `clickwrap_consent_language`.
+-   Distinct legal wording requires a new consent id/version in this package — not freeform copy from the host. Toggle `consents[].required` on the form recipe when a checkbox must be checked.
 
 ## Success behavior
 
@@ -240,10 +273,10 @@ This package does **not** wait on a returned Promise, add a flush timeout, or ca
 
 What is reliable today:
 
-- Inline thank-you (`successMessage` only) — no navigation, so tags usually complete.
-- Same-document hash redirects (`#thank-you`) — no unload.
-- Host `analytics` that uses `navigator.sendBeacon` or `fetch(..., { keepalive: true })`.
-- Conversion measured on the thank-you page itself, not on this `success` event.
+-   Inline thank-you (`successMessage` only) — no navigation, so tags usually complete.
+-   Same-document hash redirects (`#thank-you`) — no unload.
+-   Host `analytics` that uses `navigator.sendBeacon` or `fetch(..., { keepalive: true })`.
+-   Conversion measured on the thank-you page itself, not on this `success` event.
 
 `submit_attempt` is safer than `success` because it fires before `adapter.submit` and has the round-trip to flush. Prefer the thank-you page (or a beacon) when `successUrl` is a full navigation.
 
@@ -264,18 +297,43 @@ Prefer **custom properties** on `.usgb-form` for color, type, and spacing:
     --usgb-field-border: #cccccc;
 }
 
-.usgb-form[data-appearance='navy'] {
+.usgb-form[data-appearance='on-dark'] {
     --usgb-button-background: #f4e08e;
 }
 ```
 
 Use class selectors when a token does not exist (`.usgb-form .usgb-btn { border-radius: 0; }`).
 
-Stable hooks: `.usgb-form` (`data-appearance`, `data-variant`, `data-kind`), `.usgb-form-heading`, `.usgb-form-body`, `.usgb-form-grid`, `.usgb-form-inline`, `.usgb-field-control`, `.usgb-field-error`, `.usgb-consent-*`, `.usgb-btn`, `.usgb-form-status-*`.
+Stable hooks: `.usgb-form` (`data-appearance`, `data-variant`, `data-kind`), `.usgb-form-heading`, `.usgb-form-subheading`, `.usgb-form-grid`, `.usgb-form-inline`, `.usgb-field-control`, `.usgb-field-error`, `.usgb-consent-*`, `.usgb-btn`, `.usgb-form-status-*`.
+
+Semantic tokens (`--usgb-field-*`, `--usgb-button-*`, `--usgb-newsletter-underline`, …) are the first place to retheme. Palette vars (`--usgb-blue-1`, …) are a PWA snapshot. Error and checkbox glyphs are inline SVGs that use `currentColor` — override `--usgb-alert-danger` or `--usgb-checkbox-mark` to recolor them.
+
+Appearance never paints a card. Put the form on a dark host surface and pass `appearance="on-dark"` (or `on-light` on a light surface):
+
+```html
+<div style="background: #001f3d; padding: 2rem; border-radius: 0.75rem">
+    <usgb-form form-id="main-investors-kit" appearance="on-dark" …></usgb-form>
+</div>
+```
+
+Visual styles are a ported snapshot of the PWA form kit. When PWA form styles change, update this package and bump `package.json` `version`.
+
+## Versions
+
+Day to day, bump **`package.json` `version`** (and set `compatiblePackageVersions` to `^` that version). Push to `main`: npm publishes only if that version is new; S3 always uploads `dist/`. Skipping a package bump **overwrites** the existing `usgb-forms.<version>.js` pin.
+
+Patch is enough while nothing is consuming the package. Use minor/major later for compatible vs breaking host API.
+
+Everything else is a different object — leave it alone unless that object actually changed:
 
-Semantic tokens (`--usgb-form-surface`, `--usgb-field-*`, `--usgb-button-*`, `--usgb-newsletter-underline`, …) are the first place to retheme. Palette vars (`--usgb-blue-1`, …) are a PWA snapshot. Error and checkbox glyphs are inline SVGs that use `currentColor` — override `--usgb-alert-danger` or `--usgb-checkbox-mark` to recolor them.
+| Field                                         | Bump when                                                            |
+| --------------------------------------------- | -------------------------------------------------------------------- |
+| `forms[formId].definitionVersion`             | That form’s fields, consent pins, or tracking change                 |
+| Consent `definitionVersion` in `consents.tsx` | Legal wording changes (new id/version; do not edit in place)         |
+| `submissionContract.version`                  | Submit JSON shape changes (proxies read `submissionContractVersion`) |
+| `schemaVersion`                               | Manifest JSON keys/shape change (CMS parsers)                        |
 
-Visual styles are a ported snapshot of the PWA form kit. When PWA form styles change, update this package and bump the version.
+Form and consent rules: [`src/definitions/context.md`](src/definitions/context.md).
 
 ## Develop (package maintainers)
 

package/dist/forms-manifest.1.0.2.json

@@ -0,0 +1,305 @@
+{
+    "schemaVersion": "1.0.0",
+    "package": {
+        "name": "@usgb/forms",
+        "compatiblePackageVersions": "^1.0.2"
+    },
+    "submissionContract": {
+        "version": "1.0.0",
+        "transport": "server-proxy",
+        "payloadShape": "data-and-context"
+    },
+    "trackingRegistry": {
+        "page_url": {
+            "destination": "form_submission_url",
+            "category": "page",
+            "collection": "server",
+            "required": true,
+            "states": ["collected", "unavailable"],
+            "description": "Canonical landing-page URL at submission time"
+        },
+        "page_title": {
+            "destination": "pageName",
+            "category": "page",
+            "collection": "server",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "referrer": {
+            "destination": "referrer",
+            "category": "page",
+            "collection": "browser",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "first_touch_url": {
+            "destination": "crossDomain_landing_url",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "utm_source": {
+            "destination": "utm_source",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "utm_medium": {
+            "destination": "utm_medium",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "utm_campaign": {
+            "destination": "utm_campaign",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "utm_term": {
+            "destination": "utm_term",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "utm_content": {
+            "destination": "utm_content",
+            "category": "attribution",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "gclid": {
+            "destination": "gclid",
+            "category": "click-id",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "msclkid": {
+            "destination": "msclkid",
+            "category": "click-id",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "gbraid": {
+            "destination": "gbraid",
+            "category": "click-id",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "wbraid": {
+            "destination": "wbraid",
+            "category": "click-id",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "hubspot_utk": {
+            "destination": "hubspot_utk",
+            "category": "identity",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable", "consent-withheld"]
+        },
+        "ga_client_id": {
+            "destination": "ga_client_id",
+            "category": "analytics",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable", "consent-withheld"]
+        },
+        "ga_session_id": {
+            "destination": "session_id_start",
+            "category": "analytics",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable", "consent-withheld"]
+        },
+        "snowplow_id": {
+            "destination": "snowplow_id",
+            "category": "analytics",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable", "consent-withheld"]
+        },
+        "vwo_uuid": {
+            "destination": "vwo_uuid",
+            "category": "experiment",
+            "collection": "host-adapter",
+            "required": false,
+            "states": ["collected", "unavailable", "consent-withheld"]
+        },
+        "user_agent": {
+            "destination": "header_http_client_details",
+            "category": "technical",
+            "collection": "server",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        },
+        "ip_address": {
+            "destination": "ipAddress",
+            "category": "technical",
+            "collection": "server",
+            "required": false,
+            "states": ["collected", "unavailable"]
+        }
+    },
+    "forms": {
+        "main-investors-kit": {
+            "definitionVersion": "1",
+            "kind": "lead",
+            "flow": { "type": "single" },
+            "supportedHosts": ["pwa", "wordpress"],
+            "fields": [
+                { "name": "firstname", "required": true, "group": "name" },
+                { "name": "lastname", "required": true, "group": "name" },
+                { "name": "email", "required": true },
+                { "name": "phone", "required": false }
+            ],
+            "trackingFields": [
+                "page_url",
+                "page_title",
+                "referrer",
+                "first_touch_url",
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content",
+                "gclid",
+                "msclkid",
+                "gbraid",
+                "wbraid",
+                "hubspot_utk",
+                "ga_client_id",
+                "ga_session_id",
+                "snowplow_id",
+                "vwo_uuid",
+                "user_agent",
+                "ip_address"
+            ],
+            "ctaLabel": "GET MY FREE GUIDE",
+            "consents": [
+                {
+                    "definitionId": "lead-tcpa",
+                    "definitionVersion": "1",
+                    "required": false
+                },
+                {
+                    "definitionId": "lead-sms",
+                    "definitionVersion": "1",
+                    "required": false
+                },
+                {
+                    "definitionId": "lead-tospp",
+                    "definitionVersion": "1",
+                    "required": false
+                }
+            ],
+            "editor": {
+                "label": "Main Investors Kit",
+                "description": "Standard lead form: name, email, phone, plus optional TCPA, marketing SMS, and terms/privacy checkboxes. Use on full-width landing pages and PWA kit/sidebar placements.",
+                "whenToUse": "Default kit request with optional consent checkboxes. Do not use for affiliate landers or IRA-specific leads.",
+                "whenNotToUse": "Affiliate pages (separate definition). IRA kit (separate definition when added). Clickwrap-only kit (`main-investors-kit-notice`).",
+                "supportedAppearances": ["on-light", "on-dark"],
+                "supportedVariants": ["dense", "large", "sidebar", "two-column"]
+            }
+        },
+        "main-investors-kit-notice": {
+            "definitionVersion": "1",
+            "kind": "lead",
+            "flow": { "type": "single" },
+            "supportedHosts": ["pwa", "wordpress"],
+            "fields": [
+                { "name": "firstname", "required": true, "group": "name" },
+                { "name": "lastname", "required": true, "group": "name" },
+                { "name": "email", "required": true },
+                { "name": "phone", "required": false }
+            ],
+            "trackingFields": [
+                "page_url",
+                "page_title",
+                "referrer",
+                "first_touch_url",
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content",
+                "gclid",
+                "msclkid",
+                "gbraid",
+                "wbraid",
+                "hubspot_utk",
+                "ga_client_id",
+                "ga_session_id",
+                "snowplow_id",
+                "vwo_uuid",
+                "user_agent",
+                "ip_address"
+            ],
+            "ctaLabel": "GET MY FREE GUIDE",
+            "consents": [
+                { "definitionId": "lead-clickwrap", "definitionVersion": "1" }
+            ],
+            "editor": {
+                "label": "Main Investors Kit (clickwrap)",
+                "description": "Same fields as Main Investors Kit with a clickwrap notice only — no consent checkboxes.",
+                "whenToUse": "Kit request where submit acknowledges legal docs via notice copy instead of checkboxes.",
+                "whenNotToUse": "Placements that need TCPA / marketing SMS / terms checkboxes (`main-investors-kit`).",
+                "supportedAppearances": ["on-light", "on-dark"],
+                "supportedVariants": ["dense", "large", "sidebar", "two-column"]
+            }
+        },
+        "newsletter": {
+            "definitionVersion": "1",
+            "kind": "newsletter",
+            "flow": { "type": "single" },
+            "supportedHosts": ["pwa"],
+            "fields": [{ "name": "email", "required": true }],
+            "trackingFields": [
+                "page_url",
+                "page_title",
+                "referrer",
+                "utm_source",
+                "utm_medium",
+                "utm_campaign",
+                "utm_term",
+                "utm_content"
+            ],
+            "ctaLabel": "SUBSCRIBE",
+            "editor": {
+                "label": "Newsletter",
+                "description": "Email-only newsletter signup. No TCPA consent.",
+                "whenToUse": "Footer or landing newsletter capture where only an email is required.",
+                "whenNotToUse": "Lead kits that need name, phone, or TCPA consent.",
+                "supportedAppearances": ["on-light", "on-dark"],
+                "supportedVariants": []
+            }
+        }
+    },
+    "hostAdapterContract": {
+        "hosts": ["pwa", "wordpress"],
+        "mayProvide": [
+            "browser cookies",
+            "URL parameters",
+            "page and placement context",
+            "host/store identity"
+        ],
+        "mustNotDefine": [
+            "new tracking keys",
+            "destination property names",
+            "consent definitions",
+            "form fields",
+            "submission endpoints"
+        ]
+    }
+}