@nextcommerce/campaigns-os 1.61.0 → 1.63.0

package/agents/codex/AGENTS.md

@@ -7,6 +7,7 @@ A NEXT campaign is one connected commerce journey: the pages the CampaignSpec de
 - Read `campaign-runtime.build.json` first.
 - To pick up an existing campaign, run `npx --no-install campaigns-os readback .` and `npx --no-install campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`.
 - If `.campaign-runtime/build-context.json` or `.campaign-runtime/assembly-report.json` exists, read them before editing campaign files.
+- A project that holds several funnels has one Build Packet per funnel: `campaign-runtime.build.json` for the first funnel set up, whose records are directly under `.campaign-runtime/`, and `campaign-runtime-<route>.build.json` for each other funnel, whose records are under `.campaign-runtime/funnels/<route>/` (its `assembly.runtime_dir`). Pass that funnel's packet with `--packet` to every command, `readback . --packet` included; without one, readback refuses and names the packets.
 - Run `npx --no-install campaigns-os doctor --packet campaign-runtime.build.json` before build work.
 - Treat CampaignSpec validation as owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available.
 - Respect the selected template family's `agentContract`.
@@ -37,10 +38,13 @@ A NEXT campaign is one connected commerce journey: the pages the CampaignSpec de
    Readback's `evidence_debt` compares the build on disk with the builds Polish and QA were recorded for.
    Changed pages are listed against the recorded assembly build manifest; an owed stage with an empty page list still means evidence is owed.
 2. For pages built from a provided design, the Design Source Package is the authority, not the punch list's wording.
-3. Before opening the pull request, after the final edit, rebuild, then run `npx --no-install campaigns-os record build --packet campaign-runtime.build.json`,
-   `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>` for the whole route,
-   and `npx --no-install campaigns-os record polish --packet campaign-runtime.build.json --evidence <polish-evidence.json>`, in that order.
-   When QA is owed, run `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json` against that build.
+3. Before opening the pull request, after the final edit, rebuild, then run `npx --no-install campaigns-os record build --packet campaign-runtime.build.json`.
+   When `next` or the pull-request check says the change is page-only, run
+   `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json --page <page_id>` against that build,
+   with one `--page` for each changed page it names; Polish is optional for it.
+   Otherwise run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>` for the whole route
+   and `npx --no-install campaigns-os record polish --packet campaign-runtime.build.json --evidence <polish-evidence.json>`, in that order,
+   and when QA is owed, run `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json` against that build.
 4. In the pull request body, put the design reference and the preview of each changed page side by side.
 
 The standing pull-request check is `npx --no-install campaigns-os doctor --ci --packet campaign-runtime.build.json --no-live-refs`, report-only unless the repo opts in.

package/agents/copilot/copilot-instructions.md

@@ -5,6 +5,7 @@ When this repository contains Campaigns OS artifacts, use them as the build hand
 - `campaign-runtime.build.json` defines the CampaignSpec, source adapter, target output, template family, deploy target, SDK origin state, and QA proof depth.
 - `.campaign-runtime/build-context.json` records page mappings and setup/build handoff details.
 - `.campaign-runtime/assembly-report.json` records stage evidence and blockers.
+- A project that holds several funnels has one Build Packet per funnel: `campaign-runtime.build.json` for the first funnel set up, whose records are directly under `.campaign-runtime/`, and `campaign-runtime-<route>.build.json` for each other funnel, whose records are under `.campaign-runtime/funnels/<route>/` (its `assembly.runtime_dir`). Pass that funnel's packet with `--packet` to every command, `readback . --packet` included; without one, readback refuses and names the packets.
 - To pick up an existing campaign, run `npx --no-install campaigns-os readback .` and `npx --no-install campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`.
 - `.campaign-runtime/theme/theme-report.json`, when present, is optional brand-theme evidence. Generated `brand-theme.css` must load after `next-core.css`; missing or low-confidence theme is a warning/skipped reason, not permission to edit SDK-owned runtime surfaces.
 
@@ -23,10 +24,13 @@ Before Polish becomes terminal or hands off to deploy/QA, install the package-ow
    Readback's `evidence_debt` compares the build on disk with the builds Polish and QA were recorded for.
    Changed pages are listed against the recorded assembly build manifest; an owed stage with an empty page list still means evidence is owed.
 2. For pages built from a provided design, the Design Source Package is the authority, not the punch list's wording.
-3. Before opening the pull request, after the final edit, rebuild, then run `npx --no-install campaigns-os record build --packet campaign-runtime.build.json`,
-   `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>` for the whole route,
-   and `npx --no-install campaigns-os record polish --packet campaign-runtime.build.json --evidence <polish-evidence.json>`, in that order.
-   When QA is owed, run `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json` against that build.
+3. Before opening the pull request, after the final edit, rebuild, then run `npx --no-install campaigns-os record build --packet campaign-runtime.build.json`.
+   When `next` or the pull-request check says the change is page-only, run
+   `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json --page <page_id>` against that build,
+   with one `--page` for each changed page it names; Polish is optional for it.
+   Otherwise run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>` for the whole route
+   and `npx --no-install campaigns-os record polish --packet campaign-runtime.build.json --evidence <polish-evidence.json>`, in that order,
+   and when QA is owed, run `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json` against that build.
 4. In the pull request body, put the design reference and the preview of each changed page side by side.
 
 The standing pull-request check is `npx --no-install campaigns-os doctor --ci --packet campaign-runtime.build.json --no-live-refs`, report-only unless the repo opts in.

