@nextcommerce/campaigns-os 1.43.2 → 1.46.0

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.43.2",
+  "surface_version": "1.46.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -22,6 +22,7 @@
     "prepare-build",
     "build",
     "polish",
+    "record",
     "checkpoint",
     "page-kit",
     "spec",
@@ -92,7 +93,7 @@
       "sha256": "22dc5b48f12337163bd36307510e619f49e77331c974f45292ecd6e72175570d"
     },
     "schemas/campaigns-os-release-ledger.v1.schema.json": {
-      "sha256": "08ca132134b9e4610370e88082a5e888d09ddec0d5ee4512d84cc57181da722e"
+      "sha256": "d7521fe0ab4deb62485f92286cb890ee548ea290793a6ce7444ecc42ba336d49"
     },
     "schemas/campaigns-os-run-record.v0.schema.json": {
       "sha256": "00dc9bcec79c12ea22a27f636188bcc33c6811df2d646ac7b49d4cc076e97355"
@@ -101,7 +102,7 @@
       "sha256": "f8a2ab5eadbb71fb6d5653b670ee71e4471c3df74dd04000d3dbd3d9ae9e71fc"
     },
     "schemas/campaigns-os-tooling-orientation.v1.schema.json": {
-      "sha256": "897b192c7b3965c84909616023879b0a269a2e727e10efdec1b34e4c33ec499f"
+      "sha256": "8a2431b564041e8d2cbfaaf9d77ec272249268e54f5fc8952681537e0ad06e7c"
     },
     "schemas/campaigns-os-workflow-finding.v0.schema.json": {
       "sha256": "41ff370de4395149781d7e8c4ad6d7d4e2f896eb2030944399d36f1237726a20"
@@ -119,7 +120,7 @@
       "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
     },
     "contracts/effects.v1.json": {
-      "sha256": "1dae66e70bb5d167ca407d4ad03e70a1e2e761407b8ad7b85c8a7a51456df858"
+      "sha256": "794fe51952685e5afe6eee1988ce0230aae7a15a64fa1efdb350624158796f9c"
     },
     "schemas/campaigns-os-effects.v1.schema.json": {
       "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"
@@ -148,6 +149,8 @@
     "AGENTS.md",
     "CHANGELOG.md",
     "contracts/release-ledger.json",
+    "contracts/archive/release-ledger.2026-09-30.json",
+    "contracts/archive/CHANGELOG.2026-09-30.md",
     "contracts/agent-relevant-change-policy.v1.json",
     "contracts/orientation-limits.v1.json",
     "contracts/orientation-reason-codes.v1.json",

package/contracts/template-slot-manifest.shared-content-core.v0.json

@@ -3932,6 +3932,36 @@
               "description": "Page-kit page metadata \u2014 template-owned, assembly never touches.",
               "source_policy": "template_static"
             },
+            {
+              "key": "announcement_text",
+              "kind": "copy",
+              "role": "micro",
+              "description": "Top announcement bar on the upsell page, e.g. 'Special Offer Unlocked - Do Not Close This Page'.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 20,
+                "max": 90
+              }
+            },
+            {
+              "key": "upsell_hero",
+              "kind": "copy",
+              "role": "headline",
+              "description": "Structured upsell hero: title plus offer/suboffer/heading/text lines and a presentation variant. Hint: {price}, {package_name}, {discount} and {first_name} are SDK-resolved tokens, so keeping them keeps the copy in sync with live pricing. The length band applies to each copy string, not the whole block.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 15,
+                "max": 140
+              }
+            },
+            {
+              "key": "upsell_layout",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Structured layout knobs for the shared upsell offer shell (style, boxed, media, media_position, media_align, show_* toggles, decline_position). Template-owned presentation, assembly never touches.",
+              "source_policy": "template_static"
+            },
             {
               "key": "upsell_offer",
               "kind": "commerce",
@@ -4015,6 +4045,36 @@
               "description": "Page-kit page metadata \u2014 template-owned, assembly never touches.",
               "source_policy": "template_static"
             },
