@usgb/forms 0.1.0 → 1.0.0

package/README.md

@@ -1,110 +1,295 @@
 # @usgb/forms
 
-Sample React package that builds with [tsup](https://tsup.egoist.dev/) and publishes to npm using [OIDC trusted publishing](https://docs.npmjs.com/trusted-publishers/). Releases do not use a long-lived `NPM_TOKEN`.  Replace this code and this readme with real versions.
+Shared lead and newsletter forms for the **PWA** (React) and **WordPress** (Web Component) hosts.
 
-## What's included
+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.
 
-- React 18+ form primitives (`Form`, `TextField`) with TypeScript types
-- Dual ESM/CJS build output in `dist/`
-- CI on pull requests
-- Manual publish from GitHub Actions via OIDC (no git tags)
+## What you get
 
-## Local development
+| 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          |
+
+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                                                             |
+
+Hosts **must not** invent field lists, consent wording, or tracking keys. New forms are new catalog entries in this package, not host-built schemas.
+
+Use `listFormDefinitions()` (or the manifest) when a CMS needs a picker of available `formId`s. Deeper catalog rules: [`src/definitions/context.md`](src/definitions/context.md).
+
+## 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`                      |
+
+Appearances for both: `light` | `navy`.
+
+`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).
+
+## Install
+
+Registry package name, scope, and CDN base URL are **TBD** — examples below use the working package name `@usgb/forms` and a placeholder CDN host. Replace them when publishing is finalized.
+
+### npm (React / PWA)
 
 ```bash
-npm install
-npm test
-npm run build
+yarn add @usgb/forms
+# or
+npm install @usgb/forms
 ```
 
-Peer dependencies: `react` and `react-dom` >= 18.
+Then import the component and stylesheet:
+
+```ts
+import { UsgbForm } from '@usgb/forms'
+import '@usgb/forms/usgb-forms.css'
+```
 
-## Publish with OIDC
+Peer dependency: `react` and `react-dom` `^18` or `^19`.
 
-Trusted publishing creates a trust relationship between npm and this repository. GitHub Actions mints a short-lived OIDC token; npm CLI 11.5.1+ exchanges it for a publish credential. No npm write token is stored in GitHub.
+### CDN (Web Component / WordPress)
 
-Requirements:
+Load the built IIFE (styles inject themselves):
+
+```html
+<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.
+
+Until the package is published, you can still develop against a local checkout (`yarn add file:../usgb-forms` or `yarn link`).
+
+## React (PWA)
+
+```tsx
+import { UsgbForm, createStubAdapter, PWA_LEGAL_URLS } from '@usgb/forms'
+import '@usgb/forms/usgb-forms.css'
+;<UsgbForm
+    formId="main-investors-kit"
+    appearance="navy"
+    variants={['large', 'two-column']}
+    heading="Get My Free Guide"
+    body="Enter your details to receive the Main Investors Kit."
+    ctaLabel="GET MY FREE GUIDE"
+    source="cms-home"
+    campaign="spring-kit"
+    legalUrls={PWA_LEGAL_URLS}
+    successMessage="Thanks — we will send your kit shortly."
+    adapter={yourHostAdapter}
+    onAccepted={(payload) => {
+        /* analytics bridge */
+    }}
+    onFailed={(payload, message) => {
+        /* error bridge */
+    }}
+/>
+```
 
-- Node 22.14.0+ (this workflow uses Node 24)
-- npm 11.5.1+
-- GitHub-hosted runners (self-hosted runners are not supported)
-- A public GitHub repository if you want automatic provenance attestations
+Newsletter (no consent, no variants):
 
-### 1. Point `package.json` at the real package and repo
+```tsx
+<UsgbForm
+    formId="newsletter"
+    appearance="light"
+    heading="Subscribe"
+    ctaLabel="SUBSCRIBE"
+    adapter={yourHostAdapter}
+/>
+```
 
-Update these fields before the first publish. npm checks that `repository.url` matches the GitHub repository that is publishing:
+### React props
+
+| Prop                      | Required                   | Role                                                                                                |
+| ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
+| `formId`                  | yes                        | Catalog key (`main-investors-kit`, `newsletter`, …)                                                 |
+| `adapter`                 | yes                        | `HostAdapter` with `host`, `getTrackingHints()`, `submit()`                                         |
+| `appearance`              | no                         | `light` (default) or `navy`                                                                         |
+| `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                                                                                 |
+| `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                                                       |
+| `successUrl`              | no                         | Redirect after accept (analytics / `onAccepted` are invoked first; see Success behavior)            |
+| `analytics`               | no                         | `(event) => void` for view / validation / submit / success / failure                                |
+| `className`               | no                         | Extra class on `.usgb-form`                                                                         |
+| `onAccepted` / `onFailed` | no                         | Callbacks with the submission payload                                                               |
+
+## Web Component (WordPress)
+
+Load one script. Styles are injected automatically.
+
+````html
+<script src="https://cdn.example.com/usgb-forms/usgb-forms.1.0.0.js"></script>
+<usgb-form
+    ```
+    form-id="main-investors-kit"
+    appearance="navy"
+    variant="large two-column"
+    heading="Get My Free Guide"
+    cta="GET MY FREE GUIDE"
+    source="cms-home"
+    client-agreement-url="/client-agreement/"
+    privacy-policy-url="/privacy-policy/"
+    success-message="Thanks — we will send your kit shortly."
+></usgb-form>
+````
+
+Submit is **not** an attribute. Markup alone uses a stub adapter. Assign a real `HostAdapter` in script:
+
+```html
+<script>
+    const el = document.querySelector('usgb-form')
+    el.adapter = {
+        host: 'wordpress',
+        getTrackingHints() {
+            // Cookies, UTMs, click ids — keys must match the package tracking registry
+            return {}
+        },
+        async submit(payload) {
+            const res = await fetch('/your-form-submit', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload)
+            })
+            if (!res.ok) return { status: 'failed', message: res.statusText }
+            return { status: 'accepted' }
+        }
+    }
+
+    el.addEventListener('usgb-form:success', (e) => {
+        /* e.detail is SubmissionPayload */
+    })
+    el.addEventListener('usgb-form:failure', (e) => {
+        /* e.detail = { payload, message } */
+    })
+</script>
+```
 
-```json
-{
-  "name": "@your-scope/forms",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/OWNER/REPO.git"
-  }
+### Attribute map
+
+| Attribute                                       | React prop                                                    |
+| ----------------------------------------------- | ------------------------------------------------------------- |
+| `form-id`                                       | `formId`                                                      |
+| `appearance`                                    | `appearance`                                                  |
+| `variant`                                       | `variants` (space-separated)                                  |
+| `heading` / `body`                              | `heading` / `body`                                            |
+| `cta`                                           | `ctaLabel`                                                    |
+| `source` / `campaign`                           | `source` / `campaign`                                         |
+| `success-message` / `success-url`               | `successMessage` / `successUrl`                               |
+| `client-agreement-url`, `privacy-policy-url`, … | `legalUrls.*`                                                 |
+| `host`                                          | Used only for the stub adapter before you assign `el.adapter` |
+
+## Host adapter
+
+```ts
+interface HostAdapter {
+    host: 'pwa' | 'wordpress'
+    getTrackingHints(): Partial<Record<TrackingKey, string | undefined>>
+    submit(payload: SubmissionPayload): Promise<SubmitResult>
 }
 ```
 
