@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/contracts/runtime-recipe.campaigns-os-node-v1.json

@@ -105,6 +105,7 @@
     "_note": "The complete input set, enumerated explicitly rather than globbed. The compiler's configured include globs are NOT the input set: two root modules enter the compilation transitively through imports from the entry module and are emitted, so a fingerprint derived from the globs would cover 36 of the 38 compiled sources and miss one of the larger emitted surfaces. Test fixtures and the package's own tests are not inputs; nothing under them is emitted. A checker resolves the compiler's actual file list and asserts it equals this enumeration, so this list cannot rot silently.",
     "fingerprint_algorithm": "sha256",
     "files": [
+      "campaign-spec/analytics-vendors.ts",
       "campaign-spec/analytics-vocabulary.ts",
       "campaign-spec/checkout-flow.ts",
       "campaign-spec/index.ts",
@@ -113,9 +114,11 @@
       "campaign-spec/routing.ts",
       "campaign-spec/rules/analytics-contract-shape.ts",
       "campaign-spec/rules/assembly-hints-shape.ts",
+      "campaign-spec/rules/campaign-currencies.ts",
       "campaign-spec/rules/campaign-metadata.ts",
       "campaign-spec/rules/checkout-forward-target.ts",
       "campaign-spec/rules/checkout-has-success-url.ts",
+      "campaign-spec/rules/checkout-path-has-packages.ts",
       "campaign-spec/rules/checkout-step-reaches-checkout.ts",
       "campaign-spec/rules/cycle-detection.ts",
       "campaign-spec/rules/design-source-shape.ts",

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.60.0",
+  "surface_version": "1.62.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -52,28 +52,28 @@
       "sha256": "53269453dfdaac4b286124d445b60b0c46205dfbaf8037ac61b30254a32df53a"
     },
     "contracts/runtime-recipe.campaigns-os-node-v1.json": {
-      "sha256": "ab0537a4756310d3a35b400d3932e46695a820f1b8b398f52f6fd0906098bc1d"
+      "sha256": "3a960f347a8b7de7d9f223fb2bc1ae35091c943d480bca931bf8afa5e70fa83f"
     },
     "schemas/campaign-build-brief.v1.schema.json": {
       "sha256": "d524003184131398dc15fdb84385af1be0de0c69d6c5ede7278689a5b6101b81"
     },
     "schemas/campaign-design-source-package.v0.schema.json": {
-      "sha256": "65bcd8b5f41f1e9ecfc36f3b8838cd4ed531bd74c5a318ee5147131f6c9b4a1c"
+      "sha256": "ecb8fd534977826541aa7110dad3483b7b9215dd60ed30b6370083848b957f13"
     },
     "schemas/campaign-runtime-assembly-report.v0.schema.json": {
       "sha256": "625a6f2ed6bee726f9cddad750e64a54a7e03744c777f5a70afe4a39afdd9848"
     },
     "schemas/campaign-runtime-build-context.v0.schema.json": {
-      "sha256": "2aa8f652f6bb602cdbadada34b5793da1bb8842223fcae2fd24700aac14f4de6"
+      "sha256": "501867cf95eca9b3d9ce8f2255ca8dfbb0c9e073a270794ab5e4203ed79e4658"
     },
     "schemas/campaign-runtime-build-packet.v0.schema.json": {
-      "sha256": "e57d31f190a7ddfbf63afb39bc67762a09dff25707c841e84a4e1c6ee9afd9ed"
+      "sha256": "1e309c5dad8c5eeef26ef6fd3b6b90b72440c5104319a161002b17f1359fbd76"
     },
     "schemas/campaign-spec.v4.schema.json": {
-      "sha256": "af56c3de638d3c4e1fd5df8c2d733754d9ad16caa23b5bec92ce3a6f71bd0271"
+      "sha256": "587df2fdd5707b515a9b8685d30070bcf4bdac9e15de7a94df82224ef4fd91b6"
     },
     "schemas/campaign-spec.v5.schema.json": {
-      "sha256": "2923382e94ac51f6a19a3f9dfd0993d8c30fab33cd9be3d6901f314e02f5d960"
+      "sha256": "c606453dc57d210a5a5ed8a099bf868546ae8f5996cf9ba0f8e71a50b2b03fa4"
     },
     "schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": {
       "sha256": "d6edc4572900d15fdaf6b8c59916b0d885303c1d398bdadeb7c58285522c9049"
@@ -112,7 +112,7 @@
       "sha256": "41ff370de4395149781d7e8c4ad6d7d4e2f896eb2030944399d36f1237726a20"
     },
     "schemas/source-html-manifest.v0.schema.json": {
-      "sha256": "841c1f884260ce3eb3ddb518960a127bc915992a9539c818e5986ce156acff1f"
+      "sha256": "58bc98b3fd07c87c6ba92d29b26941ca97200ea433d73f7418966f679841df49"
     },
     "schemas/campaigns-os-progress-snapshot.v0.schema.json": {
       "sha256": "ef31b4f20e39dfc1614dd4b45e4cf1692a51760b008cb51d133659307bd2a954"
@@ -121,10 +121,10 @@
       "sha256": "2e440be6513fe06b351c3a72c35424a04f807792621cb01e89803441fd925e06"
     },
     "schemas/campaigns-os-readback.v2.schema.json": {
-      "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
+      "sha256": "b397b417b0456cafc03346a2e882a34c19fa0500ea92594afca2f9fa1d7f2c3b"
     },
     "contracts/effects.v1.json": {
-      "sha256": "9c1d69e44eab7403ca3ff80f850214d89b0a02fdc51544beef37dbd0a653eeaa"
+      "sha256": "7aca3aa2208ccb700a74bc9554725a23b1f6c413e7ea7dc9ec442e884a8d72c3"
     },
     "schemas/campaigns-os-effects.v1.schema.json": {
       "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"

package/contracts/template-brand-contract.shared-commerce.v0.json

@@ -55,7 +55,7 @@
       },
       "asset_pin": {
         "repo": "NextCommerceCo/campaign-cart-starter-templates",
-        "sha": "3987b18a356cb961b06c94b2035622bafe938316",
+        "sha": "5711e22345756c655f41c0ae71444478e4a8999e",
         "path": "src/<family>/assets/<asset>",
         "note": "asset_sha256 is the sha256 of each shipped starter asset at this commit (the commerce-surface-catalog _synced_from_sha pin; the bytes are identical across every family). A served asset whose bytes hash to the shipped value is the untouched starter asset and counts as residue even though its markup names no method; different bytes mean it was edited in place. check-template-doctrine verifies these hashes against the pinned checkout."
       },
