@getvitops/generator 8.3.0-alpha.4 → 8.3.0-alpha.5

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @getvitops/generator
 
+## 8.3.0-alpha.5
+
+### Minor Changes
+
+- bb61a35: **Call tracking numbers: show an ad visitor a number that attributes the phone call.** Two additive config blocks, no CSS, no breaking change — all formats unaffected.
+
+  - **`site.ads.google.callTracking`** — Google Ads _website call conversions_. `{ label, number, cache? }` makes the consent-gated Google tag fetch a Google forwarding number (Canada supported) and swap it in for visitors who arrived from a Google ad. Google replaces text only, so the capture script also rewrites the matching `tel:` href. Needs `pixelId` and `site.tracking.enabled`; rejected on any other platform (only Google can put a number on the website — Microsoft's exist only inside the ad, in the US/UK/AU).
+  - **`site.tracking.phoneNumbers`** — per-platform numbers for every other platform: the real `number`, `sources` keyed by `site.ads` platform (plus `default-paid`), and an informational `provider`. You provision the numbers with a call-tracking service (Twilio, CallRail, …). The landing URL decides first, then the `_ac` cookie, so a visitor who declines `marketing` sees a tracking number on the landing page only. An organic visitor is never swapped, and the server-rendered HTML always carries the real number.
+  - The `tel:` tap beacon now carries which number was shown (`phoneSource`), and the conversion notification says so.
+  - `vitops ads lint` flags a call-tracking provider that is not in `site.legal.privacyPolicy.processors`, and notes that `callTracking` plus `conversionLabel.call` can count one call twice (make one secondary in Google Ads).
+  - `@getvitops/utils/tracking` exports the pure `selectPhoneNumber()` and helpers; the capture script mirrors it and `tracking.test.ts` pins the two.
+  - `@getvitops/skills` gains a **`vitops-ads`** skill (overview plus a `call-tracking.md` topic). The templates gitignore synced skills by prefix (`vitops-*`, `emdash-*`), so it needs no `.gitignore` line of its own.
+
+  `@getvitops/core`, `@getvitops/vite` and `@getvitops/emdash` — no consumer-facing change in these packages.
+
+- 4d94c8b: **Added: `site.chrome` — a configurable masthead and nav behaviour.** Non-breaking.
+
+  - `site.chrome.masthead` (new `@getvitops/config` schema): `position` (`static|sticky|fixed`), `behavior` (`always|hide-on-scroll`), `surface` (`solid|glass|transparent|transparent-until-scrolled`), `tone` (a `colors.roles` key), `layout` (`full|inset|floating`), `width`, `elevation` (`shadow`, `border`, `onScroll`), `height` and `inset`. `height` and `inset` take fluid lengths (`calc()`, `clamp()`, `min()`, `max()`, with `cqi`/`vw`/… units), checked against a closed grammar because they are written into CSS. `validateConfig` rejects a `tone` or `shadow` the design system does not define (only when the default theme states them directly, not via `extends`).
+  - `site.chrome.nav`: `compact` (`drawer|dropdown`), `drawerSide`, `breakpoint`/`mobileBreakpoint`/`megaBreakpoint`, `depth`, `megaDepth`.
+  - `<Masthead config={site}>` (`@getvitops/astro`, slots `brand`/default/`actions`) and `resolveMasthead()` / `resolveNavOptions()`. A prop overrides one field per layout. The key is `chrome`/`masthead` on purpose: `<header>` is valid in any section and `banner` already means the announcement bar and the landmark role.
+  - `<SiteNav>` gains `compact="dropdown"` (a columnar panel anchored under the toggle), `drawerSide` (previously hardcoded to the end edge in Astro), `megaDepth` and `megaPanel`. `.sitenav--mega` now styles second-level items as column headings and has an optional featured column.
+  - `@getvitops/emdash`: `VitopsMegaPanel` fills that column from the widget area `mega-<item url slug>` (or a `mega-area:<name>` class on the menu item). No area means no column.
+  - `@getvitops/create` (emdash template): the layout renders through `<Masthead>`; `site.json` ships a sticky glass masthead with a shadow once scrolled. The hand-written `.navbar { block-size: 64px }` is gone (use `masthead.height`).
+  - CSS (`patterns/masthead.css`, `patterns/sitenav.css`): **all formats**, including tailwind, where the patterns are inlined into `@layer components`. Hide-on-scroll and the `*-on-scroll` states are `scroll-state()` container queries that only subtract from a settled (solid, elevated, visible) bar, so a browser without them (Firefox today) shows that bar rather than a transparent one. A sticky or fixed masthead sets `--header-offset` / `--top-offset` so anchors land below it.
+  - `@getvitops/generator`: new `TIERS.masthead`; `TIERS.sitenav` documents the new props.
+
+### Patch Changes
+
+- Updated dependencies [785b8b3]
+- Updated dependencies [bb61a35]
+- Updated dependencies [4d94c8b]
+  - @getvitops/config@8.3.0-alpha.5
+  - @getvitops/utils@8.3.0-alpha.5
+
 ## 8.3.0-alpha.4
 
 ### Minor Changes

package/assets/css/index.css

@@ -40,6 +40,7 @@
 /* navbar before sitenav: sitenav's wide state composes it. */
 @import './patterns/navbar.css';
 @import './patterns/sitenav.css';
+@import './patterns/masthead.css';
 /* After sitenav (the nav family stays contiguous) and after drawer.css, whose
    panel surface navshell's desktop block has to undo. */
 @import './patterns/navshell.css';

package/assets/css/patterns/masthead.css

@@ -0,0 +1,201 @@
+/**
+ * Masthead — the site's top bar: brand, navigation, actions. Pure CSS (tier 1); `<Masthead>`
+ * (`@getvitops/astro`) only emits the classes below from `site.chrome.masthead`.
+ *
+ *   <header class="masthead masthead--sticky masthead--glass masthead--shadow-on-scroll">
+ *     <div class="masthead__row navbar centered">brand · nav · actions</div>
+ *   </header>
+ *
+ * Named "masthead", not "header"/"banner": `<header>` is valid in any section, and `.banner` is
+ * the announcement bar. The element is a plain `<header>` with no explicit `role`.
+ *
+ * ── SAFE BASE, SUBTRACTIVE ENHANCEMENTS ──
+ * The un-modified rule is the settled state: visible, solid (or glass), elevated, in flow.
+ * Scroll behaviour is layered on with `scroll-state()` container queries that only ever
+ * SUBTRACT from it — `*-on-scroll` clears the surface/shadow/border while the page is at the
+ * top; `hide-on-scroll` slides the bar away. Where the query is unsupported (Firefox today)
+ * nothing subtracts, so the bar stays visible, solid and elevated: a query can change how the
+ * bar looks, never leave it unreadable or take the nav away. (Writing these the other way
+ * round — base clear, query reveals — leaves an unsupporting browser with a transparent bar
+ * over body text forever.)
+ *
+ * Hooks (all optional custom properties): `--masthead-height`, `--masthead-bg`, `--masthead-fg`,
+ * `--masthead-blur`, `--masthead-glass-opacity`, `--masthead-inset`, `--masthead-shadow`,
+ * `--masthead-border`. `site.chrome.masthead` sets `--masthead-height` and `--masthead-inset`
+ * on `:root` (see `mastheadRootCss()`), so a clamp()/cqi length there reaches `--header-offset`.
+ */
+
+/* Zero-specificity colour defaults, so a `.tone` (or any class) on the element wins. */
+:where(.masthead) {
+  --_masthead-base: var(--tone-bg, var(--color-bg-surface));
+
+  background-color: var(--masthead-bg, var(--_masthead-base));
+  color: var(--masthead-fg, var(--tone-fg, var(--color-text-surface)));
+}
+
+.masthead {
+  --_masthead-h: var(--masthead-height, 4rem);
+  --_masthead-inset: 0px;
+
+  position: relative;
+  z-index: var(--z-tier-sticky);
+  display: block;
+  box-sizing: border-box;
+  transition:
+    translate 0.25s ease,
+    background-color 0.25s ease,
+    box-shadow 0.25s ease,
+    backdrop-filter 0.25s ease;
+}
+
+.masthead__row {
+  display: block;
+}
+
+/* The row's flex child carries the height; `.centered` (when used) is the grid around it. */
+.masthead__row > .navbar {
+  min-block-size: var(--_masthead-h);
+}
+
+/* `width: full` has no track to supply a gutter. */
+.masthead__row:not(.centered) > .navbar {
+  padding-inline: var(--masthead-gutter, 1rem);
+}
+
+/* ── Position ──────────────────────────────────────────────────────────────── */
+.masthead--sticky {
+  position: sticky;
+  inset-block-start: var(--_masthead-inset);
+}
+
+/* Out of flow: overlays the first section. Pair with `--transparent*`. */
+.masthead--fixed {
+  position: fixed;
+  inset-block-start: var(--_masthead-inset);
+  inset-inline: 0;
+}
+
+/* Anchors and `scroll-padding` land below a pinned masthead. Sticky keeps its space in
+   flow, fixed does not, but both cover the top of the viewport. */
+:root:has(.masthead--sticky, .masthead--fixed) {
+  --header-offset: calc(var(--masthead-height, 4rem) + var(--masthead-inset, 0px));
+  --top-offset: var(--header-offset);
+}
+
+/* ── Surface ───────────────────────────────────────────────────────────────── */
+.masthead--glass {
+  background-color: color-mix(
+    in oklch,
+    var(--masthead-bg, var(--_masthead-base)) var(--masthead-glass-opacity, 72%),
+    transparent
+  );
+  backdrop-filter: blur(var(--masthead-blur, 12px));
+  -webkit-backdrop-filter: blur(var(--masthead-blur, 12px));
+}
+
+/* A browser without backdrop-filter would show page content through a tint. Go solid. */
+@supports not (backdrop-filter: blur(1px)) {
+  .masthead--glass {
+    background-color: var(--masthead-bg, var(--_masthead-base));
+  }
+}
+
+.masthead--transparent {
+  background-color: transparent;
+}
+
+/* ── Layout ────────────────────────────────────────────────────────────────── */
+.masthead--inset,
+.masthead--floating {
+  --_masthead-inset: var(--masthead-inset, 0.75rem);
+
+  margin-inline: var(--_masthead-inset);
+  margin-block-start: var(--_masthead-inset);
+}
+
+/* `fixed` has no flow to margin against: pin the box in by its insets instead. */
+.masthead--fixed.masthead--inset,
+.masthead--fixed.masthead--floating {
+  margin: 0;
+  inset-inline: var(--_masthead-inset);
+}
+
+.masthead--inset {
+  border-radius: var(--br-control, 0.375rem);
+}
+
+.masthead--floating {
+  border-radius: var(--br-panel, 1rem);
+  overflow: clip;
+}
+
+/* ── Elevation ─────────────────────────────────────────────────────────────── */
+.masthead--shadow {
+  box-shadow: var(--masthead-shadow, var(--shadow-sm));
+}
+
+.masthead--border {
+  border-block-end: var(
+    --masthead-border,
+    1px solid var(--tone-border, var(--color-border-surface))
+  );
+}
+
+/* A full outline once the masthead is detached from the viewport edge. */
+.masthead--border:is(.masthead--inset, .masthead--floating) {
+  border: var(--masthead-border, 1px solid var(--tone-border, var(--color-border-surface)));
+}
+
+/* ── Scroll behaviour ───────────────────────────────────────────────────────
+   The page is the scroll-state container. Only when a masthead asks for one, so a
+   site that uses none pays nothing. */
+:root:has(
+  .masthead--hide-on-scroll,
+  .masthead--transparent-until-scrolled,
+  .masthead--shadow-on-scroll,
+  .masthead--border-on-scroll
+) {
+  container: masthead-page / scroll-state;
+}
+
+/* At the top of the page, the *-on-scroll modifiers subtract their settled look. `not
+   scroll-state(scrollable: top)` is "nothing above the viewport", i.e. scrollY = 0. */
+@container masthead-page not scroll-state(scrollable: top) {
+  .masthead--transparent-until-scrolled {
+    background-color: transparent;
+    /* A glass bar would otherwise blur the hero behind an otherwise clear bar. */
+    backdrop-filter: none;
+    -webkit-backdrop-filter: none;
+  }
+  .masthead--shadow-on-scroll {
+    box-shadow: none;
+  }
+  .masthead--border-on-scroll {
+    border-color: transparent;
+  }
+}
+
+/* Slide away while the last scroll was downward; back when it reverses. Never while the
+   visitor is inside it: focus, an open popover or an open disclosure keeps it on screen. */
+@container masthead-page scroll-state(scrolled: block-end) {
+  .masthead--hide-on-scroll:not(:focus-within, :has(:popover-open, details[open])) {
+    translate: 0 calc(-100% - var(--_masthead-inset) - 1px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .masthead {
+    transition: none;
+  }
+}
+
+/* Shadows and tints disappear in forced-colors; keep a real edge. */
+@media (forced-colors: active) {
+  .masthead {
+    border-block-end: 1px solid CanvasText;
+  }
+  .masthead--inset,
+  .masthead--floating {
+    border: 1px solid CanvasText;
+  }
+}

package/assets/css/patterns/sitenav.css

@@ -179,6 +179,77 @@
   }
 }
 
+/* ── Compact dropdown — NARROW ONLY ─────────────────────────────────────────
+   `compact: 'dropdown'` swaps the edge drawer for a panel anchored under the toggle,
+   laid out as columns (each top-level item a column, its sub-links beneath). Same
+   markup; `navClass` emits `sitenav--panel-dropdown` INSTEAD of a `drawer-*` class,
+   so nothing here competes with the drawer's equal-specificity edge rules. Scoped to
+   the narrow state for the reason the whole file is (see "TWO BRANCHES"). */
+.sitenav--panel-dropdown {
+  anchor-scope: --sitenav-toggle;
+}
+.sitenav--panel-dropdown > .sitenav__toggle {
+  anchor-name: --sitenav-toggle;
+}
+
+@container style(--_sitenav-wide: 0) {
+  .sitenav--panel-dropdown .sitenav__panel {
+    position-anchor: --sitenav-toggle;
+    position-area: block-end span-inline-start;
+    inset: auto;
+    margin: var(--sitenav-dropdown-gap, 0.5rem) 0;
+    inline-size: min(calc(100dvw - 1.5rem), var(--sitenav-dropdown-size, 36rem));
+    max-block-size: calc(100dvh - 6rem);
+    padding: 1.25rem;
+    border: var(--b-panel);
+    border-radius: var(--br-panel);
+    box-shadow: var(--ds-panel);
+    translate: 0 -0.5rem;
+  }
+  .sitenav--panel-dropdown .sitenav__panel:popover-open {
+    translate: 0 0;
+  }
+  @starting-style {
+    .sitenav--panel-dropdown .sitenav__panel:popover-open {
+      opacity: 0;
+      translate: 0 -0.5rem;
+    }
+  }
+  /* The dropdown is anchored, not modal: no close button, no dimmed page. */
+  .sitenav--panel-dropdown .sitenav__close {
+    display: none;
+  }
+  .sitenav--panel-dropdown .sitenav__panel {
+    padding-block-start: 1.25rem;
+  }
+  .sitenav--panel-dropdown .sitenav__panel::backdrop {
+    background: transparent;
+  }
+  .sitenav--panel-dropdown .sitenav__panel:popover-open::backdrop {
+    background: transparent;
+  }
+  .sitenav--panel-dropdown .sitenav__list {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));
+    gap: 1rem 1.5rem;
+    align-items: start;
+  }
+  /* Columns, not accordions: every sub-list is open, so the caret has nothing to do. */
+  .sitenav--panel-dropdown .sitenav__item--branch {
+    display: block;
+  }
+  .sitenav--panel-dropdown .sitenav__item--branch > .sitenav__submenu {
+    overflow: visible;
+    padding-inline-start: 0;
+  }
+  .sitenav--panel-dropdown .sitenav__disclosure {
+    display: none;
+  }
+  .sitenav--panel-dropdown .sitenav__list > .sitenav__item--branch > .sitenav__link {
+    font-weight: 600;
+  }
+}
+
 /* ── Lists + links ─────────────────────────────────────────────────────────── */
 .sitenav__list,
 .sitenav__submenu {
@@ -534,6 +605,38 @@
   .sitenav--mega .sitenav__submenu .sitenav__disclosure {
     display: none;
   }
+  /* Second level reads as a column heading; its description (`titleAttr`) stays. */
+  .sitenav--mega
+    .sitenav__list
+    > .sitenav__item--branch
+    > .sitenav__submenu
+    > .sitenav__item--branch
+    > .sitenav__link {
+    font-weight: 600;
+    padding-inline: 0;
+  }
+  .sitenav--mega .sitenav__submenu .sitenav__item--branch > .sitenav__submenu {
+    padding-inline: 0;
+  }
+  /* Optional featured column (EmDash widget area via `megaPanel`). */
+  .sitenav--mega .sitenav__mega-extra {
+    flex: 1 1 14rem;
+    margin-inline-start: auto;
+    max-inline-size: 22rem;
+    padding-inline-start: 1.5rem;
+    border-inline-start: 1px solid var(--color-border-surface, currentColor);
+  }
+  .sitenav--mega .sitenav__mega-extra:empty {
+    display: none;
+  }
+}
+
+/* Extra column is a wide-mega feature: in a drawer (a mega menu that is the only tier) it
+   would be an unlabelled block between accordions. Empty (no widget area) shows nothing. */
+@container style(--_sitenav-wide: 0) {
+  .sitenav__mega-extra {
+    display: none;
+  }
 }
 
 /* ── In-page menu (`vitops_nav` block) ─────────────────────────────────────────

package/config.schema.json

@@ -2338,6 +2338,160 @@
           },
           "additionalProperties": false
         },
+        "chrome": {
+          "description": "Page furniture: the masthead (top bar — position, hide-on-scroll, glass/transparent surface, inset/floating layout, shadow/border) and how its navigation behaves at each width (compact drawer or dropdown, mega tier). Read by `<Masthead />` and `<SiteNav />` via `resolveMasthead()` / `resolveNavOptions()`; a prop overrides a field per layout.",
+          "type": "object",
+          "properties": {
+            "masthead": {
+              "description": "The top bar: position, scroll behaviour, surface, layout, elevation.",
+              "type": "object",
+              "properties": {
+                "position": {
+                  "description": "`static` scrolls away; `sticky` stays in flow and pins to the top; `fixed` is out of flow and overlays the first section (for a transparent masthead over a hero). Default `static`.",
+                  "type": "string",
+                  "enum": [
+                    "static",
+                    "sticky",
+                    "fixed"
+                  ]
+                },
+                "behavior": {
+                  "description": "`hide-on-scroll` slides the masthead away while scrolling down and back on scrolling up. Ignored when `position` is `static`. It never hides while a menu inside it is open or has focus. Uses `scroll-state()`; in a browser without it (Firefox today) the masthead just stays visible. Default `always`.",
+                  "type": "string",
+                  "enum": [
+                    "always",
+                    "hide-on-scroll"
+                  ]
+                },
+                "surface": {
+                  "description": "`solid`, `glass` (blurred + tinted via `--surface-glass`), `transparent`, or `transparent-until-scrolled` (clear while the page is at the top, solid once it scrolls; a browser without `scroll-state()` shows it solid throughout). Default `solid`.",
+                  "type": "string",
+                  "enum": [
+                    "solid",
+                    "glass",
+                    "transparent",
+                    "transparent-until-scrolled"
+                  ]
+                },
+                "tone": {
+                  "description": "A `colors.roles` key, optionally `<role>:solid`, applied as the masthead `.tone` so text contrast stays the generator's guarantee.",
+                  "type": "string"
+                },
+                "layout": {
+                  "description": "`full` is flush to the viewport edges; `inset` leaves a gap to them; `floating` is inset with a panel radius. Default `full`.",
+                  "type": "string",
+                  "enum": [
+                    "full",
+                    "inset",
+                    "floating"
+                  ]
+                },
+                "width": {
+                  "description": "`content` keeps the masthead row on the page's `.centered` track; `full` lets it span the masthead. Default `content`.",
+                  "type": "string",
+                  "enum": [
+                    "full",
+                    "content"
+                  ]
+                },
+                "elevation": {
+                  "description": "Shadow and border.",
+                  "type": "object",
+                  "properties": {
+                    "shadow": {
+                      "description": "A `designSystem.shadows` key (e.g. `sm`). Omit for no shadow.",
+                      "type": "string"
+                    },
+                    "border": {
+                      "description": "A bottom border (a full outline when `layout` is not `full`).",
+                      "type": "boolean"
+                    },
+                    "onScroll": {
+                      "description": "Apply the shadow/border only once the page has scrolled, so the masthead sits flush with the page at the top. Uses `scroll-state()` container queries; in a browser without them (Firefox today) the elevation is simply always on.",
+                      "type": "boolean"
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                "height": {
+                  "description": "CSS length for the masthead row (default `4rem`). `calc()`, `clamp()`, `min()` and `max()` are accepted, so it can be fluid: `clamp(3.5rem, 8cqi, 4.5rem)`. `cqi` resolves against the nearest size container (`body`, the same one the nav breakpoints use), `vw` against the viewport. Becomes `--masthead-height` and, when the masthead is sticky or fixed, `--header-offset` so in-page anchors land below it.",
+                  "type": "string"
+                },
+                "inset": {
+                  "description": "Gap between a `layout: inset` or `floating` masthead and the viewport edge (default `0.75rem`). Same length grammar as `height`, e.g. `clamp(0.5rem, 2cqi, 1.5rem)`. Ignored when `layout` is `full`. Becomes `--masthead-inset` and is counted in `--header-offset`.",
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            "nav": {
+              "description": "How the masthead navigation behaves at each width.",
+              "type": "object",
+              "properties": {
+                "breakpoint": {
+                  "description": "Container width where the default `primary` menu promotes from the compact control to a navbar. Default `md`.",
+                  "type": "string",
+                  "enum": [
+                    "sm",
+                    "md",
+                    "lg",
+                    "xl"
+                  ]
+                },
+                "mobileBreakpoint": {
+                  "description": "Where a `primary-mobile` menu hands over to `primary`. Default = `breakpoint`.",
+                  "type": "string",
+                  "enum": [
+                    "sm",
+                    "md",
+                    "lg",
+                    "xl"
+                  ]
+                },
+                "megaBreakpoint": {
+                  "description": "Where a `primary-mega` menu takes over. Default `xl`.",
+                  "type": "string",
+                  "enum": [
+                    "sm",
+                    "md",
+                    "lg",
+                    "xl"
+                  ]
+                },
+                "depth": {
+                  "description": "Levels in the default nav (1–3). Default 3.",
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 3
+                },
+                "megaDepth": {
+                  "description": "Levels in the mega panel (1–3). Default 3.",
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 3
+                },
+                "compact": {
+                  "description": "What the toggle opens below its breakpoint: an edge `drawer`, or a columnar `dropdown` panel anchored under the toggle. Default `drawer`.",
+                  "type": "string",
+                  "enum": [
+                    "drawer",
+                    "dropdown"
+                  ]
+                },
+                "drawerSide": {
+                  "description": "Edge the drawer slides from when `compact` is `drawer`. Default `end`.",
+                  "type": "string",
+                  "enum": [
+                    "start",
+                    "end"
+                  ]
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
         "seo": {
           "description": "SEO defaults: site name, title/description defaults, robots policy, verification tokens, Open Graph + Twitter cards, and post-deploy indexing notification. Read by `<Seo />`, `vitops robots` and `vitops search notify`.",
           "type": "object",
@@ -2714,6 +2868,46 @@
               "items": {
                 "type": "string"
               }
+            },
+            "phoneNumbers": {
+              "description": "Show a visitor from an ad the tracking number for that platform instead of the real one. Swapped in by the capture script from the landing URL (immediately) or the `_ac` cookie (later pages, once `marketing` is granted); the matching `tel:` links are rewritten too. An organic visitor is never swapped. Needs `enabled: true`.",
+              "type": "object",
+              "properties": {
+                "number": {
+                  "type": "string",
+                  "description": "The real phone number exactly as the site displays it. Server-rendered HTML always carries this one, so crawlers, structured data and visitors without JavaScript see it."
+                },
+                "sources": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string",
+                    "enum": [
+                      "google",
+                      "meta",
+                      "linkedin",
+                      "reddit",
+                      "tiktok",
+                      "microsoft",
+                      "pinterest",
+                      "snapchat",
+                      "default-paid"
+                    ]
+                  },
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Tracking numbers keyed by ad platform (the `site.ads` provider names), each provisioned with a call-tracking provider and forwarding to `number`. `default-paid` is the fallback for a paid visit from a platform with no number of its own. Google needs no entry when `site.ads.google.callTracking` is set — Google supplies its own."
+                },
+                "provider": {
+                  "description": "The call-tracking provider (e.g. `twilio`, `callrail`). Informational, but it records callers’ numbers, so it must be named in the privacy policy — declare it in `site.legal.privacyPolicy.processors` unless it is a known one.",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "number",
+                "sources"
+              ],
+              "additionalProperties": false
             }
           },
           "additionalProperties": false
@@ -2746,7 +2940,7 @@
                 "type": "string"
               },
               "conversionLabel": {
-                "description": "Google Ads only: the conversion action label(s) paired with the `AW-…` conversion ID — either one bare label (back-compat, treated as the `call` action) or a map of action → label, so a call, an email click and a form submission each fire their own Google Ads conversion action instead of all three reporting as the same one.",
+                "description": "Google Ads only: the conversion action label(s) paired with the `AW-…` conversion ID — the category (Phone call lead, Contact, …) is a property of the action in Google Ads, not of the tag call, so a wrong category can't be fixed from code; either one bare label (back-compat, treated as the `call` action) or a map of action → label, so a call, an email click and a form submission each fire their own Google Ads conversion action instead of all three reporting as the same one.",
                 "anyOf": [
                   {
                     "type": "string"
@@ -2755,15 +2949,15 @@
                     "type": "object",
                     "properties": {
                       "call": {
-                        "description": "Fired on a tel: link click.",
+                        "description": "Fired on a tel: link click. Create the action in Google Ads with category \"Phone call lead\".",
                         "type": "string"
                       },
                       "email": {
-                        "description": "Fired on a mailto: link click.",
+                        "description": "Fired on a mailto: link click. Create the action in Google Ads with category \"Contact\".",
                         "type": "string"
                       },
                       "form": {
-                        "description": "Fired client-side by `vitopsFormConversion()` — the consumer's own submit handler calls it once a form POST succeeds.",
+                        "description": "Fired client-side by `vitopsFormConversion()` — the consumer's own submit handler calls it once a form POST succeeds. Create the action in Google Ads with category \"Submit lead form\". Don't fire it from a success-page query parameter: that replays on refresh and the honeypot returns the same success page.",
                         "type": "string"
                       }
                     },
@@ -2797,6 +2991,29 @@
                   }
                 ]
               },
+              "callTracking": {
+                "description": "Google Ads only: **website call conversions**. The Google tag fetches a Google forwarding number for visitors who arrived from a Google ad and swaps it in for `number`, so a phone call (not just a `tel:` tap) is attributed to the click. Google decides who sees it; this toolchain also rewrites the matching `tel:` links, which Google does not. Counts the same call as `conversionLabel.call` if both are primary — make one secondary in Google Ads. Any other platform has no equivalent: see `site.tracking.phoneNumbers`.",
+                "type": "object",
+                "properties": {
+                  "label": {
+                    "type": "string",
+                    "description": "The conversion action label of a **separate** Google Ads action of type \"Calls from a phone number on your website\" (not the `conversionLabel.call` action, which counts `tel:` taps). Paired with `pixelId` as `AW-…/<label>`."
+                  },
+                  "number": {
+                    "type": "string",
+                    "description": "The phone number exactly as the site displays it, e.g. `613-555-0100`. Google swaps its forwarding number in only where the page text matches these digits, so a differently formatted number on the page is silently never replaced."
+                  },
+                  "cache": {
+                    "description": "Set false to stop Google caching the fetched forwarding number in a cookie (`phone_conversion_options.cache`). Default true, so the number follows the visitor across pages.",
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "label",
+                  "number"
+                ],
+                "additionalProperties": false
+              },
               "reporting": {
                 "description": "Google Ads only: `\"client\"` (default) fires the conversion via `gtag.js` in the browser at click/submit time; `\"server\"` uploads it via the Ads API from the conversion endpoint instead (see `conversionActionId`). An action with no matching `conversionActionId` keeps firing client-side regardless of this setting, so setting it before `conversionActionId` is filled in never silently drops a conversion.",
                 "type": "string",