-### 2. Create the npm package (first publish only)
+-   `submit` must return `{ status: 'accepted' }` or `{ status: 'failed', message?: string }`.
+-   The package never embeds Workato, Magento, or WordPress endpoints.
+-   `createStubAdapter('pwa' | 'wordpress')` accepts every payload (playground / markup-only WC).
+-   Tracking keys and destination names live in `forms-manifest.json`. Hosts may supply values for registered keys; they must not invent new ones.
 
-Trusted publishers are configured on an existing package. Create the package on [npmjs.com](https://www.npmjs.com/) if it does not exist yet, or publish once with a granular token and then switch to OIDC.
+### Payload shape (summary)
 
-### 3. Add a trusted publisher on npmjs.com
+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.
 
-Open the package **Settings → Trusted Publisher**, choose **GitHub Actions**, and enter values that match this repository exactly (all fields are case-sensitive):
+## Consent and legal URLs
 
-| Field | Value |
-| --- | --- |
-| Organization or user | `OWNER` |
-| Repository | `REPO` |
-| Workflow filename | `publish.yml` |
-| Environment name | `npm-publish` |
-| Allowed actions | `npm publish` |
+Consent bundles are versioned and package-owned (checkboxes and/or clickwrap notices). Hosts only supply document **hrefs**.
 
-Use only the workflow filename (`publish.yml`), not `.github/workflows/publish.yml`. npm validates the top-level workflow that started the run.
+-   `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.
 
-### 4. Protect the GitHub environment (recommended)
+`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.
 
-Create a GitHub environment named `npm-publish` and add required reviewers if you want a human approval step before each release. The environment name in the workflow and on npmjs.com must match.
+## Success behavior
 
-### 5. Release
+1. Adapter returns `accepted`.
+2. `analytics({ type: 'success' })` and `onAccepted` / `usgb-form:success` run synchronously. The package does not `await` them.
+3. If `successUrl` / `success-url` is set, the page calls `window.location.assign` immediately after those callbacks return.
+4. Otherwise the form shows `successMessage` / `success-message`, or a package default thank-you line.
 
-Bump `version` in `package.json` without creating a git tag, then run the publish workflow from the Actions tab.
+### Redirect vs analytics
 
-```bash
-npm version patch --no-git-tag-version   # or minor / major
-git add package.json package-lock.json
-git commit -m "Release 0.1.1"
-git push origin main
-```
+Invocation order is fixed (hooks first, then navigate). Delivery is not. `location.assign` starts unload in the same turn, so a typical GTM / `gtag` / `dataLayer.push` / image pixel started in `analytics` or `onAccepted` can be cancelled before the beacon leaves — especially on Safari and slow networks. Same for async work inside a `usgb-form:success` listener: the CustomEvent is dispatched synchronously, but anything it schedules after return can die with the document.
+
+This package does **not** wait on a returned Promise, add a flush timeout, or call `sendBeacon` on the host’s behalf. A hung analytics callback must not trap the user on the submit screen.
+
+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.
+
+`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.
+
+## Styling
 
-In GitHub, open **Actions → Publish Package → Run workflow** and run it on `main`. [`.github/workflows/publish.yml`](.github/workflows/publish.yml) then:
+Light DOM with stable `usgb-` class names (not CSS-in-JS). Isolation comes from the prefix and from styling `.usgb-field-control` / `.usgb-btn` instead of bare `input` / `button`. Host theme rules can still win; load host CSS **after** this package’s stylesheet and override under `.usgb-form`.
 
-1. Requests `id-token: write` so Actions can mint an OIDC token
-2. Installs Node 24 (ships npm 11.x)
-3. Runs tests and the library build
-4. Publishes the version already in `package.json` with **no token secret**
+| Host          | How styles load                                |
+| ------------- | ---------------------------------------------- |
+| React         | `import '@usgb/forms/usgb-forms.css'`          |
+| Web Component | Injected as `<style id="usgb-forms-css">` once |
 
-npm automatically attaches [provenance](https://docs.npmjs.com/generating-provenance-statements/) for public packages published from a public repository. Do not pass `--provenance`; the CLI enables it when OIDC publishing is in use.
+Prefer **custom properties** on `.usgb-form` for color, type, and spacing:
 
-### 6. Lock down token publishing (recommended)
+```css
+.usgb-form {
+    --usgb-button-background: #123456;
+    --usgb-field-border: #cccccc;
+}
+
+.usgb-form[data-appearance='navy'] {
+    --usgb-button-background: #f4e08e;
+}
+```
+
+Use class selectors when a token does not exist (`.usgb-form .usgb-btn { border-radius: 0; }`).
 
-After the first OIDC publish succeeds, on the package **Settings → Publishing access** select **Require two-factor authentication and disallow tokens**. Trusted publishing keeps working because it does not use classic npm tokens.
+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-*`.
 
-## Workflow notes
+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.
 
-- `permissions.id-token: write` is required. Without it the CLI cannot obtain an OIDC token and publish fails with `ENEEDAUTH`.
-- Do not set `NODE_AUTH_TOKEN` or `NPM_TOKEN` on the publish step. A leftover token can mask a broken trusted-publisher config.
-- `actions/setup-node` must set `registry-url: https://registry.npmjs.org`.
-- If this workflow is later called from another workflow, npm still checks the **calling** workflow filename, and both jobs need `id-token: write`.
-- Private dependencies still need a **read-only** npm token for `npm ci`. Trusted publishing only authenticates `npm publish`.
+Visual styles are a ported snapshot of the PWA form kit. When PWA form styles change, update this package and bump the version.
+
+## Develop (package maintainers)
+
+```bash
+yarn install
+yarn dev      # Vite playground (tries :5174)
+yarn build
+yarn typecheck
+yarn lint
+yarn format
+```
 
-## Troubleshooting
+Prettier and ESLint match magento-frontend (4-space indent, single quotes, no semicolons, print width 80).
 
-| Symptom | Likely cause |
-| --- | --- |
-| `ENEEDAUTH` / unable to authenticate | Workflow filename, repo, or environment does not match the trusted publisher |
-| 404 during OIDC exchange | Trusted publisher is missing, or npm CLI is older than 11.5.1 |
-| Provenance missing | Repository or package is private |
-| `npm ci` fails on private deps | Need a read-only install token; OIDC does not apply to install |
+## Git
 
-See the [npm trusted publishing docs](https://docs.npmjs.com/trusted-publishers/) for the full provider matrix and security recommendations.
+Local repo only. Connect a GitHub remote later when ready to publish.

package/dist/forms-manifest.json

@@ -0,0 +1,249 @@
+{
+    "schemaVersion": "1.0.0",
+    "package": {
+        "name": "@usgb/forms",
+        "compatiblePackageVersions": "^1.0.0"
+    },
+    "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"
+            ],
+            "consent": {
+                "definitionId": "lead-tcpa",
+                "definitionVersion": "1",
+                "required": true,
+                "submitFields": [
+                    "tcpa_form_consent_granted",
+                    "tcpa_form_opt_in_date"
+                ]
+            },
+            "editor": {
+                "label": "Main Investors Kit",
+                "description": "Standard lead form: name, email, phone, TCPA consent. Use on full-width landing pages and PWA kit/sidebar placements.",
+                "whenToUse": "Default kit request. Do not use for affiliate landers or IRA-specific leads.",
+                "whenNotToUse": "Affiliate pages (separate definition). IRA kit (separate definition when added).",
+                "supportedAppearances": ["light", "navy"],
+                "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"
+            ],
+            "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": ["light", "navy"],
+                "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"
+        ]
+    }
+}