package/agents/cursor/campaigns-os.mdc

@@ -2,12 +2,15 @@
 description: Campaigns OS target campaign guidance
 globs:
   - "campaign-runtime.build.json"
+  - "campaign-runtime-*.build.json"
   - ".campaign-runtime/**/*.json"
 alwaysApply: false
 ---
 
 Read Campaigns OS artifacts before editing campaign pages. To pick up an existing campaign, run `npx --no-install campaigns-os readback .` and `npx --no-install campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`. Treat CampaignSpec/API values as live commerce truth, starter-template contracts as SDK surface truth, and designed HTML/assets as visual/content intent. Treat CampaignSpec validation as owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available. If `context.theme` or `.campaign-runtime/theme/theme-report.json` exists, use it as optional brand-theme evidence; generated `brand-theme.css` must load after `next-core.css`, and missing/low-confidence theme is a warning or skipped reason, not permission to edit SDK-owned runtime surfaces.
 
+A project that holds several funnels has one Build Packet per funnel: `campaign-runtime.build.json` for the first funnel set up, whose records are directly under `.campaign-runtime/`, and `campaign-runtime-<route>.build.json` for each other funnel, whose records are under `.campaign-runtime/funnels/<route>/` (its `assembly.runtime_dir`). Pass that funnel's packet with `--packet` to every command, `readback . --packet` included; without one, readback refuses and names the packets.
+
 A NEXT campaign is one connected commerce journey: the pages the CampaignSpec declares, in its order, through product choice, checkout, post-purchase offers and receipt. Creative intent — audience, purpose, layout, imagery, approved copy, visual style — belongs to the operator, the Campaign Build Brief and the accepted design source. Commerce behaviour — products, package IDs, prices, offers, shipping, routes, cart, checkout, payment and post-purchase — belongs to CampaignSpec/API values and the SDK. Before changing a campaign, read the normalized brief at `.campaign-runtime/input/campaign-build-brief.normalized.json` and the recorded decisions: `adapter_decisions`, `decisions` and `theme` in `.campaign-runtime/assembly-report.json`, and `assembly.template_decision_notes` in the Build Packet. The setup, build, Polish and QA prompts begin with a campaign intent summary, and every `next` result carries it (`intent_summary` in JSON); treat it as orientation, never as a source of prices or behaviour. When a revision is narrow, keep the recorded intent and ask only about missing choices that affect that revision. Ask the operator before saving brief answers.
 
 Do not carry over demo package, shipping, voucher, payment, tracking, footer, or SEO values. Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Preserve prepared landing/presell source HTML when it is a real standalone design. For checkout/upsell/downsell/receipt, use starter-template commerce surfaces as SDK contract references while campaign/source owns visual chrome. Reproduce the source design's own proof and urgency elements as designed (reviews, ratings, stock counters, countdowns, guarantees). They are the merchant's content; Campaigns OS does not review them, so do not remove, soften or flag them. Copy starter template families atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages. Emit SDK routing meta tags as campaign-root paths such as `/campaign-slug/upsell/`. Preserve SDK-owned checkout/cart/upsell/receipt surfaces. For `shop-three-step`, shipping is dynamic via `window.next.getShippingMethods()`.
@@ -21,10 +24,13 @@ Before Polish becomes terminal or hands off to deploy/QA, install the package-ow
    Readback's `evidence_debt` compares the build on disk with the builds Polish and QA were recorded for.
    Changed pages are listed against the recorded assembly build manifest; an owed stage with an empty page list still means evidence is owed.
 2. For pages built from a provided design, the Design Source Package is the authority, not the punch list's wording.
