@getvitops/generator 8.0.1 → 8.2.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,365 @@
 # @getvitops/generator
 
+## 8.2.0-alpha.0
+
+### Minor Changes
+
+- 65a13cc: **New: `site.experiments`** — runtime, per-visitor A/B content experiments for a page that
+  must stay at one URL (unlike `site.abTesting`'s existing build-time variant merge, which is
+  for a full design-system/CSS-level test via two manual deploys — `site.experiments` is the
+  opposite granularity: one page, one cookie, content branched in the page itself). Keyed by
+  an open experiment name, so more than one can run at once, each with its own consent
+  category, cookie name/lifetime, split ratio and pair of variant names.
+
+  **New `vitopsAbTesting()` middleware** (`@getvitops/astro/middleware`) — the first Astro
+  middleware this toolchain ships. Wire it into your own `src/middleware.ts`:
+
+  ```ts
+  import { vitopsAbTesting } from '@getvitops/astro/middleware';
+  import config from '../site.json' with { type: 'json' };
+
+  export const onRequest = vitopsAbTesting({
+    experiments: config.site.experiments ?? {},
+  });
+  ```
+
+  It assigns and cookie-pins a visitor to one of an experiment's two variants on first visit,
+  by weighted random (`splitRatio`) — and never touches an already-set cookie, so a recognized
+  query parameter named after the cookie itself (`?_ab_<key>=<variant>`) reliably forces that
+  variant, even overriding an existing assignment. Combined with `splitRatio: 0`, this is a
+  blue/green-style "100% on control, but a shared link reveals the other variant" mode with no
+  special-cased logic.
+
+  A page reads its own experiment's cookie (`Astro.cookies.get(cookieName)?.value`) and
+  renders whichever of its two hand-written blocks matches — there's no config-schema
+  representation of "the variant content," which is what keeps this lightweight regardless of
+  how many experiments are configured.
+
+  **`<Analytics />` gained a reporting hook**: each configured provider's bootstrap now
+  attaches an enabled experiment's assignment to the real pageview via that provider's own
+  mechanism — Plausible via `plausible.init({customProperties})`, Matomo via
+  `setCustomDimension` (needs a new `site.analytics.matomo.abVariantDimensions` entry — the
+  dimension must exist in your Matomo instance first), GA4 via a runtime-merged
+  `gtag('config', …)` call. A no-op when `site.experiments` is unset — zero behavior change
+  for every existing site.
+
+  Also new: `experimentDimensionWarnings(site)` (`@getvitops/generator`) — a build-time warning
+  (not a hard error) when an enabled experiment's site also configures Matomo but has no
+  matching `abVariantDimensions` entry.
+
+  **Not included in this pass, deliberately**: a mechanism for a fully prerendered
+  (`output: 'static'`) page — this needs a genuinely separate Cloudflare Worker Route + two
+  pre-built static variants, real but bounded follow-up work. Everything above applies to an
+  on-demand-rendered page (the current EmDash templates' default), which needs zero new
+  deploy infrastructure.
+
+- 67e2088: **Config validation now rejects unknown keys instead of silently stripping them.** Every
+  object in `ConfigSchema` (the `Config` type — `organization`/`site` and everything nested under
+  them) switched from `z.object` to `z.strictObject`, matching what the published JSON Schema has
+  always asserted (`additionalProperties: false` at ~95 points) but the runtime validator never
+  actually enforced. A typo'd field (`site.ntoifications`, an add-on key on the wrong nesting
+  level, …) now fails `validateConfig()`/`vitops validate` with an `unrecognized_keys` error naming
+  the bad key, instead of validating successfully and doing nothing. `site.icons` stays
+  deliberately loose (`z.looseObject`, unchanged) — its per-set keys are open-ended by design.
+
+  **Breaking for any config carrying a field that isn't in the schema** — this is the point of the
+  change, but if a real config was relying on the old silent-strip behavior (an extra key kept
+  around for another tool to read), move it under a block the schema already permits `z.unknown()`
+  on (`site.cloudflare`, `site.tags`, `site.postTypes`) or open an issue.
+
+  Also:
+  - Added `configVersion` (optional, currently `1`) to `Config` — the document's own SHAPE
+    version, distinct from this package's release version (which is CSS-driven and bumps on every
+    design-system change regardless of `Config`'s shape). `defaultSiteConfig()` stamps it.
+    Exported as `CONFIG_VERSION`.
+  - Re-exported several `Config`-related types/values that were defined but missing from the
+    package root: `SiteReviews`, `SiteReviewLocation`, `SiteSearchConsoleSetup`,
+    `CrmProviderConfig`, `CRM_PROVIDERS`, `BIGIN_DATA_CENTERS`.
+  - Added a `@getvitops/generator/config` subpath export — `ConfigSchema`, `Config`,
+    `validateConfig`, `resolveConfig`, `isConfig`, `resolveInput` and friends, on their own, with no
+    `node:fs`/`node:crypto`/lightningcss in the import graph (verified: `publint` clean, and the
+    built chunk's own imports are `@zod/mini` + `@getvitops/utils`'s Worker-safe `ads`/`tracking`/
+    `color` subpaths only). This is what makes `Config` bundleable in a Cloudflare Worker — the
+    EmDash plugin's own admin route being the motivating case — without pulling in code that only
+    ever runs at build time.
+
+- 0574388: Add `site.crm` — push form submissions into HubSpot, Zoho Bigin, or Jobber.
+
+  Client sites need form submissions to land in the client's CRM. The options available before this
+  — a HubSpot/Bigin/Jobber iframe or JS embed — fail on three counts: the markup can't be
+  white-labelled against this design system, nothing can operate on the submission before it leaves
+  the page, and the submission never touched `createConversionRoute()`, so `_ac` ad-click attribution
+  was lost and no conversion notification was planned.
+
+  This adds one server-side path for all three CRMs, hung off the conversion route that already
+  exists. `createConversionRoute()` gets a new `crm` option (`{ config, credentials, fetch?,
+timeoutMs? }`); credentials arrive as a function of `locals`, exactly like the existing `binding`
+  option, and are never config. A failed CRM write never fails the request and is folded into the
+  notification email's new "Delivery" section, so a broken CRM token is never silent.
+
+  New `@getvitops/utils/crm` subpath: `deliverToCrm()`, `mapSubmission()`, `deriveLastName()` (Bigin
+  requires a last name; this derives one from an explicit field, a full name, or an email address,
+  refusing rather than fabricating one), `submitToHubSpot()`, `submitToBigin()`, `submitToJobber()`.
+  `identifySubmitter()` was promoted out of `notify`'s private name-guessing cascade into
+  `@getvitops/utils/tracking`, since the CRM mapper needed the whole identity (first/last name,
+  email, phone, company), not just a display name.
+
+  Jobber is GraphQL, not REST, and answers `200 OK` for failures — a rejected `clientCreate` returns
+  `userErrors[]`, a malformed request returns top-level `errors[]`. `submitToJobber()` classifies on
+  the response body, not just the status. Its refresh tokens also rotate by default: **Refresh Token
+  Rotation must be turned off** in the app's Developer Center settings, since a Worker reading a
+  static `VITOPS_JOBBER_REFRESH_TOKEN` cannot persist a rotated one — a rotated token is detected at
+  exchange time and reported with the fix, rather than surfacing an hour later as an opaque 401.
+  Attribution and unmapped extra fields render into a best-effort note by default (works on every
+  Jobber plan); a resubmitting visitor creates a second Jobber client unless `crm.jobber.dedupe: true`
+  is set once its lookup query has been verified against a live account (defaults `false` pending
+  that verification — see `jobber.ts`'s docblock).
+
+  New `site.crm` config block (`provider`, `hubspot`/`bigin`/`jobber`, `fieldMap`, `trackingFields`)
+  and two CLI commands: `vitops crm check` (fetches the live HubSpot property list or Bigin field
+  list and reports every mapped name that doesn't exist there — HubSpot rejects an unknown field
+  outright, Bigin silently drops it; Jobber has nothing live to check yet, since its mapped values
+  currently render as note text) and `vitops crm setup` (creates missing HubSpot properties; Bigin
+  and Jobber have no such API, so both always print a manual reminder).
+
+  The generated privacy policy now names HubSpot, Zoho Bigin, or Jobber when `site.crm` configures
+  one. Bigin gets the same cross-border-transfer derivation Matomo Cloud already gets: a
+  `dataCenter: 'ca'` asserts no transfer outside Canada, any other data centre does. Jobber's
+  operator (Octopusapp Inc. d/b/a Jobber) is Canadian, but its own privacy policy names the United
+  States as a processing location too, so the policy always asserts a cross-border transfer for
+  Jobber regardless of config — a Canadian operator is not read as Canadian-only storage.
+
+  Credentials: `VITOPS_HUBSPOT_ACCESS_TOKEN` for HubSpot; `VITOPS_ZOHO_CLIENT_ID` /
+  `VITOPS_ZOHO_CLIENT_SECRET` / `VITOPS_ZOHO_REFRESH_TOKEN` for Bigin; `VITOPS_JOBBER_CLIENT_ID` /
+  `VITOPS_JOBBER_CLIENT_SECRET` / `VITOPS_JOBBER_REFRESH_TOKEN` for Jobber. Never config.
+
+  No consumer-facing change in `@getvitops/astro` beyond the new `crm` route option and a build
+  warning when `site.crm` is configured with no route answering `TRACKING_ENDPOINT` — CSS/Bricks/
+  tailwind outputs are unaffected.
+
+- c3c1bcb: **New: the design-system editor, mounted inside the EmDash admin.** `vitopsEmdash({
+designSystemEditor: { config } })` (`config` is your `site.json`, e.g. `import config from
+'./site.json' with { type: 'json' }`) adds a `/design-system` admin page mounting
+  `<wc-theme-editor>` — the same live token editor `@getvitops/vite`'s dev server has always
+  offered, now usable by the client directly, no dev server required. An edit is visible
+  site-wide immediately (a runtime `:root` override, served via a new plugin API route and
+  `page:fragments`) and — once `site.deployment.repo`/`branch` and a `VITOPS_GITHUB_TOKEN`
+  secret are set (see the scaffold's `SETUP.html`) — auto-commits to your `dev` branch, so it
+  reaches the git-tracked `site.json` through your repo's normal review path rather than
+  becoming a second, unreviewed source of truth. Until that's configured, the live half still
+  works; only the auto-commit half is skipped (and says so in the admin page). The save route
+  runs the exact same accessibility (APCA contrast) gate `generate()` enforces at build time,
+  synchronously, before persisting — nothing non-compliant ever goes live even momentarily.
+
+  Requires `@astrojs/react` + `react` + `react-dom` (already scaffold dependencies, for
+  EmDash's own admin) and `@getvitops/core` (added as a new scaffold dependency this release).
+  Declares two new plugin capabilities when enabled: `network:request` (for the GitHub
+  auto-commit) and `hooks.page-fragments:register` (for the live override) — reviewed once at
+  plugin-install time.
+
+  **Breaking for `@getvitops/emdash`**: `vitopsEmdash()`'s `hooks.page-fragments:register`
+  capability is now also granted whenever `designSystemEditor` is set, independent of the
+  existing `scripts: 'fragments'` option (which governs something unrelated — web-component
+  script delivery). No change if you don't use `designSystemEditor`.
+
+  Also new, supporting the above:
+  - `@getvitops/generator`: `validateColorContract()` and `buildReverseIndex()` (both
+    `/tokens` subpath, Worker-safe) — the monotonicity/contrast gate and the
+    `design-manifest.json` reverse-index, each extracted from `generate()`'s `build()` into
+    standalone, non-throwing functions. `patchToOverrideCss()` turns a design-system patch
+    into the `:root` override `<style>` block. `designSystemPath`/`getAt`/`setAt`/
+    `mergePatch`/`formatConfig` moved from `@getvitops/vite` into `@getvitops/generator/config`
+    (re-exported from `@getvitops/vite` unchanged) — one "patch a config file's design-system
+    subtree" implementation shared by the dev endpoint and the new plugin route. New
+    `site.deployment.repo`/`branch` config fields.
+  - `@getvitops/utils`: new `/git` subpath — `commitFile()`, a Worker-safe (fetch-only)
+    wrapper over GitHub's Contents API.
+  - `@getvitops/core`: `<wc-theme-editor>` gains a `save-endpoint` attribute (default
+    unchanged — `/__vitops/design-system`) so the same element can target the new plugin
+    route instead of the dev-only Vite endpoint.
+
+- 0574388: Add `vitops email setup|check` — connect `site.notifications.email.from` to whether its domain is
+  actually onboarded onto an outbound email provider.
+
+  Before this, nothing checked that. `EMAIL.send()` throws `E_SENDER_NOT_VERIFIED` at runtime with no
+  build or deploy-time warning — the failure mode is silent and production-only.
+
+  `vitops email setup [domain]` onboards a sending domain (currently Cloudflare Email Sending only)
+  and polls DNS until its SPF/DKIM/DMARC records resolve or a timeout is reached; `vitops email
+check` is the non-blocking deploy guard both `@getvitops/create` templates' `deploy`/`deploy:dev`
+  scripts now run first (`--strict` makes it a real gate; opt out per-site with
+  `site.notifications.email.verifySender: false`, or globally with `--skip` /
+  `VITOPS_SKIP_EMAIL_CHECK`).
+
+  Two things worth knowing before running it:
+  - **The onboarded entity is an exact name, and it is usually a subdomain**
+    (`send.yourdomain.com`), never the apex your `from` address names. When the exact domain isn't
+    onboarded but a sibling in the same zone already is, the command reports that as the fix — send
+    from the onboarded subdomain — rather than silently trying to onboard the apex, which rewrites
+    `_dmarc.<domain>` and can tighten DMARC policy on every other mail your domain sends.
+  - Candidates come from `site.notifications.email.from` (or its derived `noreply@<domains
+.canonical>` default) first; a best-effort scan of `--src` only supplements it, and never guesses
+    at a computed `from` value.
+
+  New `@getvitops/utils/email` subpath and `site.notifications.email.verifySender` config field.
+  Needs `CLOUDFLARE_API_TOKEN` with an Email Sending scope in addition to the `Zone:Read` other
+  commands already use.
+
+- dde3df3: **`site.ads.google.conversionLabel` now accepts a per-action map** —
+  `{ call?, email?, form? }` — instead of one bare string shared by every
+  interaction. A bare string still works (back-compat, treated as `call`), but a
+  call and an email click used to report as the **same** Google Ads conversion
+  action, indistinguishable in the account; each action now gets its own
+  `send_to` target.
+
+  **New: `vitopsFormConversion(formEl)`**, exposed as `window.vitopsFormConversion`
+  by `<Tracking />`'s capture script — call it from your own fetch-based form
+  submit handler once the POST to `createConversionRoute()` succeeds, to fire the
+  `form` Google Ads conversion action client-side (mirroring the existing
+  tel:/mailto: click handler, which now fires `call`/`email` instead of sharing
+  one label). Idempotent per form element. There's deliberately no server-side
+  equivalent for a no-JS `<form method="post">` submission — that's a full-page
+  redirect with no script to fire from, and a real server-side Google Ads
+  conversion needs the Ads API's click-conversion upload (developer token + MCC
+  access), tracked separately in the vNext backlog.
+
+  **Fixed: the conversion route's rate limiter no longer trusts the client's
+  raw `event` field.** It used to key on whatever string a client sent
+  (`` `${ip}:${body.event}` ``), so varying that value on every request let a
+  form submission dodge the per-IP rate limit entirely — only `'call'`/`'email'`
+  were ever recognized, and anything else got its own fresh bucket. The key now
+  uses the server's own classification (`call` | `email` | `form`), closing that
+  bypass without changing the existing call-vs-email-don't-compete behavior.
+
+  **New: `site.notifications.actionUrl`** — an optional action-link template
+  added to the conversion-notification email as an "Actions" section.
+  `{clickId}` is replaced with the ad click ID captured on `_ac` (gclid, fbclid,
+  etc.); the section is omitted when the event has no click ID to interpolate,
+  rather than emailing a broken link.
+
+- d9f213b: **New: `site.plan`** — records a commercial plan/add-on entitlement (`{ key, addons? }`),
+  distinct from a section's own `enabled` flag: `enabled` answers "does this site do X at all"
+  (a capability switch); `plan` answers "is this client entitled to turn X on" (a commercial
+  switch one layer above). Absence means unrestricted, matching every other opt-in block in
+  `Config`.
+
+  `PLAN_CAPABILITIES` (new export) is the small, hand-authored table of which add-on gates
+  which `Config` field — today: `ab_testing` gates `site.abTesting.enabled`, any
+  `environments.*.variant`, **and any enabled `site.experiments` entry** (that last one was
+  missed in this feature's first pass and fixed before release — found while planning this
+  toolchain's downstream adoption, not by a consumer hitting it), `server_side_tracking` gates
+  `site.tracking.enabled`. `validateConfig` now rejects a config that turns on a gated feature
+  without listing the owning add-on in `site.plan.addons`, naming the add-on in the error.
+
+  **Breaking**: an existing config using `site.abTesting.enabled`/`environments.*.variant` or
+  `site.tracking.enabled` now needs a matching `site.plan.addons` entry, or `validateConfig`
+  rejects it. Add `site.plan: { key: '<your-plan>', addons: ['ab_testing'] }` (and/or
+  `'server_side_tracking'`) to a config already using either feature.
+
+### Patch Changes
+
+- 0574388: Bump `emdash`/`@emdash-cms/cloudflare` peers to `>=1.0.0 <2` and `vite-plus` to `^1.0.0`, following
+  both projects' GA releases.
+
+  **Breaking for `@getvitops/emdash` consumers on EmDash 0.x**: the peer range no longer admits
+  `emdash@0.31.x`/`@emdash-cms/cloudflare@0.31.x`. Upgrade `emdash` and `@emdash-cms/cloudflare` to
+  `^1.0.1` first — nothing in `@getvitops/emdash`'s own plugin surface (`admin.portableTextBlocks`,
+  the `hooks.page-fragments:register` capability, `definePlugin()`) changed against EmDash 1.0, so no
+  code here needed to change, only the declared range.
+
+  The `emdash` scaffold template (`vp create @getvitops:emdash`) picks up several fixes alongside
+  the version bump:
+  - `tailwindcss`/`@tailwindcss/vite` are now real dependencies — the template selected
+    `css.format: 'tailwind'` without installing either, which threw on build.
+  - `site.json` now sets `site.icons.sprite: true` plus the full `semantic` list the
+    `vitops.actionLink` block's icon picker offers — previously its sprite icons pointed at a file
+    the build never generated.
+  - `astro.config.mjs` sets `migrations: { runtime: 'check', dev: 'auto' }`, and
+    `site-deploy-emdash.yml` runs EmDash 1.0's documented `build → status → apply → deploy → check`
+    migration sequence explicitly, rather than relying solely on first-request auto-migration. This
+    needs a new GitHub Environment variable, `EMDASH_TARGET_FINGERPRINT` (one per environment),
+    which only a human can set — run `emdash migrate --status` against the real deployed database,
+    review the printed identity, then `gh variable set EMDASH_TARGET_FINGERPRINT --env <env> --body
+<value>`. Deploys fail clearly on the migration-apply step until it's set.
+  - `lint.options.typeAware`/`typeCheck` in the template's own `vite.config.ts` are commented out,
+    not deleted: vite-plus 1.0 only honours that option in a project's actual root config, and hard
+    errors on it in a nested one (which this file is, sitting inside the `design-system` monorepo).
+    Uncomment it once scaffolded into its own repo.
+
+  No config schema changes. `@getvitops/generator` also switches from the `zod/mini` subpath import
+  to the standalone `@zod/mini` package (zod 4.5+; same API) and fixes `validateConfig()` silently
+  losing the offending key name on an `unrecognized_keys` error (e.g. a typo'd `site.ads` platform
+  now names the bad key instead of reporting a bare "Invalid input").
+
+  Also fixed: `vp check`'s `tsconfig-error` for `packages/create/templates/emdash/tsconfig.json`
+  (`extends: "astro/tsconfigs/strict"`, unresolvable from inside this monorepo since the template
+  has no `node_modules` of its own — a pre-existing, structural gap, newly surfaced as a hard error
+  by oxlint 1.85's deeper config discovery, and blocking on every commit since this repo's pre-commit
+  hook runs `vp check --fix`). Fixed with a new `scripts/link-template-deps.mjs`, wired as the root
+  `postinstall` script: symlinks `astro`/`emdash`/`@emdash-cms/cloudflare` into the template's own
+  `node_modules/` (resolved fresh from sibling packages that already depend on them for real, not a
+  hardcoded `.pnpm` hash) and writes a minimal `astro:content` ambient shim at `.astro/types.d.ts`
+  (the same path `astro sync` would generate for real). Both are gitignored and only ever exist
+  inside this monorepo's copy of the template — a real scaffold installs its own real copies instead.
+  Considered and rejected first: inlining astro's strict preset (drift risk against astro's own
+  evolving default) and making the template a real pnpm workspace member (would change how its
+  `@getvitops/*: "latest"` deps resolve locally, which `templates.test.ts` exists to protect).
+
+  **Known gap, not fixed here**: `packages/astro/src/components/container.test.ts` (the
+  `AstroContainer`-based render tests) fails to even load under vite-plus 1.0's Vite 8 — direct
+  `.astro` imports in a Vitest file need the Astro Vite plugin registered, which nothing in this
+  repo's test config actually does (Astro's own docs call for `getViteConfig()`, which doesn't
+  compose with vite-plus's own `defineConfig`). A type-level shim
+  (`packages/astro/src/components/astro-modules.d.ts`) fixes `vp check`'s type-aware pass, but the
+  runtime `vp test` failure for this one file is still open.
+
+- 1a3e811: **Fixed: `<Icon />` no longer crashes a Cloudflare Workers SSR page.** It statically imported
+  `loadIconSvg`/`spriteId` from `@getvitops/generator`'s root entry, which also re-exports
+  `generate.ts` — reaching lightningcss, whose native binary Workers cannot `require()`.
+  Rendering `<Icon>` anywhere in an SSR project 500'd every request, regardless of
+  `icons.engine`, since the import itself (not just calling the function) pulled lightningcss
+  into the bundle. Fixed by publishing a new Worker-safe `@getvitops/generator/icons-sprite`
+  subpath (`buildIconSprite`/`loadIconSvg`/`spriteId`, no lightningcss in its import graph) and
+  switching `<Icon />` to import from there.
+- Updated dependencies [0574388]
+- Updated dependencies [c3c1bcb]
+- Updated dependencies [0574388]
+- Updated dependencies [0574388]
+- Updated dependencies [0574388]
+- Updated dependencies [0574388]
+- Updated dependencies [dde3df3]
+  - @getvitops/utils@8.2.0-alpha.0
+
+## 8.1.0
+
+### Minor Changes
+
+- **Added — `vitops init --site` and `vitops setup`, the scripted client-onboarding path.**
+
+  `vitops init --site [--name] [--url]` scaffolds a starter `site.json` (the umbrella `Config`,
+  embedding a starter design system at `designSystem.themes.default`) instead of a bare
+  `design-system.json` — exported as `defaultSiteConfig()` from `@getvitops/generator`, alongside a
+  new `CONFIG_SCHEMA_LOCAL_PATH` and an optional `$schema` field on `ConfigSchema` so a scaffolded
+  config gets editor autocomplete the same way `design-system.json` already does.
+
+  `vitops setup <repo|hosting|domain|search|ads|all>` (new `@getvitops/utils/hosting` subpath: a
+  pure planner + `wrangler`/`gh`-shelling executors, following the same idempotent
+  plan/observe/apply split as `onboarding`/`ads`) automates GitHub repo + branch policy and
+  Cloudflare dev D1/R2 + repo secrets, and plans/checks the workers.dev-vs-custom-domain
+  consistency without ever applying the cutover itself — see AGENTS.md's new "Client onboarding"
+  section for the full design rationale. `search`/`ads` forward to the existing `search setup`/
+  `ads setup` subcommands rather than reimplementing them.
+
+  No consumer-facing change in `@getvitops/vite` or `@getvitops/astro` in this release — bumped
+  only because they are in the `fixed` release group with `generator`/`utils`/`cli`.
+  `@getvitops/core` does have a real fix in this release; see the separate `banner-hidden-fix`
+  changeset.
+
+### Patch Changes
+
+- Updated dependencies
+  - @getvitops/utils@8.1.0
+
 ## 8.0.1
 
 ### Patch Changes
@@ -15,7 +375,6 @@
 
   **Breaking (`css`/`bricks` and `tailwind` formats — `.lightbox-dialog`'s markup
   contract changed):**
-
   - `<Gallery />` now emits ONE `<dialog class="lightbox-dialog">` per gallery,
     wrapping a `<Carousel />`, instead of one dialog per image. A `.gallery__trigger`
     is now a plain `<a href="#slide-id">`, not a `command="show-modal"` button.
@@ -56,7 +415,6 @@
 ### Minor Changes
 
 - Add Google Business Profile reviews: fetch, cache, render.
-
   - **`vitops reviews`** (new CLI command) fetches a client's GBP reviews (legacy v4 API — the only
     one that has them) and writes them to `.vitops/reviews.json`, meant to be committed so a build
     never needs a live Google credential. `--dry` prints the plan; `--check` diffs against the cache