@@ -186,5 +186,27 @@
       "Apply My Discount Coupon"
     ],
     "rule": "If an exit-intent include or default widget ships without CampaignSpec checkout exit_intent or promo_code_input behavior, strip it or record a hard warning. If present, it must apply the mapped offer through the SDK/API coupon path and use cart.hasCoupon(\"CODE\") style conditionals for applied-state presentation."
+  },
+  "layout_conventions": {
+    "rule": "Design-independent layout conventions. polish capture measures them on every built page, in the same pass as readability, and reports each as a layout.conventions warning that checkpoint accept can accept. They never block Polish and never read or judge the merchant's copy. Polish reads this block from the shared contract; a family contract does not override it.",
+    "floating_cta": {
+      "key": "floating_cta",
+      "reason_code": "floating_cta_extra_content",
+      "viewports": ["mobile"],
+      "positions": ["fixed", "sticky"],
+      "control_selector": "a[href], button, input[type=\"submit\"], input[type=\"button\"], [role=\"button\"]",
+      "exclude_selector": "header, nav, dialog, [role=\"banner\"], [role=\"navigation\"], [role=\"dialog\"], [aria-modal=\"true\"], .announcement",
+      "form_field_selector": "input:not([type=\"hidden\"]):not([type=\"submit\"]):not([type=\"button\"]), select, textarea",
+      "max_viewport_height_share": 0.5,
+      "rule": "A floating CTA container holds the control alone: one link or button and no other visible text. A floating CTA container is the nearest box around a visible control (control_selector) whose computed position is one of positions. Boxes that match or sit inside exclude_selector, boxes that hold a visible form field (form_field_selector), and boxes taller than max_viewport_height_share of the viewport are not floating CTA containers. Visible text is text the browser renders, including CSS generated text; text inside the control does not count."
+    },
+    "cta_label": {
+      "key": "cta_label_size",
+      "reason_code": "cta_label_too_small",
+      "viewports": ["mobile"],
+      "roles": ["add_to_cart", "upsell_accept", "submit_control"],
+      "min_font_size_px": 16,
+      "rule": "The primary CTA label is at least min_font_size_px CSS px at the mobile viewport. The label is every rendered, enabled text element the readability record lists under one of roles (purchase and accept controls, and submit buttons)."
+    }
   }
 }

package/docs/access-model.md

@@ -0,0 +1,20 @@
+# Access Model
+
+Campaign developers should not need access to the private Campaigns OS runtime development repo.
+
+This repo is the developer-facing surface:
+
+- docs
+- schemas
+- examples
+- starter-template contract snapshots
+- agent skills
+- Build Packet doctor
+- checkpoint wrappers
+- issue templates
+
+Private platform/runtime development remains outside this repo. Do not copy private repo paths, client-specific examples, secrets, dashboard internals, or unpublished platform mutation procedures here.
+
+## Distribution
+
+This repo should stay suitable for public or partner access. Private runtime details, private repo paths, secrets, and client-specific implementation notes belong outside this surface.