+            {
+              "key": "announcement_text",
+              "kind": "copy",
+              "role": "micro",
+              "description": "Top announcement bar on the upsell page, e.g. 'Special Offer Unlocked - Do Not Close This Page'.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 20,
+                "max": 90
+              }
+            },
+            {
+              "key": "upsell_hero",
+              "kind": "copy",
+              "role": "headline",
+              "description": "Structured upsell hero: title plus offer/suboffer/heading/text lines and a presentation variant. Hint: {price}, {package_name}, {discount} and {first_name} are SDK-resolved tokens, so keeping them keeps the copy in sync with live pricing. The length band applies to each copy string, not the whole block.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 15,
+                "max": 140
+              }
+            },
+            {
+              "key": "upsell_layout",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Structured layout knobs for the shared upsell offer shell (style, boxed, media, media_position, media_align, show_* toggles, decline_position). Template-owned presentation, assembly never touches.",
+              "source_policy": "template_static"
+            },
             {
               "key": "upsell_offer",
               "kind": "commerce",
@@ -4106,6 +4166,36 @@
               "description": "Page-kit page metadata \u2014 template-owned, assembly never touches.",
               "source_policy": "template_static"
             },
+            {
+              "key": "announcement_text",
+              "kind": "copy",
+              "role": "micro",
+              "description": "Top announcement bar on the upsell page, e.g. 'Special Offer Unlocked - Do Not Close This Page'.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 20,
+                "max": 90
+              }
+            },
+            {
+              "key": "upsell_hero",
+              "kind": "copy",
+              "role": "headline",
+              "description": "Structured upsell hero: title plus offer/suboffer/heading/text lines and a presentation variant. Hint: {price}, {package_name}, {discount} and {first_name} are SDK-resolved tokens, so keeping them keeps the copy in sync with live pricing. The length band applies to each copy string, not the whole block.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 15,
+                "max": 140
+              }
+            },
+            {
+              "key": "upsell_layout",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Structured layout knobs for the shared upsell offer shell (style, boxed, media, media_position, media_align, show_* toggles, decline_position). Template-owned presentation, assembly never touches.",
+              "source_policy": "template_static"
+            },
             {
               "key": "upsell_offer",
               "kind": "commerce",
@@ -4142,6 +4232,319 @@
         }
       ]
     },