@@ -91,7 +449,6 @@
   `--site` for now.)
 
   **Fixed:**
-
   - `@getvitops/core`'s 12 runtime deps (`lit`, both `@oddbird` polyfills, both
     `@webcomponents` packages, `colorjs.io`, etc.) were listed as `dependencies` despite
     being bundled into `dist/elements.js`/`dist/polyfills.js`/`dist/deferred.js` — a
@@ -1131,20 +1488,28 @@ hidden` would pull it out of the accessible-name computation along with the visu
   {
     "designSystem": {
       "themes": {
-        "default": {/* … */},
+        "default": {
+          /* … */
+        },
       },
     },
     "organization": {
       "name": "Acme",
       "contact": "hq",
       "locations": {
-        "hq": {/* … */},
+        "hq": {
+          /* … */
+        },
       },
     },
     "site": {
       "defaultLocale": "en",
-      "domains": {/* … */},
-      "analytics": {/* … */},
+      "domains": {
+        /* … */
+      },
+      "analytics": {
+        /* … */
+      },
     },
   }
   ```
@@ -1309,7 +1674,7 @@ open-fade-in"` composes slide and fade. Applied at zero specificity with identit
   Also new, and worth wiring at the same time — **`gitLastmod()` for real sitemap dates**:
 
   ```js
-  import vitops, { gitLastmod } from "@getvitops/astro";
+  import vitops, { gitLastmod } from '@getvitops/astro';
   vitops({ sitemap: { serialize: await gitLastmod() } });
   ```
 