package/docs/brand-theme-bridge.md

@@ -37,12 +37,66 @@ the accent fallback and the warning asks the operator to confirm it.
 ```text
 .campaign-runtime/theme/theme-report.json
 .campaign-runtime/theme/brand-theme.css
+.campaign-runtime/theme/brand-fonts.css   (only when the source ships brand faces)
 ```
 
 The generated CSS is v0 root-variable-only. It can override next-core custom
 properties such as `--brand--color--primary` and
 `--brand--color--cta-primary`, but it must not emit selectors, `data-next`
 selectors, payment/package/cart selectors, JavaScript, or remote URL fetches.
+The one exception is a `:root, body` block for the font-family tokens (see
+Typography below).
+
+### Typography
+
+Commerce pages keep the design's type, not the template's system stack.
+Inspection reads every CSS file the source pages link:
+
+- the `@font-face` rules the source ships;
+- which family its headings use (`h1`–`h3`, then `heading`/`title` classes);
+- which family its body copy uses (`html`, `body`, `p`, or the class a
+  stylesheet scopes itself under, such as the importer's `.cc-import`);
+- which family its buttons use, and the button `border-radius`.
+
+`var()` references resolve through custom properties on `:root`, `html`, `body`
+and that scope class, where Shopify themes keep `--font-body-family` and
+`--buttons-radius`. A family is mapped only when the source ships a face for
+it: a family the page can't load would only change the fallback, so it is
+left out, reported as a `theme.typography.face_unavailable` warning, and
+listed in the theme report's `typography.unavailable`.
+
+| Source | next-core token |
+| --- | --- |
+| heading family, then the generic the source gave it | `--_text---font-family--heading` |
+| body family (else the button family), then its generic | `--_text---font-family--primary` |
+| button radius (`0`, or one to four lengths or percentages) | `--radius-size--buttons` |
+
+A button radius in another form (`10px / 20px`, an unresolved `var()`) is not
+mapped and is listed in `typography.radius_rejected`.
+
+The targets are in the `typography` block of
+`contracts/brand-theme-target-tokens.next-core.v0.json`. next-core re-declares
+both font-family tokens on `body` inside its 991px, 767px and 479px media
+queries, so a `:root` value alone holds only on desktop. The generator emits
+them in a `:root, body` block. `brand-theme.css` loads after next-core, so its
+`body` declaration wins at every width.
+
+`brand-fonts.css` holds only `@font-face` rules for the mapped families. It
+always ships `font-display: swap`, whatever the source declared. A face the
+source declares once per format keeps every file, in source order. Its URLs are relative to `assets/css/`, pointing at the
+source's own font files, which build copies into the campaign's `assets/`
+tree with the rest of the source assets. A face whose file is remote, a
+`data:` URL, root-relative, outside the source root or missing is left out with
+`theme.typography.face_src_dropped`; containment is checked on real paths, so
+a symlink out of the source root is dropped. Family names are stripped of
+characters that could not appear in a quoted family. Button radius is mapped only alongside a
+mapped family, so a source with no brand faces generates exactly what it did
+before.
+
+Typography covers family and button radius only, because those are the only
+type and shape tokens next-core exposes. Heading weight, letter-spacing and
+text-transform stay at next-core's values: next-core renders headings at 700,
+so a design that sets headings at 600 shows its bold face on commerce pages.
 
 ### Foreground tokens are derived from background luminance
 
@@ -205,8 +259,10 @@ downsell, or receipt pages.
 
 If a fresh `brand-theme.css` exists:
 
-1. Copy it into the campaign asset tree.
-2. Add it to commerce page frontmatter styles after `next-core.css`.
+1. Copy it into the campaign asset tree (`assets/css/`), with
+   `brand-fonts.css` beside it when theme generate wrote one.
+2. Add it to commerce page frontmatter styles after `next-core.css`. List
+   `brand-fonts.css` on the same pages; its position does not matter.
 3. Preserve SDK-owned runtime surfaces: `data-next-*`, package selectors,
    payment fields, totals, submit controls, receipt templates, route meta tags,
    and SDK JavaScript.
@@ -215,7 +271,10 @@ If a fresh `brand-theme.css` exists:
    page's stylesheet links and records `report.theme.status`, `css_path`,
    `commerce_pages`, `load_order` and evidence. It refuses, writing nothing,
    when a page that loads `next-core.css` does not load the brand layer after
-   it, or when no built commerce page loads `next-core.css`.
+   it, when theme generate wrote `brand-fonts.css` (at the Build Context's
+   `theme.generated.fonts_css_path`) and a styled page does not load an
+   identical copy from inside the built site, or when no built commerce page
+   loads `next-core.css`.
 
 ### Where next-core.css belongs