+    "upsell-single": {
+      "sections": [
+        {
+          "section": "main",
+          "slots": [
+            {
+              "key": "title",
+              "kind": "copy",
+              "role": "micro",
+              "description": "Short copy slot.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 15,
+                "max": 67
+              },
+              "demo_value": "Apollo \u2014 Upsell (single offer)"
+            },
+            {
+              "key": "page_type",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Page-kit page metadata \u2014 template-owned, assembly never touches.",
+              "source_policy": "template_static"
+            },
+            {
+              "key": "next_url",
+              "kind": "link",
+              "role": "routing",
+              "description": "Route/link target.",
+              "source_policy": "spec_truth"
+            },
+            {
+              "key": "decline_url",
+              "kind": "link",
+              "role": "routing",
+              "description": "Route/link target.",
+              "source_policy": "spec_truth"
+            },
+            {
+              "key": "scripts",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Page-kit page metadata \u2014 template-owned, assembly never touches.",
+              "source_policy": "template_static"
+            },
+            {
+              "key": "announcement_text",
+              "kind": "copy",
+              "role": "micro",
+              "description": "Top announcement bar on the upsell page, e.g. 'Special Offer Unlocked - Do Not Close This Page'.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 20,
+                "max": 90
+              }
+            },
+            {
+              "key": "upsell_hero",
+              "kind": "copy",
+              "role": "headline",
+              "description": "Structured upsell hero: title plus offer/suboffer/heading/text lines and a presentation variant. Hint: {price}, {package_name}, {discount} and {first_name} are SDK-resolved tokens, so keeping them keeps the copy in sync with live pricing. The length band applies to each copy string, not the whole block.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 15,
+                "max": 140
+              }
+            },
+            {
+              "key": "countdown_timer",
+              "kind": "copy",
+              "role": "micro",
+              "description": "Structured SDK countdown (text, highlight, duration, persistence_id). The length band applies to each copy string (text, highlight).",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 6,
+                "max": 40
+              }
+            },
+            {
+              "key": "upsell_layout",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Structured layout knobs for the shared upsell offer shell (style, boxed, media, media_position, media_align, show_* toggles, decline_position). Template-owned presentation, assembly never touches.",
+              "source_policy": "template_static"
+            },
+            {
+              "key": "upsell_offer",
+              "kind": "commerce",
+              "role": "commerce_structure",
+              "owner": "commerce",
+              "description": "Structured commerce configuration \u2014 owned by the commerce-surface catalog and the family brand contract, not the content-slot layer.",
+              "reference": "integrated_commerce_surface_ref"
+            },
+            {
+              "key": "upsell_body",
+              "kind": "copy",
+              "role": "body",
+              "description": "Structured upsell body sections (features, comparison, steps, reviews). The length band applies to each copy string, not the whole block.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 10,
+                "max": 240
+              }
+            },
+            {
+              "key": "closing_cta",
+              "kind": "copy",
+              "role": "cta",
+              "description": "Structured closing accept/decline block (variant, title, note, show_guarantees). The length band applies to each copy string (title, note).",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 10,
+                "max": 140
+              }
+            }
+          ]
+        }
+      ]
+    },
+    "upsell-vsl": {
+      "sections": [
+        {
+          "section": "main",
+          "slots": [
+            {
+              "key": "title",
+              "kind": "copy",
+              "role": "micro",
+              "description": "Short copy slot.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 15,
+                "max": 67
+              },
+              "demo_value": "Apollo \u2014 Upsell (VSL)"
+            },
+            {
+              "key": "page_type",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Page-kit page metadata \u2014 template-owned, assembly never touches.",
+              "source_policy": "template_static"
+            },
+            {
+              "key": "next_url",
+              "kind": "link",
+              "role": "routing",
+              "description": "Route/link target.",
+              "source_policy": "spec_truth"
+            },
+            {
+              "key": "decline_url",
+              "kind": "link",
+              "role": "routing",
+              "description": "Route/link target.",
+              "source_policy": "spec_truth"
+            },
+            {
+              "key": "styles",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Page-kit page metadata \u2014 template-owned, assembly never touches.",
+              "source_policy": "template_static"
+            },
+            {
+              "key": "scripts",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Page-kit page metadata \u2014 template-owned, assembly never touches.",
+              "source_policy": "template_static"
+            },
+            {
+              "key": "announcement_text",
+              "kind": "copy",
+              "role": "micro",
+              "description": "Top announcement bar on the upsell page, e.g. 'Special Offer Unlocked - Do Not Close This Page'.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 20,
+                "max": 90
+              }
+            },
+            {
+              "key": "announcement_variant",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Announcement bar style knob (e.g. danger). Template-owned presentation, assembly never touches.",
+              "source_policy": "template_static"
+            },
+            {
+              "key": "header_bar",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Header style knob for the upsell page (e.g. logo-only). Template-owned presentation, assembly never touches.",
+              "source_policy": "template_static"
+            },
+            {
+              "key": "upsell_hero",
+              "kind": "copy",
+              "role": "headline",
+              "description": "Structured upsell hero: title plus offer/suboffer/heading/text lines and a presentation variant. Hint: {price}, {package_name}, {discount} and {first_name} are SDK-resolved tokens, so keeping them keeps the copy in sync with live pricing. The length band applies to each copy string, not the whole block.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 15,
+                "max": 140
+              }
+            },
+            {
+              "key": "countdown_timer",
+              "kind": "copy",
+              "role": "micro",
+              "description": "Structured SDK countdown (text, highlight, duration, persistence_id). The length band applies to each copy string (text, highlight).",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 6,
+                "max": 40
+              }
+            },
+            {
+              "key": "upsell_layout",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Structured layout knobs for the shared upsell offer shell (style, boxed, media, media_position, media_align, show_* toggles, decline_position). Template-owned presentation, assembly never touches.",
+              "source_policy": "template_static"
+            },
+            {
+              "key": "upsell_offer",
+              "kind": "commerce",
+              "role": "commerce_structure",
+              "owner": "commerce",
+              "description": "Structured commerce configuration \u2014 owned by the commerce-surface catalog and the family brand contract, not the content-slot layer.",
+              "reference": "integrated_commerce_surface_ref"
+            },
+            {
+              "key": "upsell_video",
+              "kind": "image",
+              "role": "image",
+              "description": "Structured upsell video (src, poster, title, autoplay, loop).",
+              "source_policy": "merchant_asset_required"
+            },
+            {
+              "key": "swiper_slides",
+              "kind": "commerce",
+              "role": "commerce_structure",
+              "owner": "commerce",
+              "description": "Structured commerce configuration \u2014 owned by the commerce-surface catalog and the family brand contract, not the content-slot layer.",
+              "reference": "integrated_commerce_surface_ref"
+            },
+            {
+              "key": "swiper_thumbs",
+              "kind": "commerce",
+              "role": "commerce_structure",
+              "owner": "commerce",
+              "description": "Structured commerce configuration \u2014 owned by the commerce-surface catalog and the family brand contract, not the content-slot layer.",
+              "reference": "integrated_commerce_surface_ref"
+            },
+            {
+              "key": "offer_bullets",
+              "kind": "copy",
+              "role": "body",
+              "description": "Bullet list beside the upsell offer. The length band applies to each bullet.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 15,
+                "max": 80
+              }
+            },
+            {
+              "key": "upsell_guarantees",
+              "kind": "copy",
+              "role": "body",
+              "description": "Structured guarantee/trust cards (e.g. secure checkout, money-back terms). The length band applies to each copy string (title, text).",
+              "source_policy": "spec_truth",
+              "length_band_chars": {
+                "min": 10,
+                "max": 200
+              }
+            },
+            {
+              "key": "upsell_body",
+              "kind": "copy",
+              "role": "body",
+              "description": "Structured upsell body sections (features, comparison, steps, reviews). The length band applies to each copy string, not the whole block.",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 10,
+                "max": 240
+              }
+            },
+            {
+              "key": "closing_cta",
+              "kind": "copy",
+              "role": "cta",
+              "description": "Structured closing accept/decline block (variant, title, note, show_guarantees). The length band applies to each copy string (title, note).",
+              "source_policy": "generated",
+              "length_band_chars": {
+                "min": 10,
+                "max": 140
+              }
+            }
+          ]
+        }
+      ]
+    },
     "receipt": {
       "sections": [
         {

package/docs/brand-theme-bridge.md

@@ -54,6 +54,65 @@ that still falls below the contract's `min_contrast_ratio` is emitted with a
 confirmed. Derived-foreground confidence scales with the achieved contrast
 (`>= 7:1` high, `>= 4.5:1` medium, otherwise low).
 
+One exception keeps the design's own CTA label. The declared CTA foreground is
+read from the selected source in this order:
+
+1. the `color:` of the button rules whose `background` or `background-color`
+   is the CTA background (the design's own pairing), only when they all agree
+   on one colour; when they disagree, this step declares nothing and the next
+   step applies;
+2. a `:root` inverse/on-colour text token: the name needs a `text` or
+   `foreground` part plus `inverse`, or `on` followed by `primary`, `cta`,
+   `brand`, `accent` or `dark` (`--text-inverse` first, then for example
+   `--text-color-inverse`, `--text-on-primary`, `--on-primary-text` or
+   `--foreground-on-dark`). `--border-on-primary`, `--overlay-on-dark` and a
+   bare `--on-primary` are not text and never qualify;
+3. the `color:` of the other button rules that declare no background, only when
+   they all agree on one colour.
+
+A button rule is one whose every selector ends in a compound selector that is
+the `button` element, `input[type=submit]`, or a class starting with
+`btn`, `button` or `cta` or having a `cta` part (`.btn-primary`, `.button`,
+`.cta`, `.hero-cta`). An attribute alone does not make a button:
+`[type=submit]`, `div[type="submit"]` and `.order-summary[type=submit]` do not
+qualify. Only the compound's own element, class and attribute
+selectors count: the value inside an attribute selector and the arguments of
+`:not()`, `:is()`, `:where()` and `:has()` are not read, so
+`.btn-primary[data-x]` and `button:not(.order-summary)` qualify while
+`.order-summary[data-target=".btn"]`, `.order-summary:not(.btn)` and
+`.cart:has(.button)` do not. Any other pseudo-class or pseudo-element
+(`:hover`, `:disabled`, `::before`) disqualifies the selector. Selectors such
+as `.order-summary` or `.cart-count`, and `.btn .icon`, never qualify. When that
+colour reaches at least 3:1 on the CTA background (WCAG AA for large text),
+`--brand--color--text-inverse` and `--brand--color--cta-foreground` use it
+(`derivation.method: declared-cta-foreground`). White on `#dd4249` is 4.24:1,
+so a design that declares white CTA text keeps white, although black scores
+higher there. A declared colour under 3:1 is ignored and the luminance pick
+applies, so a white scaffold default on a yellow CTA still resolves dark. A
+declared colour between 3:1 and the contract's `min_contrast_ratio` (4.5:1) is
+used and reported with `theme.foreground.low_contrast`. With no declared CTA
+foreground, the output is unchanged. Declarations inside CSS comments are not
+read, so a commented-out token or rule never supplies a CTA or body text colour.
+
+### Body text prefers the darkest declared text token
+
+A declared text token is a `:root` custom property in the selected source whose
+name has a `text` part and whose value is a solid colour. Names that carry
+another job are not counted: inverse/on-colour labels (`text` or `foreground`
+with `inverse` in any order, or `on` followed by `primary`, `cta`, `brand`,
+`accent` or `dark`; `--text-on-light` is ordinary copy), `secondary`, `muted` or
+`subtle` copy, link, status and state colours (`link`, `error`, `danger`,
+`success`, `warning`, `info`, `highlight`, `accent`, `placeholder`, `disabled`,
+`selection`), `cta`/`button`/`btn` labels, and text `shadow`, `border`,
+`outline`, `stroke`, `bg` or `background` values. When the source has a solid
+body background (`--surface-bg`), `--brand--color--text-primary` and
+`--brand--color--foreground` take the darkest declared text token that is
+darker than that background and reaches 4.5:1 on it
+(`derivation.method: darkest-declared-text-token`, with the replaced value
+recorded, or `null` when the source yielded no `--text-primary`). This applies
+whether or not the source yields a `--text-primary` of its own. If no token
+qualifies, the existing pick (or its absence) stands.
+
 > **Contract change (PR #117):** `--text-inverse` and the three `*-foreground`
 > targets are no longer entries under `source_mappings` — they moved to
 > `foreground_derivations`. A source `--text-inverse` token (or anything that
@@ -141,6 +200,28 @@ If a fresh `brand-theme.css` exists:
 4. Record `report.theme.status`, `css_path`, `commerce_pages`, `load_order`,
    and evidence.
 
+### Where next-core.css belongs
+
+`next-core.css` and the brand layer are needed only on pages where the
+starter-template family's components render, because those components read
+the `--brand--*` tokens. `next-core.css` also carries element resets (`li`,
+`a`, headings, body letter-spacing) that restyle any markup on the page. On a
+page whose upsell, downsell or receipt markup comes from the design rather
+than from family components, loading it breaks that markup. Leave both
+stylesheets off those pages and list them only in the frontmatter styles of
+the pages that render family components, often just checkout.
+
+`report.theme.commerce_pages` is the list of pages where the brand layer was
+applied, recorded by the build. Record the pages you actually scoped, for
+example `commerce_pages: ["checkout"]`. The theme gate does not compare this
+list with the funnel. It passes on `report.theme.status: applied` with
+`load_order: after-next-core`. The gate's own `commerce_pages` output is a
+different field: every checkout, upsell, downsell, receipt or thank-you page
+the campaign builds or declares. It decides whether the gate applies, not
+which pages must load the brand layer. No check reads each built page's
+stylesheet order, so the recorded list and the evidence are what a reviewer
+sees.
+
 Polish should verify token parity, load order after next-core, starter-logo
 replacement when source assets expose a real brand mark, and SDK safety. If the
 brand layer is repairable, record the first repair-loop defect.