-3. Before opening the pull request, after the final edit, rebuild, then run `npx --no-install campaigns-os record build --packet campaign-runtime.build.json`,
-   `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>` for the whole route,
-   and `npx --no-install campaigns-os record polish --packet campaign-runtime.build.json --evidence <polish-evidence.json>`, in that order.
-   When QA is owed, run `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json` against that build.
+3. Before opening the pull request, after the final edit, rebuild, then run `npx --no-install campaigns-os record build --packet campaign-runtime.build.json`.
+   When `next` or the pull-request check says the change is page-only, run
+   `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json --page <page_id>` against that build,
+   with one `--page` for each changed page it names; Polish is optional for it.
+   Otherwise run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>` for the whole route
+   and `npx --no-install campaigns-os record polish --packet campaign-runtime.build.json --evidence <polish-evidence.json>`, in that order,
+   and when QA is owed, run `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json` against that build.
 4. In the pull request body, put the design reference and the preview of each changed page side by side.
 
 The standing pull-request check is `npx --no-install campaigns-os doctor --ci --packet campaign-runtime.build.json --no-live-refs`, report-only unless the repo opts in.

package/campaign-spec/README.md

@@ -145,6 +145,13 @@ shape — `CheckoutForwardTarget`, `PrePaymentForwardTarget`,
 reads page order or page names. `paymentPageFrom`, `checkoutPathFrom` and
 `paymentPagesForFunnel` answer "which Checkout is on this path".
 
+`CheckoutPathHasPackages` adds that every path into a Checkout passes a page
+selling a main-cart package (an entry marked neither `is_upsell` nor
+`is_order_bump`; `isMainCartPackage` and `sellsMainCartPackage` in
+`checkout-flow.ts`). The selling page can be a select page, a landing page, a
+checkout step or the Checkout itself. The contract is written up in
+`../docs/template-family-contracts.md`, "Main-cart entry".
+
 ## See also
 
 - `../CONTEXT.md` — domain vocabulary.

package/campaign-spec/dist/analytics-vendors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Template analytics vendors: the eight direct vendor adapters the certified
+ * starter templates ship (GA4, AppLovin Axon, Taboola, Triple Whale, TikTok,
+ * Northbeam, Snapchat, Pinterest).
+ *
+ * A vendor is switched on by a flat key in the campaign's page-kit
+ * `_data/campaigns.json` entry (`ga4_id`, `triplewhale_name`, …): absent or
+ * empty means off. The template then loads the vendor's base snippet, the
+ * shared forwarder and the vendor adapter, which maps the SDK's dl_* stream to
+ * the vendor. These vendors are separate from the SDK providers in
+ * `analytics.providers` (gtm, facebook, rudderstack, custom), which reach the
+ * page through config.js.
+ *
+ * MIRROR of the Map Builder repo's `shared/route-c-vendors.mjs` (ROUTE_C_VENDORS,
+ * "Route C" in that repo), which drives the Map Builder `analytics.vendors`
+ * emit and the spec compiler's campaigns.json key upsert. The key table itself
+ * is the starter templates' `_shared/analytics/README.md`. Keep `key`,
+ * `idKey`, `platformKey`, `piiKey` and `numericId` identical to that registry;
+ * analytics-vendors.test.ts pins them.
+ */
+export interface AnalyticsVendorDefinition {
+    /** Key under `analytics.vendors` in the CampaignSpec. */
+    key: string;
+    /** Human label. */
+    label: string;
+    /** campaigns.json key that carries the vendor id and switches the vendor on. */
+    idKey: string;
+    /** campaigns.json key for the vendor platform (Triple Whale only). */
+    platformKey?: string;
+    /** campaigns.json key for the vendor's identity / advanced-matching (PII) flag. */
+    piiKey?: string;
+    /** True when the template injects the id unquoted, so it must be digits only. */
+    numericId?: boolean;
+}
+export declare const ANALYTICS_VENDORS: readonly AnalyticsVendorDefinition[];
+/** The `analytics.vendors` keys, in registry order. */
+export declare const ANALYTICS_VENDOR_KEYS: readonly string[];
+export declare function analyticsVendorByKey(key: string): AnalyticsVendorDefinition | undefined;
+/** Whether a vendor id looks like a documentation placeholder, not a real id. */
+export declare function isPlaceholderVendorId(value: string): boolean;

package/campaign-spec/dist/analytics-vendors.js

@@ -0,0 +1,44 @@
+/**
+ * Template analytics vendors: the eight direct vendor adapters the certified
+ * starter templates ship (GA4, AppLovin Axon, Taboola, Triple Whale, TikTok,
+ * Northbeam, Snapchat, Pinterest).
+ *
+ * A vendor is switched on by a flat key in the campaign's page-kit
+ * `_data/campaigns.json` entry (`ga4_id`, `triplewhale_name`, …): absent or
+ * empty means off. The template then loads the vendor's base snippet, the
+ * shared forwarder and the vendor adapter, which maps the SDK's dl_* stream to
+ * the vendor. These vendors are separate from the SDK providers in
+ * `analytics.providers` (gtm, facebook, rudderstack, custom), which reach the
+ * page through config.js.
+ *
+ * MIRROR of the Map Builder repo's `shared/route-c-vendors.mjs` (ROUTE_C_VENDORS,
+ * "Route C" in that repo), which drives the Map Builder `analytics.vendors`
+ * emit and the spec compiler's campaigns.json key upsert. The key table itself
+ * is the starter templates' `_shared/analytics/README.md`. Keep `key`,
+ * `idKey`, `platformKey`, `piiKey` and `numericId` identical to that registry;
+ * analytics-vendors.test.ts pins them.
+ */
+export const ANALYTICS_VENDORS = [
+    { key: 'ga4', label: 'GA4', idKey: 'ga4_id' },
+    { key: 'axon', label: 'AppLovin Axon', idKey: 'axon_event_key' },
+    { key: 'taboola', label: 'Taboola', idKey: 'taboola_account_id', numericId: true },
+    { key: 'triplewhale', label: 'Triple Whale', idKey: 'triplewhale_name', platformKey: 'triplewhale_platform', piiKey: 'triplewhale_contact_enabled' },
+    { key: 'tiktok', label: 'TikTok', idKey: 'tiktok_pixel_id', piiKey: 'tiktok_advanced_matching_enabled' },
+    { key: 'northbeam', label: 'Northbeam', idKey: 'northbeam_client_id', piiKey: 'northbeam_identity_enabled' },
+    { key: 'snap', label: 'Snapchat', idKey: 'snap_pixel_id', piiKey: 'snap_advanced_matching_enabled' },
+    { key: 'pinterest', label: 'Pinterest', idKey: 'pinterest_tag_id', piiKey: 'pinterest_enhanced_match_enabled' },
+];
+/** The `analytics.vendors` keys, in registry order. */
+export const ANALYTICS_VENDOR_KEYS = ANALYTICS_VENDORS.map((vendor) => vendor.key);
+export function analyticsVendorByKey(key) {
+    return ANALYTICS_VENDORS.find((vendor) => vendor.key === key);
+}
+// The same pattern the ops registry warns on (route-c-placeholder-id): a
+// placeholder-shaped id goes live on any non-development build, because the
+// template gate is only "non-empty". Bare XXXX also catches a half-edited
+// placeholder such as "G-XXXXABC123".
+const PLACEHOLDER_VENDOR_ID = /XXXX|YOUR[_-]|CHANGE[_-]?ME|<[^>]*>|EXAMPLE/i;
+/** Whether a vendor id looks like a documentation placeholder, not a real id. */
+export function isPlaceholderVendorId(value) {
+    return PLACEHOLDER_VENDOR_ID.test(value);
+}

package/campaign-spec/dist/checkout-flow.d.ts

@@ -41,6 +41,24 @@ export declare function isPaymentPage(page: Page | null | undefined): boolean;
 export declare function isCheckoutStepPage(page: Page | null | undefined): boolean;
 export declare function isPrePaymentPage(page: Page | null | undefined): boolean;
 export declare function isCheckoutFlowPage(page: Page | null | undefined): boolean;
+/**
+ * A main-cart package entry: one with neither `is_upsell: true` nor
+ * `is_order_bump: true` (campaigns-os#206, ratified 2026-09-17). Either flag
+ * marks a bump on a checkout page and an offer on an upsell; real exports mark
+ * checkout bumps with `is_upsell`, so the two are read as one signal.
+ * `default_selected` says which entry a selector starts on and never changes
+ * the role. Contract: docs/template-family-contracts.md, "Main-cart entry".
+ */
+export declare function isMainCartPackage(entry: unknown): boolean;
+/**
+ * True when `page` puts a main-cart package in front of the shopper: a page
+ * that is not a post-payment page and declares at least one main-cart entry.
+ * A select page's bundle picker, a landing page's package cards and a
+ * Checkout's own selector all count; page type beyond post-payment is not
+ * consulted. Upsell, downsell and thank-you entries are post-purchase offers,
+ * never the main cart.
+ */
+export declare function sellsMainCartPackage(page: Page | null | undefined): boolean;
 /**
  * The page a route target names within `pages`, or null when it names none
  * (an absolute URL, a fragment, a route outside this funnel, or a typo that

package/campaign-spec/dist/checkout-flow.js

@@ -53,6 +53,34 @@ export function isPrePaymentPage(page) {
 export function isCheckoutFlowPage(page) {
     return CHECKOUT_FLOW_PAGE_TYPES.includes(typeOf(page));
 }
+/**
+ * A main-cart package entry: one with neither `is_upsell: true` nor
+ * `is_order_bump: true` (campaigns-os#206, ratified 2026-09-17). Either flag
+ * marks a bump on a checkout page and an offer on an upsell; real exports mark
+ * checkout bumps with `is_upsell`, so the two are read as one signal.
+ * `default_selected` says which entry a selector starts on and never changes
+ * the role. Contract: docs/template-family-contracts.md, "Main-cart entry".
+ */
+export function isMainCartPackage(entry) {
+    if (!entry || typeof entry !== 'object')
+        return false;
+    const flags = entry;
+    return flags.is_upsell !== true && flags.is_order_bump !== true;
+}
+/**
+ * True when `page` puts a main-cart package in front of the shopper: a page
+ * that is not a post-payment page and declares at least one main-cart entry.
+ * A select page's bundle picker, a landing page's package cards and a
+ * Checkout's own selector all count; page type beyond post-payment is not
+ * consulted. Upsell, downsell and thank-you entries are post-purchase offers,
+ * never the main cart.
+ */
+export function sellsMainCartPackage(page) {
+    if (!page || POST_PAYMENT_PAGE_TYPES.includes(typeOf(page)))
+        return false;
+    const packages = page.packages;
+    return Array.isArray(packages) && packages.some(isMainCartPackage);
+}
 /**
  * Strip surrounding slashes and a `.html` suffix so a route target, a page ID
  * and a `page_url` compare on equal terms. The corpus writes targets in all

package/campaign-spec/dist/index.d.ts

@@ -11,17 +11,19 @@
  * Corpus, normalize) and ./README.md for usage patterns.
  */
 import type { CampaignSpec, RuleSet, Violation } from './types.ts';
-export type { CampaignSpec, Rule, RuleSet, Violation, Tag, Severity, Fixture, Page, PageType, Funnel, Offer, Campaign, DesignSource, DesignSourceBreakpoints, TemplateFamilyHint, UpsellTemplatePattern, UpsellMvTiers, VariantLabels, PromoCode, AnalyticsContract, AnalyticsMode, AnalyticsProvider, OutOfBandPixel, ManualEvent, ContentParam, TrackingParams, AnalyticsParams, UtmTransfer, } from './types.ts';
+export type { CampaignSpec, Rule, RuleSet, Violation, Tag, Severity, Fixture, Page, PageType, Funnel, Offer, Campaign, DesignSource, DesignSourceBreakpoints, TemplateFamilyHint, UpsellTemplatePattern, UpsellMvTiers, VariantLabels, PromoCode, AnalyticsContract, AnalyticsMode, AnalyticsProvider, AnalyticsVendor, OutOfBandPixel, ManualEvent, ContentParam, TrackingParams, AnalyticsParams, UtmTransfer, } from './types.ts';
 export { normalize, NormalizeError } from './normalize.ts';
 export { FORWARD_ROUTE_FIELDS, ACCEPT_ROUTE_FIELD, DECLINE_ROUTE_FIELD, ROUTE_FIELDS, PAYMENT_BEARING_PAGE_TYPES, OFFER_BEARING_PAGE_TYPES, forwardRouteTarget, acceptRouteTarget, declineRouteTarget, hasForwardRoute, applicableForwardFields, inapplicableForwardFields, describeForwardField, outgoingEdgeIds, } from './routing.ts';
 export type { ForwardFieldApplicability } from './routing.ts';
-export { CURRENT_SCHEMA_VERSION, PAYMENT_PAGE_TYPE, CHECKOUT_STEP_PAGE_TYPE, PRE_PAYMENT_PAGE_TYPES, CHECKOUT_FLOW_PAGE_TYPES, POST_PAYMENT_PAGE_TYPES, POST_PURCHASE_OFFER_PAGE_TYPES, isPaymentPage, isCheckoutStepPage, isPrePaymentPage, isCheckoutFlowPage, resolveRouteTargetPage, forwardTargetPage, checkoutPathFrom, paymentPageFrom, entryPages, paymentPageForFunnel, paymentPagesForFunnel, upgradeCampaignSpec, } from './checkout-flow.ts';
+export { CURRENT_SCHEMA_VERSION, PAYMENT_PAGE_TYPE, CHECKOUT_STEP_PAGE_TYPE, PRE_PAYMENT_PAGE_TYPES, CHECKOUT_FLOW_PAGE_TYPES, POST_PAYMENT_PAGE_TYPES, POST_PURCHASE_OFFER_PAGE_TYPES, isPaymentPage, isCheckoutStepPage, isPrePaymentPage, isCheckoutFlowPage, isMainCartPackage, sellsMainCartPackage, resolveRouteTargetPage, forwardTargetPage, checkoutPathFrom, paymentPageFrom, entryPages, paymentPageForFunnel, paymentPagesForFunnel, upgradeCampaignSpec, } from './checkout-flow.ts';
 export { allRules, fastRules, specOnlyRules } from './rules/index.ts';
 export { SUPPORTED_SCHEMA_VERSIONS } from './rules/schema-version.ts';
 export { RELEASED_SDK_VERSION_PATTERN, parseSdkVersion, isReleasedSdkVersion, describeSdkVersionRejection, } from './sdk-version-parse.ts';
 export type { SdkVersionParseResult, SdkVersionRejectionReason, } from './sdk-version-parse.ts';
 export { CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION, CAMPAIGN_CART_ANALYTICS_VOCABULARY_SDK_VERSION, DL_EVENTS, DL_EVENT_NAMES, DL_EVENT_NAME_SET, isKnownDlEvent, } from './analytics-vocabulary.ts';
 export type { DlEventCategory, DlEventDefinition, } from './analytics-vocabulary.ts';
+export { ANALYTICS_VENDORS, ANALYTICS_VENDOR_KEYS, analyticsVendorByKey, isPlaceholderVendorId, } from './analytics-vendors.ts';
+export type { AnalyticsVendorDefinition } from './analytics-vendors.ts';
 /**
  * Run a RuleSet against a normalized spec. Returns the flat list of
  * violations across all rules; callers choose their failure policy (throw on

package/campaign-spec/dist/index.js

@@ -20,7 +20,7 @@ export { FORWARD_ROUTE_FIELDS, ACCEPT_ROUTE_FIELD, DECLINE_ROUTE_FIELD, ROUTE_FI
 // Which page takes payment, and the pages leading to it (campaigns-os#641).
 // Every "the Checkout on this path" lookup asks here; upgradeCampaignSpec is
 // the v4 → v5 read-time upgrade normalize() applies.
-export { CURRENT_SCHEMA_VERSION, PAYMENT_PAGE_TYPE, CHECKOUT_STEP_PAGE_TYPE, PRE_PAYMENT_PAGE_TYPES, CHECKOUT_FLOW_PAGE_TYPES, POST_PAYMENT_PAGE_TYPES, POST_PURCHASE_OFFER_PAGE_TYPES, isPaymentPage, isCheckoutStepPage, isPrePaymentPage, isCheckoutFlowPage, resolveRouteTargetPage, forwardTargetPage, checkoutPathFrom, paymentPageFrom, entryPages, paymentPageForFunnel, paymentPagesForFunnel, upgradeCampaignSpec, } from "./checkout-flow.js";
+export { CURRENT_SCHEMA_VERSION, PAYMENT_PAGE_TYPE, CHECKOUT_STEP_PAGE_TYPE, PRE_PAYMENT_PAGE_TYPES, CHECKOUT_FLOW_PAGE_TYPES, POST_PAYMENT_PAGE_TYPES, POST_PURCHASE_OFFER_PAGE_TYPES, isPaymentPage, isCheckoutStepPage, isPrePaymentPage, isCheckoutFlowPage, isMainCartPackage, sellsMainCartPackage, resolveRouteTargetPage, forwardTargetPage, checkoutPathFrom, paymentPageFrom, entryPages, paymentPageForFunnel, paymentPagesForFunnel, upgradeCampaignSpec, } from "./checkout-flow.js";
 export { allRules, fastRules, specOnlyRules } from "./rules/index.js";
 // Supported schema_version matrix — single source for the SchemaVersion rule
 // and any consumer that needs to present or gate on the supported lineages.
@@ -35,6 +35,10 @@ export { RELEASED_SDK_VERSION_PATTERN, parseSdkVersion, isReleasedSdkVersion, de
 // The AnalyticsContractShape rule validates blockedEvents against it; the Map
 // Builder picker (via the campaign-spec.js shim) autocompletes from it.
 export { CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION, CAMPAIGN_CART_ANALYTICS_VOCABULARY_SDK_VERSION, DL_EVENTS, DL_EVENT_NAMES, DL_EVENT_NAME_SET, isKnownDlEvent, } from "./analytics-vocabulary.js";
+// The starter templates' analytics vendor adapters (analytics.vendors) and the
+// campaigns.json key each one is switched on by, mirrored from the ops
+// registry. spec derive and doctor read the same table.
+export { ANALYTICS_VENDORS, ANALYTICS_VENDOR_KEYS, analyticsVendorByKey, isPlaceholderVendorId, } from "./analytics-vendors.js";
 // ── Phases ─────────────────────────────────────────────────────────────────
 /**
  * Run a RuleSet against a normalized spec. Returns the flat list of

package/campaign-spec/dist/rules/analytics-contract-shape.d.ts

@@ -37,6 +37,14 @@
  *      "disabled"; missing mode means SDK defaults apply), runtime/global_config
  *      sdk_version should be an exact released semver >= the SDK identity
  *      baseline so events carry campaign/session ids.
+ *   9. `vendors`, when present, is an object keyed by one of the eight
+ *      starter-template vendor keys (analytics-vendors.ts); an unknown key is
+ *      carried but compiles to no campaigns.json key, so nothing loads it. Each
+ *      enabled vendor declares an `id` (the compiler skips a vendor without
+ *      one), and `allowedEvents` / `blockedEvents` are string arrays. The
+ *      id-format, placeholder and event-name checks for vendors live with the
+ *      ops registry the Map Builder export gate composes on top of this rule,
+ *      so they are not repeated here.
  */
 import type { Rule } from '../types.ts';
 export declare const AnalyticsContractShape: Rule;

package/campaign-spec/dist/rules/analytics-contract-shape.js

@@ -37,8 +37,17 @@
  *      "disabled"; missing mode means SDK defaults apply), runtime/global_config
  *      sdk_version should be an exact released semver >= the SDK identity
  *      baseline so events carry campaign/session ids.
+ *   9. `vendors`, when present, is an object keyed by one of the eight
+ *      starter-template vendor keys (analytics-vendors.ts); an unknown key is
+ *      carried but compiles to no campaigns.json key, so nothing loads it. Each
+ *      enabled vendor declares an `id` (the compiler skips a vendor without
+ *      one), and `allowedEvents` / `blockedEvents` are string arrays. The
+ *      id-format, placeholder and event-name checks for vendors live with the
+ *      ops registry the Map Builder export gate composes on top of this rule,
+ *      so they are not repeated here.
  */
 import { CAMPAIGN_CART_ANALYTICS_IDENTITY_MIN_SDK_VERSION, isKnownDlEvent, } from "../analytics-vocabulary.js";
+import { ANALYTICS_VENDOR_KEYS, analyticsVendorByKey } from "../analytics-vendors.js";
 const VALID_MODES = new Set(['auto', 'manual', 'disabled']);
 const PURCHASE_EVENT = /^(?:dl_)?purchase$/i;
 function isNonEmptyString(value) {
@@ -208,6 +217,36 @@ export const AnalyticsContractShape = {
                 }
             }
         }
+        // 9. vendors
+        const vendors = analytics.vendors;
+        if (vendors !== undefined) {
+            if (!isPlainAnalyticsObject(vendors)) {
+                warn(`analytics.vendors must be an object keyed by vendor (${ANALYTICS_VENDOR_KEYS.join(', ')}).`, '/analytics/vendors', 'vendors-not-object');
+            }
+            else {
+                for (const [key, vendor] of Object.entries(vendors)) {
+                    const base = `/analytics/vendors/${key}`;
+                    const definition = analyticsVendorByKey(key);
+                    if (!definition) {
+                        warn(`analytics.vendors.${key} is not a starter-template vendor (${ANALYTICS_VENDOR_KEYS.join(', ')}). No campaigns.json key is compiled for it, so nothing loads it; check for a typo, or declare a pixel loaded another way under out_of_band_pixels.`, base, 'vendor-unknown', { vendor: key });
+                        continue;
+                    }
+                    if (!vendor || typeof vendor !== 'object' || Array.isArray(vendor)) {
+                        warn(`analytics.vendors.${key} must be an object ({ enabled, id, … }).`, base, 'vendor-shape', { vendor: key });
+                        continue;
+                    }
+                    const entry = vendor;
+                    if (entry.enabled !== false && !isNonEmptyString(entry.id)) {
+                        warn(`analytics.vendors.${key} is enabled but has no id; the template loads ${definition.label} only when ${definition.idKey} is set, so it stays off.`, `${base}/id`, 'vendor-id-missing', { vendor: key });
+                    }
+                    for (const list of ['allowedEvents', 'blockedEvents']) {
+                        if (entry[list] !== undefined && !isStringArray(entry[list])) {
+                            warn(`analytics.vendors.${key}.${list} must be an array of event-name strings.`, `${base}/${list}`, 'vendor-events-shape', { vendor: key, list });
+                        }
+                    }
+                }
+            }
+        }
         const { pageIds, checkoutPageIds } = collectPageIds(spec);
         // 3. out_of_band_pixels
         if (analytics.out_of_band_pixels !== undefined) {

package/campaign-spec/dist/rules/campaign-currencies.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CampaignCurrencies — checks the campaign's default currency and its list of
+ * selling currencies (#714).
+ *
+ *   1. campaign.currency, when set, is a three-letter upper-case ISO 4217
+ *      code (error). A lower-case or made-up code can make Campaign Cart
+ *      fall back to a cached USD campaign, so the page shows the wrong prices
+ *      and nothing else complains.
+ *   2. campaign.available_currencies, when set, is an array whose every entry
+ *      is such a code (error). A `{ code, label }` object, the Campaigns API's
+ *      shape, is reported with the code it should be written as: Map Builder
+ *      writes code strings, and so should a hand-authored spec.
+ *   3. campaign.currency is one of campaign.available_currencies when that
+ *      list is non-empty (warning). An empty list states nothing and is
+ *      silent, since Map Builder exports [] for a campaign with no list.
+ *
+ * The spec owns `campaign.available_currencies`: every currency the campaign
+ * sells in, the default included. The Campaigns App API's
+ * `additional_currencies` is the same list without the default; it is not a
+ * CampaignSpec field, and this rule does not read it.
+ *
+ * An absent, null or empty currency is silent here: a missing default is a
+ * draft state, not a malformed code.
+ *
+ * The ISO list is `Intl.supportedValuesOf('currency')`. A runtime without it
+ * (very old browsers) gets the shape check only.
+ */
+import type { Rule } from '../types.ts';
+export declare function isCurrencyCode(value: unknown): value is string;
+export declare const CampaignCurrencies: Rule;

package/campaign-spec/dist/rules/campaign-currencies.js

@@ -0,0 +1,130 @@
+/**
+ * CampaignCurrencies — checks the campaign's default currency and its list of
+ * selling currencies (#714).
+ *
+ *   1. campaign.currency, when set, is a three-letter upper-case ISO 4217
+ *      code (error). A lower-case or made-up code can make Campaign Cart
+ *      fall back to a cached USD campaign, so the page shows the wrong prices
+ *      and nothing else complains.
+ *   2. campaign.available_currencies, when set, is an array whose every entry
+ *      is such a code (error). A `{ code, label }` object, the Campaigns API's
+ *      shape, is reported with the code it should be written as: Map Builder
+ *      writes code strings, and so should a hand-authored spec.
+ *   3. campaign.currency is one of campaign.available_currencies when that
+ *      list is non-empty (warning). An empty list states nothing and is
+ *      silent, since Map Builder exports [] for a campaign with no list.
+ *
+ * The spec owns `campaign.available_currencies`: every currency the campaign
+ * sells in, the default included. The Campaigns App API's
+ * `additional_currencies` is the same list without the default; it is not a
+ * CampaignSpec field, and this rule does not read it.
+ *
+ * An absent, null or empty currency is silent here: a missing default is a
+ * draft state, not a malformed code.
+ *
+ * The ISO list is `Intl.supportedValuesOf('currency')`. A runtime without it
+ * (very old browsers) gets the shape check only.
+ */
+const CODE_SHAPE = /^[A-Z]{3}$/;
+let isoCodes;
+function knownIsoCodes() {
+    if (isoCodes === undefined) {
+        const supportedValuesOf = Intl.supportedValuesOf;
+        isoCodes = typeof supportedValuesOf === 'function' ? new Set(supportedValuesOf('currency')) : null;
+    }
+    return isoCodes;
+}
+export function isCurrencyCode(value) {
+    if (typeof value !== 'string' || !CODE_SHAPE.test(value))
+        return false;
+    const known = knownIsoCodes();
+    return known === null || known.has(value);
+}
+// The code a malformed value most likely meant: the upper-cased string, or an
+// object's `code`, when that is a valid code. Null when nothing obvious fits.
+function suggestedCode(value) {
+    const raw = typeof value === 'string'
+        ? value
+        : value && typeof value === 'object' && !Array.isArray(value)
+            ? value.code
+            : undefined;
+    if (typeof raw !== 'string')
+        return null;
+    const candidate = raw.trim().toUpperCase();
+    return isCurrencyCode(candidate) ? candidate : null;
+}
+function isAbsent(value) {
+    return value === undefined || value === null || (typeof value === 'string' && value.trim() === '');
+}
+function quoted(value) {
+    return typeof value === 'string' ? `"${value}"` : JSON.stringify(value) ?? String(value);
+}
+function codeMessage(field, value) {
+    const suggestion = suggestedCode(value);
+    const isObject = value !== null && typeof value === 'object';
+    const base = isObject
+        ? `${field} is an object; CampaignSpec lists currencies as three-letter ISO 4217 code strings.`
+        : `${field} ${quoted(value)} is not a three-letter upper-case ISO 4217 currency code.`;
+    return suggestion ? `${base} Write it as "${suggestion}".` : base;
+}
+export const CampaignCurrencies = {
+    id: 'CampaignCurrencies',
+    severity: 'error',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const campaign = spec.campaign;
+        if (!campaign || typeof campaign !== 'object')
+            return violations;
+        const currency = campaign.currency;
+        const currencyValid = !isAbsent(currency) && isCurrencyCode(currency);
+        if (!isAbsent(currency) && !currencyValid) {
+            violations.push({
+                ruleId: 'CampaignCurrencies',
+                severity: 'error',
+                message: codeMessage('campaign.currency', currency),
+                path: '/campaign/currency',
+                data: { check: 'currency_code', received: currency, suggestion: suggestedCode(currency) },
+            });
+        }
+        const available = campaign.available_currencies;
+        if (available === undefined || available === null)
+            return violations;
+        if (!Array.isArray(available)) {
+            violations.push({
+                ruleId: 'CampaignCurrencies',
+                severity: 'error',
+                message: 'campaign.available_currencies must be an array of three-letter ISO 4217 currency codes, the default currency included.',
+                path: '/campaign/available_currencies',
+                data: { check: 'available_currencies_shape', received: available },
+            });
+            return violations;
+        }
+        available.forEach((entry, index) => {
+            if (isCurrencyCode(entry))
+                return;
+            violations.push({
+                ruleId: 'CampaignCurrencies',
+                severity: 'error',
+                message: codeMessage(`campaign.available_currencies[${index}]`, entry),
+                path: `/campaign/available_currencies/${index}`,
+                data: { check: 'available_currency_code', received: entry, suggestion: suggestedCode(entry) },
+            });
+        });
+        // Membership compares what each entry most likely means, so a list entry
+        // already reported as "usd" does not also make "USD" read as missing.
+        if (currencyValid && available.length > 0) {
+            const listed = new Set(available.map((entry) => (isCurrencyCode(entry) ? entry : suggestedCode(entry))));
+            if (!listed.has(currency)) {
+                violations.push({
+                    ruleId: 'CampaignCurrencies',
+                    severity: 'warning',
+                    message: `campaign.currency "${currency}" is not in campaign.available_currencies. List every currency the campaign sells in, the default included, or change the default.`,
+                    path: '/campaign/available_currencies',
+                    data: { check: 'currency_not_available', currency, available },
+                });
+            }
+        }
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/checkout-path-has-packages.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CheckoutPathHasPackages — every path from an entry page to a Checkout passes
+ * at least one page that sells a main-cart package (campaigns-os#711, #206).
+ *
+ * A Checkout the shopper reaches with nothing in the cart cannot take an
+ * order, and until this rule nothing said so before a test order failed. The
+ * selling page may be any page on the path up to and including the Checkout:
+ * a select page's bundle picker, a landing page's package cards, a checkout
+ * step, or the Checkout's own selector. So the rule counts per path, never per
+ * page: a Checkout with no packages of its own passes when every path into it
+ * sells first.
+ *
+ * "Main-cart package" is the ratified #206 contract (checkout-flow.ts
+ * `isMainCartPackage`, docs/template-family-contracts.md "Main-cart entry"):
+ * an entry with neither `is_upsell: true` nor `is_order_bump: true`. Bump rows
+ * alone sell nothing, `default_selected` never changes the role, and entries
+ * on upsell, downsell or thank-you pages never count.
+ *
+ * Paths are walked the way OneCheckoutPerPath walks them: both edges a page
+ * can traverse (routing.ts), starting at the funnel's entry pages
+ * (checkout-flow.ts `entryPages`). No page order or name is consulted. The
+ * search runs, per entry page, over (page, sold yet) states and stops at the
+ * first Checkout, so each empty Checkout is reported once per entry however
+ * many of that entry's paths reach it. A second Checkout on one path is
+ * OneCheckoutPerPath's to report.
+ *
+ * With build_scope.mode === 'partial' the finding is a warning: a partial
+ * build may ship a Checkout that a page outside the build fills.
+ */
+import type { Rule } from '../types.ts';
+export declare const CheckoutPathHasPackages: Rule;