@@ -1494,8 +1859,8 @@ open-fade-in"` composes slide and fade. Applied at zero specificity with identit
 
   ```js
   vitops({
-    analytics: { googleAnalytics: "G-XXXXXXXXXX", plausible: "acme.com" },
-    consent: { policyUrl: "/legal/cookies" },
+    analytics: { googleAnalytics: 'G-XXXXXXXXXX', plausible: 'acme.com' },
+    consent: { policyUrl: '/legal/cookies' },
   });
   ```
 
@@ -1635,7 +2000,7 @@ inset(0 100% 0 0)`, and `clip-path` clips **hit-testing** as well as painting
 
   ```js
   // astro.config.mjs
-  getvitops({ css: { input: "company.json", format: "css" } });
+  getvitops({ css: { input: 'company.json', format: 'css' } });
   ```
 
   ```
@@ -1686,11 +2051,11 @@ inset(0 100% 0 0)`, and `clip-path` clips **hit-testing** as well as painting
   getvitops({
     fonts: [
       {
-        name: "League Spartan",
-        provider: "fontsource",
-        cssVariable: "--font-league-spartan",
-        weights: ["100 900"],
-        subsets: ["latin"],
+        name: 'League Spartan',
+        provider: 'fontsource',
+        cssVariable: '--font-league-spartan',
+        weights: ['100 900'],
+        subsets: ['latin'],
         preload: true,
       },
     ],
@@ -2561,7 +2926,7 @@ inset(0 100% 0 0)`, and `clip-path` clips **hit-testing** as well as painting
   ```js
   // astro.config.mjs
   getvitops({
-    css: { input: "design-system.json", format: "css", out: "src/styles" },
+    css: { input: 'design-system.json', format: 'css', out: 'src/styles' },
     editor: true,
   });
   ```

package/assets/css/layout-utilities.css

@@ -270,6 +270,19 @@
   }
 }
 
+/* Opt out of `.rhythm`'s ambient `li + li` sibling margin (layout.css) for a list
+   whose item spacing is already the layout's job — a custom `gap`-based grid or
+   flex wrap the framework has no pattern for. Wins by LAYER (this file is
+   `vitops.utilities`, later than `.rhythm`'s `vitops.components`), the same
+   guarantee `bg-danger-muted` uses to beat `.card` — no specificity trick
+   needed, unlike every pattern-local `:is(ul, ol) > li + li` neutraliser above
+   and in patterns/*.css. The five framework list patterns (gallery, tag-list,
+   cluster, masonry, comment-thread) already do this automatically and don't
+   need this class; reach for it on markup the framework doesn't own. */
+.no-rhythm > li + li {
+  margin-top: 0;
+}
+
 /* ── Flex direction (display + direction; tiered classes set both) ── */
 .flex {
   display: flex;

package/assets/css/layout.css

@@ -133,6 +133,37 @@
 .rhythm > :where(ul, ol) + p {
   margin-top: calc(var(--rhythm-base) * var(--rhythm-list-p));
 }
+/* The only DESCENDANT rule in this block (every other rule above is `>`-scoped to
+   direct children) — it reaches into a list at any depth, including one nested
+   inside a pattern several levels down. That is deliberate: it is the correct
+   default for prose, and prose lists can be arbitrarily nested.
+
+   It is also 0-1-2, not 0-1-0 like the rest of this file's `:where()`-guarded
+   rules — `li + li` sits OUTSIDE the `:where()`, so it carries real weight. A
+   pattern whose item spacing is already its own job (a `gap`-based grid or flex
+   wrap: `.gallery`, `.tag-list`, `.cluster`, `.masonry`, `.comment-thread`,
+   `.subgrid`, `.grid-auto`) neutralises this LOCALLY, in its own partial, with
+   `&:is(ul, ol) > li + li { margin-block-start: 0; }` — `:is(ul, ol)` pushes it
+   to 0-1-3, safely past this rule's 0-1-2 regardless of source order. Consumer
+   markup gets the same escape hatch as a public utility: `.no-rhythm`
+   (layout-utilities.css), which wins by LAYER instead, since it lives in
+   `vitops.utilities`.
+
+   Two alternatives were considered and rejected, worth recording so neither is
+   re-proposed:
+   - Centralising the exclusion HERE, as `:where(ul, ol):not(:where(.gallery,
+     .subgrid, …))`. Rejected: it re-opens exactly the registry the heading rules
+     above were rewritten to delete (see the comment there) — an enumeration that
+     is always one pattern short, unlike a closed set like "what a heading is".
+     It also fails SILENTLY (a missing name renders a stray margin, nothing
+     errors) where the local form fails a build (`bundle-layers.test.ts`'s
+     per-pattern drift guard), and this file's `.rhythm` block is hand-mirrored
+     into a tailwind template literal (`generate.ts`) that has already drifted
+     once — a second selector list to keep in step, not a cleanup.
+   - Zeroing `--rhythm-li-li` locally instead of overriding `margin-top`. It
+     inherits (declared on `:root`), so it would also zero the rhythm of any
+     PROSE list nested inside the opted-out pattern — losing the exact behaviour
+     the descendant combinator above exists to provide. */
 .rhythm :where(ul, ol) > li + li {
   margin-top: calc(var(--rhythm-base) * var(--rhythm-li-li));
 }

package/assets/css/patterns/banner.css

@@ -62,3 +62,10 @@
     flex-shrink: 0;
   }
 }
+
+/* `.banner`'s own `display: flex` and the UA `[hidden] { display: none }` are
+   both 0-1-0 — a tie the author sheet wins on source order, so a hidden
+   banner would render anyway. Name `[hidden]` explicitly so it always wins. */
+.banner[hidden] {
+  display: none;
+}

package/assets/css/patterns/cluster.css

@@ -13,6 +13,25 @@
   gap: var(--cluster-gap, 0.5rem);
 }
 
+/* Markerless — so ADD `role="list"` to the element. Safari + VoiceOver stop
+   announcing a marker-less <ul> as a list, so this reset silently costs the
+   semantics the <ul> was chosen for. Nothing in the framework emits this markup,
+   so only the author can restore it. Conditional so `.cluster` on a `div` is
+   untouched; scoped to `.cluster` alone — the `cluster-*` attribute selectors above
+   are alignment modifiers, not the list itself. */
+.cluster:is(ul, ol) {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* Item spacing is the wrap's job, not the flow's — neutralise `.rhythm`'s
+   `li + li` margin (see layout.css for why this is local rather than
+   centralised). */
+.cluster:is(ul, ol) > li + li {
+  margin-block-start: 0;
+}
+
 .cluster-start-start {
   place-content: start start;
 }

package/assets/css/patterns/comment.css

@@ -85,4 +85,22 @@
   display: flex;
   flex-direction: column;
   gap: 1.5rem;
+
+  /* Markerless — so ADD `role="list"` to the element. Safari + VoiceOver stop
+     announcing a marker-less <ul> as a list, so this reset silently costs the
+     semantics the <ul> was chosen for. Nothing in the framework emits this markup,
+     so only the author can restore it. Conditional so `.comment-thread` on a `div`
+     is untouched. */
+  &:is(ul, ol) {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  /* Item spacing is the flex `gap` above's job, not the flow's — neutralise
+     `.rhythm`'s `li + li` margin (see layout.css for why this is local rather
+     than centralised). */
+  &:is(ul, ol) > li + li {
+    margin-block-start: 0;
+  }
 }

package/assets/css/patterns/gallery.css

@@ -27,6 +27,22 @@ wc-gallery {
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(var(--gallery-thumb-size, 150px), 1fr));
   gap: var(--gallery-gap, 0.5rem);
+
+  /* Gallery.astro emits this as `<ul role="list">`, so the UA's list padding, block
+     margin and markers all apply. The pattern owns no outer spacing — the context it
+     sits in does. Conditional so `.gallery` on a `div` is untouched. */
+  &:is(ul, ol) {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  /* Item spacing is the grid's job, not the flow's — neutralise `.rhythm`'s
+     `li + li` margin (see layout.css for why this is local rather than
+     centralised). */
+  &:is(ul, ol) > li + li {
+    margin-block-start: 0;
+  }
 }
 
 .gallery__item {

package/assets/css/patterns/list.css

@@ -244,6 +244,23 @@
   align-items: center;
   font-size: var(--_fs);
 
+  /* Markerless — so ADD `role="list"` to the element. Safari + VoiceOver stop
+     announcing a marker-less <ul> as a list, so this reset silently costs the
+     semantics the <ul> was chosen for. Nothing in the framework emits this markup,
+     so only the author can restore it. Conditional so `.tag-list` on a `div` is
+     untouched — `--_p` already overrides the UA padding either way. */
+  &:is(ul, ol) {
+    margin: 0;
+    list-style: none;
+  }
+
+  /* Item spacing is the wrap's job, not the flow's — neutralise `.rhythm`'s
+     `li + li` margin (see layout.css for why this is local rather than
+     centralised). */
+  &:is(ul, ol) > li + li {
+    margin-block-start: 0;
+  }
+
   .tag-list__input {
     flex: 1;
     min-inline-size: 6rem;

package/assets/css/patterns/marquee.css

@@ -17,6 +17,12 @@
  * `100% + gap`, because the seam between copies is one more gap that has to be
  * consumed for the loop to be seamless — translate by a bare `-100%` and the
  * items visibly bunch up once per revolution.
+ *
+ * `Marquee.astro` authors THREE `.marquee__content` copies (the slotted one
+ * plus two `aria-hidden`), not two — a very wide track under the 100% floor
+ * needs more than one duplicate to stay covered. `<wc-marquee>` treats the
+ * first as its source and discards the rest, replacing them with however many
+ * its own measurement calls for.
  */
 
 .marquee {