@getvitops/generator 3.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,390 @@
 # @getvitops/generator
 
+## 4.1.0
+
+### Minor Changes
+
+- 2c890c0: Link a site to its ad properties: `site.ads`, `vitops ads`, and `<Ads />`.
+
+  `vitops search` covers the whole Search Console relationship. Nothing covered the equivalent one
+  with ad platforms, and a site's ad accounts had nowhere to live — so a Meta pixel pasted into a
+  template was invisible to the rest of the toolchain. It set `_fbp` on a site whose generated cookie
+  notice never mentioned it, whose consent gate never cleared it on revoke, and — for LinkedIn and
+  Pinterest — whose attribution never captured the click ID at all, so every conversion from those
+  platforms arrived indistinguishable from organic traffic.
+
+  **New `site.ads` block**, keyed by platform (`google`, `meta`, `linkedin`, `reddit`, `tiktok`,
+  `microsoft`, `pinterest`, `snapchat`):
+
+  ```jsonc
+  {
+    "site": {
+      "ads": {
+        "meta": { "pixelId": "123456789", "domainVerification": "abc123" },
+        "google": {
+          "accountId": "123-456-7890",
+          "pixelId": "AW-987654321",
+          "conversionLabel": "xyz",
+        },
+      },
+    },
+  }
+  ```
+
+  **`vitops ads setup`** ensures each platform's domain-verification DNS record. Only four platforms
+  verify a domain at all — Meta, TikTok, Pinterest and Snapchat, by apex DNS TXT — and that record is
+  the one thing created for you (in Cloudflare, via `CLOUDFLARE_API_TOKEN`; created only, never edited
+  or deleted). Google Ads, LinkedIn, Reddit and Microsoft Ads have no domain verification: linking
+  there is the tag and the account id, and the run says so rather than skipping in silence. No
+  platform Marketing API is called — Meta's needs a system-user token and Google's an approved
+  developer token with your own account on the line — so the final "Verify" click is surfaced as a
+  reminder. `--dry` prints the plan, `--check` reports drift and exits non-zero.
+
+  **It asks for what the config is missing.** A verification token does not exist until someone
+  fetches it from the platform UI, so a first run prompts for it, naming the exact UI path, folds the
+  answer into the plan and writes it to your config. The token is not a secret — it is published in
+  DNS, and the platform fetching it back is the ownership proof, exactly like the IndexNow key.
+  Prompting requires a TTY: with `--dry`, `--check`, `--no-prompt`, or in CI, you get a named error
+  instead and the run never hangs. `--no-write` keeps the answer out of the config.
+
+  **`vitops ads tags`** prints each pixel as an inert, consent-gated `<script>` — `type="text/plain"`
+  with the library URL on `data-src`, so an undecided visitor's page issues no third-party request.
+  For Bricks, WordPress, Eleventy: any stack without the Astro integration.
+
+  **`vitops ads lint`** reports the gaps that are invisible at runtime: a click ID the platform stamps
+  that attribution does not capture, a pixel while `site.tracking` is off, a property with no tag id.
+
+  **`<Ads />` in `@getvitops/astro`**, a sibling of `<Analytics />` rather than part of it — ad
+  properties come from the site config, state their own consent category (`marketing` by default,
+  rather than being derived), and switch per environment on their own
+  (`environments.<env>.ads`, defaulting to `analytics`, then true, so a preview deployment can send
+  pageviews without firing conversion pixels). Both components now render through one `<GatedTags />`,
+  so the inert markup has a single implementation.
+
+  **Your cookie notice now discloses every configured pixel** — name, cookies and opt-out — from the
+  same table that writes `data-consent-cookies`, so the notice and the revoke cannot disagree. If you
+  add `site.ads` to a config whose privacy policy or cookie notice you have already published,
+  re-generate and re-read them.
+
+  `li_fat_id` (LinkedIn) and `epik` (Pinterest) join the click-ID capture vocabulary; a site running
+  either platform starts attributing conversions it previously recorded as organic.
+
+- e764090: Separate where a processor stores information from whose law can reach it.
+
+  A processor carried one optional `country`, and the privacy policy flat-deduped it into a single
+  sentence. That conflated two facts a disclosure has to keep apart — **where the data rests** and
+  **which jurisdiction can compel access** — and privacy law turns on the second: the OPC's concern
+  is foreign _access_, not merely foreign storage.
+
+  Ordinary arrangements were inexpressible. Azure is data-resident in Canada and US-controlled;
+  Zoho can serve mail from a Canadian datacentre and telemetry from the US while being headquartered
+  in India; a Microsoft 365 tenant can be Canadian with its identity data in the US. For all of
+  them every available option was wrong: `country: "Canada"` rendered the incoherent _"outside of
+  Canada, including Canada"_, naming the operator's country asserted storage that wasn't happening,
+  and omitting it dropped the processor from the disclosure **silently**.
+
+  **New on a processor:**
+
+  ```jsonc
+  {
+    "name": "Zoho",
+    "purpose": "receiving and storing email sent to us",
+    "storage": [
+      { "country": "Canada", "scope": "mail and productivity data" },
+      { "country": "the United States", "scope": "analytics and telemetry" },
+    ],
+    "operatorCountry": "India",
+  }
+  ```
+
+  - `storage[]` — where information rests, each entry optionally `scope`d to a category. The scope
+    is what makes "Canadian tenant, identity data in the US" sayable.
+  - `operatorCountry` — the jurisdiction that can compel the provider to produce it. Gets its own
+    sentence: _"…established in, or controlled from, jurisdictions outside of Canada, including
+    India. Personal information those providers handle on our behalf may be subject to the laws of
+    those jurisdictions even when it is stored in Canada."_
+  - `country` still works, as shorthand asserting **both** facts — which is what it always
+    asserted, since the sentence it fed claimed storage and legal reach in one breath.
+
+  **Combining `country` with either explicit field is rejected** by `vitops validate`. Whether the
+  shorthand narrows the explicit fact or adds to it are two readings that make contradictory legal
+  claims, so neither is guessed.
+
+  A country in the policy's own jurisdiction is no longer treated as a transfer, which is the
+  `country: "Canada"` fix. Comparison ignores case and a leading "the".
+
+  ### This changes text you have already published
+
+  **Cloudflare, Cloudflare Turnstile, Vercel and Netlify now assert operator jurisdiction and no
+  storage.** They previously claimed `the United States` into a sentence saying "stored or processed
+  in" — a claim about the wrong fact. Cloudflare is anycast: a request from Toronto is answered from
+  a Toronto PoP, and Workers/R2 have residency controls the config cannot see.
+
+  So a site whose only foreign element is its host or Turnstile **stops claiming foreign storage**
+  and instead discloses foreign legal reach. That is a retraction in the direction of accuracy, and
+  it deserves a re-read. **If you pin a US region, say so** — declare a processor with
+  `storage: [{ country: "the United States" }]`. This generalises the rule the provider table
+  already applied to Matomo: "we don't know" is a fact.
+
+  **Everything else renders identically.** Google Analytics, Tag Manager, Clarity, Plausible,
+  Matomo Cloud and any processor you declared with `country` produce the same words as before,
+  because the shorthand expands to both facts and the operator sentence is suppressed when it would
+  only restate a country already disclosed as storage. The one cosmetic change: the closing
+  "subject to access requests…" sentence is now its own paragraph, since it is shared by both
+  clauses.
+
+  **A processor with no location at all is now reported** on stderr by `vitops legal`, naming the
+  document it will be missing from. It cannot appear in a transfer disclosure — there is nothing
+  true to say — but it used to vanish in silence, which is the failure that looks tidy. It is not a
+  validation error: a bare `{ name, purpose }` is still valid.
+
+  New exports from `@getvitops/generator`: `processorsMissingLocation`, `JURISDICTION_COUNTRIES`,
+  and the `ProcessorStorage` type. `PolicyVars` gains `jurisdictionCountry`, `storageCountries`,
+  `scopedStorage` and `operatorCountries`; `countries` is **deprecated but retained**, and still
+  names every country it ever named, so a custom template keeps rendering what it rendered.
+
+### Patch Changes
+
+- Updated dependencies [2c890c0]
+  - @getvitops/utils@4.1.0
+
+## 4.0.0
+
+### Major Changes
+
+- f7bc0a0: Add `vitops search setup` — onboard domains into Google Search Console as domain properties.
+
+  **Breaking:** the `vitops indexing` command has been renamed to **`vitops search notify`**. There is
+  no alias — update any scripts or CI that call `vitops indexing` to `vitops search notify` (same flags,
+  same behaviour).
+
+  **New: `vitops search setup`.** For each domain in a site config's new `site.searchConsole` block
+  (a record keyed by bare hostname), it:
+  - ensures the apex verification TXT record in Cloudflare,
+  - verifies ownership via the Site Verification API (DNS_TXT), retried with exponential backoff while
+    DNS propagates — a still-unverified domain is reported **PENDING**, not failed,
+  - adds the `sc-domain:` property via the Search Console API,
+  - adds any `delegatedOwners` to the verified Site Verification web resource.
+
+  It is idempotent (a re-run of an onboarded domain is a no-op), supports `--check` (report drift, exit
+  non-zero, mutate nothing) and `--dry` (print the plan, change nothing), and `--domain <name>` to
+  scope to one entry. DNS records are only ever created, never edited or deleted.
+
+  Credentials come from the environment, never the config: `CLOUDFLARE_API_TOKEN` (a `Zone:DNS:Edit`
+  token) and a Google **user OAuth refresh token** as `VITOPS_GOOGLE_CLIENT_ID` /
+  `VITOPS_GOOGLE_CLIENT_SECRET` / `VITOPS_GOOGLE_REFRESH_TOKEN` (scoped to `siteverification` +
+  `webmasters`). Granting a Google Group **Full-User** access has no Search Console API and is surfaced
+  as a reminder in the summary rather than automated.
+
+### Minor Changes
+
+- 14813fa: Document which tier provides each pattern — `vitops docs components`.
+
+  The toolkit ships four tiers that compose: CSS framework classes, `<wc-*>` web components, Astro
+  components, Bricks elements. Nothing said so. The class reference listed pattern names, the
+  elements reference listed Bricks controls, and the fact that `tree` is _also_ a web component
+  _and_ an Astro component existed only in the source layout. The cost is silent: you hand-write
+  the markup a component already emits, or you wrap a component that already emits its own tag.
+
+  `TIERS` in `@getvitops/generator` is the new manifest — per pattern, its CSS partial and
+  representative classes, its `wc-*` tag and which bundle that ships in, its Astro component(s),
+  its Bricks element, and one line saying what to actually write. `tierPatterns(tier)` projects one
+  tier. `vitops docs components` renders all four in one document, and the reference sections it
+  feeds render the same data per tier.
+
+  It is **authored rather than derived, and drift-guarded** instead. Naming convention carries most
+  of it and breaks exactly where it matters — `splitter.css` hosts two components, `tag.css` serves
+  three config patterns, `anchor-link.css` provides `.link`, `layout.css` provides `.split` and
+  `.centered` — so a derivation would need an exceptions table longer than the rule, and a rename
+  would silently drop a link. Instead, tests fail the build when a hand-written CSS partial, a
+  `customElements.define`, an exported Astro component or a Bricks element isn't accounted for.
+
+  Four things the manifest records that cannot be inferred, each a real failure mode:
+  - **Whether an Astro component wraps a web component.** `Tree` and `CookieConsent` emit the
+    `<wc-*>` tag with the fallback inside; `Details`, `Drawer`, `Popover`, `NavShell` and `Subgrid`
+    emit tier-1 markup with no web component at all. Reading the first group as the second gives
+    `<wc-tree><Tree /></wc-tree>` — two elements on one tree, which renders and misbehaves.
+  - **Where each element ships.** `elements.js` for the registered set, its own bundle for
+    `<wc-consent>` and `<wc-theme-editor>`, and **no bundle at all** for the four editor-v2 tags —
+    which are registered, importable-looking and inert in a consumer project. The guard checks this
+    against what `js/elements.ts` imports, so it can't claim an element ships when it doesn't.
+  - **Whether a pattern is config-authored.** `patterns.items` patterns get the token cascade,
+    states, role variants and override hooks; a structural partial gets none of them. The docs also
+    now say when a config-authored pattern is **absent from your config**, because naming its
+    classes while your build emits none of them is worse than omitting it.
+  - **The import specifier, verbatim.** These are published as the line to copy, so they are checked
+    against `@getvitops/astro`'s `exports`. That guard immediately caught
+    `@getvitops/astro/components/../CookieConsent.astro` — plausible-looking, right basename, not an
+    importable path (`CookieConsent.astro` ships from the package root).
+
+- c6b99e7: Ad-click attribution and conversion notifications ship as part of the toolchain.
+
+  A visitor arriving on an ad carries a click ID in the URL; `<Tracking />` captures it into a first-party `_ac` cookie, and when that visitor later submits a form or taps a `tel:` link, the conversion handler reads the cookie back and notifies whoever the config says. Previously this was per-site code.
+
+  **Added — `@getvitops/utils/tracking`.** The attribution vocabulary and cookie, as pure functions over a cookie _string_ so the browser capture and the server-side handler share one implementation: `parseTrackingCookie`, `serializeTrackingCookie`, `mergeTracking`, `identifyPlatform`, `getPrimaryClickId`, plus the click-ID/UTM tables. No DOM, no network, no clock — every function that needs "now" takes it as an argument, so it runs unchanged in a Worker.
+
+  **Added — `@getvitops/utils/notify`.** Conversion notifications, split the way `indexing/` is: `plan.ts` decides everything purely (which channels fire, who they reach, and **why anything is skipped**), `render.ts` turns the event into prose, `email.ts` executes and decides nothing. A misconfigured site can therefore be told exactly why no notification will arrive — a silently unsent one is indistinguishable from no conversion.
+
+  The `ConversionEvent` is the abstraction: the event is the _fact_, and how it reads is the channel's business.
+
+  **Added — the `email` channel, via Cloudflare Email Sending.** Uses the current structured binding (`env.EMAIL.send({ to, from, subject, html, text })`), not the legacy `EmailMessage` + hand-built MIME path. The binding is **passed in, never imported**, so `@getvitops/utils` takes no Cloudflare dependency and the sender is testable with a stub. Retries only the transient error codes; a configuration fault like `E_SENDER_NOT_VERIFIED` is surfaced verbatim rather than collapsed into "send failed". With no binding it prints the notification — the dev path.
+
+  Remember to onboard the sending domain (`wrangler email sending enable <domain>`) and add `"send_email": [{ "name": "EMAIL" }]` to `wrangler.jsonc`, or every send fails.
+
+  **Added — `<Tracking />` and `createConversionRoute()`** in `@getvitops/astro` (`@getvitops/astro/Tracking.astro`, `@getvitops/astro/routes`). The route factory handles both the `tel:` beacon and a form POST; validation and business rules stay the consumer's, because every site's form differs. A failed notification never fails the request — the visitor has already submitted, and refusing them because our mail didn't go out turns a lost notification into a lost conversion.
+
+  **Added — `site.tracking` and a widened `site.notifications`.** `notifications.email` now accepts a full channel object as well as a bare address (which still means what it did). `tracking` gains `category`.
+
+  **Fixed — the capture script now asks for consent instead of only reading it.** It previously checked `granted('marketing')` passively, which under the demand-driven banner is a permanent no-op: nothing else on a page demands `marketing`, so the banner never offered it, so it was never granted, so `_ac` was never written — silently, on every site with the gate enabled. It now calls `require()`, which is what raises the banner, and only when the URL actually carried a click ID or UTM. A visitor arriving organically has nothing to attribute and is never asked.
+
+  The integration adds `marketing` to the offered categories when tracking is on, so the banner has a row for the category the script will demand, and warns when tracking is enabled with `consent` off.
+
+  **Fixed — revoking consent now clears `_ac`.** The marker `<Tracking />` emits carries `data-consent-cookies`, which the consent runtime's cleanup reads. There was no cleanup path for this cookie before.
+
+  **Fixed — the cookie notice discloses `_ac`.** It is first-party, so no provider table would ever name it, and a site running attribution alongside a cookieless analytics provider was previously described as setting no cookies at all.
+
+- c6b99e7: Consent is now demand-driven: the banner appears when something actually needs permission, not on every first visit.
+
+  Previously, enabling the gate showed a banner to every new visitor regardless of what the site did — including sites whose only analytics provider was cookieless, where there was nothing to consent to. The build decided whether the machinery shipped and the runtime showed the banner because no cookie existed yet.
+
+  Now those are two separate facts. The build decides what the banner _can_ ask (rows in the markup); the runtime decides what it _does_ ask. A gated tag registers its demand when it reaches its loading strategy, and `<color-scheme-toggle>` registers `preferences` when a visitor picks a scheme. A site that gates nothing never interrupts anyone.
+
+  **Breaking — consent cookie schema (v1 → v2).** Consent is now recorded per category as granted / declined / **not yet asked**. The third state is what lets a later demand ask about a category an earlier prompt didn't cover: accepting an analytics banner no longer silently declines preferences. Every stored v1 choice is invalid and re-prompts once — a v1 cookie asserted a definite answer for categories the visitor was never shown.
+
+  **Breaking — `ConsentApi`.**
+  - `needed()` now means "something demanded a category the visitor hasn't answered", not "no cookie yet". A custom banner calling it will now stay hidden until something asks.
+  - `ConsentState.decided` (a single boolean) is gone. Use `decidedFor(state, category)`, or `undecidedCategories(state)`.
+  - New: `require(category)` registers a demand and reports whether it is granted; `request(category)` resolves once the visitor answers it; `demanded()` lists what has asked so far.
+  - `acceptAll()` / `rejectAll()` still mean every optional category. The banner no longer routes its buttons through them — "Accept" applies to the categories on screen.
+
+  **Breaking — `<color-scheme-toggle>` persistence.** The chosen scheme still applies immediately, but writing it to `localStorage` now waits on the `preferences` category **when the site has a consent gate**. Sites without `consent` enabled are unaffected and keep storing as before. If your site enables consent and offers a theme toggle, make sure `preferences` is among the offered categories (it is by default).
+
+  **Changed — offered categories.** `consent.categories` defaults to `['analytics', 'preferences']` (plus `marketing` when a configured tag needs it) rather than only what analytics detection could see. An unused row is hidden markup, so offering broadly costs nothing and covers `data-consent` markup no build-time scan can find. Pass `categories` explicitly to narrow it.
+
+  **Added — `<Head />` emits a small inline consent stub** when the gate is on. `consent.js` and `elements.js` are both deferred with no ordering between them, so without it a theme toggle could be clicked before the gate existed, read "no gate", and store. The stub answers `false` and queues, and the runtime replays the queue on load.
+
+  **Fixed — the generated cookie notice** now discloses the stored display preference when `preferences` is offered, and no longer promises a banner "shown when you first visit", which is no longer how the banner works.
+
+- 14813fa: Document the consent, conversion-tracking, search and legal subsystems for agents.
+
+  `vitops docs` gains four topics — `consent`, `tracking`, `search`, `legal` — and the docs
+  bundle gains the matching concept docs under `concepts/`. Until now these subsystems were
+  described only by their generated config-schema field descriptions, so an agent working in a
+  consumer project had no account of the rules that make them work, and every one of those rules
+  fails **silently** when broken:
+  - a gated tag given a live `src` instead of `type="text/plain"` fetches the third party anyway,
+    so the gate becomes decorative;
+  - a caller using `granted()` instead of `require()` never raises the banner, so on a site where
+    nothing else demands that category the permission is never offered, never granted, and the
+    write never happens;
+  - an absent `window.vitopsConsent` read as "denied" rather than "this site has no gate";
+  - a consent patch widened to every category records consent nobody gave;
+  - a sitemap with no `<lastmod>` makes edited pages undetectable, so `search notify` looks
+    healthy while never resubmitting anything;
+  - a stale IndexNow key file returns `202` and is then discarded;
+  - Google's Indexing API accepts ordinary URLs, discards them, and violates its own terms.
+
+  The packaged agent skill now covers consent and conversion tracking, and its description names
+  these subsystems so it is actually surfaced when they are the task.
+
+  Also fixed: the icons concept doc still called the Astro integration `getvitops()`, renamed to
+  `vitops()` in 3.0.
+
+- 14813fa: Add `<wc-tree>`, and a schema walker that feeds it.
+
+  `<wc-tree>` is progressive enhancement for the existing `.tree` pattern: given a nested
+  `<details>` disclosure tree it adds a filter, expand-all / collapse-all, and hash deep-linking.
+  It ships in `elements.js`.
+
+  `@getvitops/astro` gains `./components/Tree.astro` and `./components/tree.ts` (its `TreeItem`
+  type) to build that markup from data. As with every wrapper over a web component, `<Tree />`
+  emits the `<wc-tree>` tag itself with the accessible fallback inside — so `<Tree items={…} />`
+  is the whole call, and wrapping it in your own `<wc-tree>` nests two elements on one tree.
+
+  The slotted markup is the whole content and works without it — every node readable, expandable
+  and linkable — so the element only adds what CSS cannot do. Four things worth knowing:
+  - **The toolbar is generated, never authored.** A search field that does nothing is worse than
+    no search field, so the controls exist only once the element upgrades.
+  - **Deep-linking is the non-obvious one.** A node inside a closed `<details>` has no layout box,
+    so the browser's own fragment navigation finds nothing and silently stays at the top of the
+    page. `<wc-tree>` opens the target's ancestors — and the target's own disclosure — then scrolls.
+  - **Filtering matches a node's own label and description, never its subtree's text.** The obvious
+    `textContent` implementation makes every ancestor of a hit match, so the root matches any query
+    and the filter narrows nothing. That decision lives in a pure, tested module (`matchTree`)
+    rather than in the DOM wiring.
+  - **It initialises even when upgraded mid-insertion.** An element connected during an
+    `innerHTML` write — a view-transition swap, a client-side navigation — has no children yet
+    (measured: zero). Setup retries once the insertion completes, because the failure mode was
+    silent: no toolbar, no filter, no deep link, no error.
+
+  `patterns/tree.css` now supports two markup shapes: the item may be the `<details>` (the
+  pattern's original contract) or an `<li class="tree__item">` wrapping one, which is what gives
+  assistive tech list position and depth.
+
+  **`.tree` indent is fixed and now fluid**, which matters for any deep tree. Three separate leaks
+  compounded, each invisible in the CSS and each charging roughly one extra indent per level:
+  - the rule set both `margin-inline-start` and `padding-inline-start` to `--tree-indent`;
+  - `.tree { padding: var(--_p) }` applied to every nested `.tree`, not just the outermost — on all
+    four sides, so it narrowed from the end as well;
+  - `patterns/details.css` gives every non-summary child of a `<details>`
+    `margin-inline: var(--_content-margin)`, and its `details, .details` selector takes `:is()`
+    specificity under CSS nesting (**0-1-1**), so `.tree { margin: 0 }` at 0-1-0 _loses_ to it. A
+    nested tree is exactly such a child.
+
+  Measured in a browser: **41px per level against a 24px design**, so a 9-deep tree spent 382px on
+  indent and left its deepest label 162px wide. Now 24px per level, 198px total, and 653px of label.
+  The nested rule resets both box axes before applying the one indent it owes, and the default is
+  `clamp(0.75rem, 2.5vw, 1.5rem)` — 12px on a phone, 24px on a desktop — because a tree's depth is a
+  property of the data and cannot be known when the pattern is written. `--tree-indent` still
+  overrides it, and the `--lines` elbow derives from the same resolved value so the two cannot
+  disagree.
+
+  **Leaf rows now align with their branch siblings.** A branch spends a toggle column on its chevron
+  before its label; a leaf has none, so every leaf label sat one full column (24px, measured) to the
+  inline-start of its siblings and nothing at a given depth lined up. `.tree` exposes
+  `--_node-indent` (the toggle column) and `--_leaf-indent` (what a row without a toggle owes to
+  reach the same label column); `.tree__content` and `.tree__desc` both read the latter rather than
+  re-deriving the sum.
+
+  `<wc-tree>` also wraps its generated filter in `.input-group`, because `forms.css` styles text
+  controls as `.form-group > input` / `.input-group > input` — a bare `<input>` rendered with the
+  browser's 2px inset border and square corners next to the framework's own rounded controls.
+
+  `schemaTreeNodes(schema, { idPrefix, maxDepth, prune })` is new in `@getvitops/generator`: it walks
+  a JSON Schema — the same walk behind the `authoring.md` / `config.md` references — and returns tree
+  **data**, not markup, so each medium renders it (markdown for agents, an accessible `<details>`
+  tree for a site). Field ids are dotted config paths (`site.analytics.clarityId`), so any field can
+  be linked to directly.
+
+  `prune` exists for a specific hazard. The project config declares `designSystem.themes` as a
+  looser shape than `DesignSystemSchema`, because the full one is applied separately by
+  `resolveTheme` — so its embedded copy is an **approximation**, and measurably missing the
+  descriptions for `colors`, `colors.palette`, `colors.roles` and `colors.utilities`. Anything
+  rendering that copy as the token reference would silently document the colour system less well
+  than the toolchain already does; `prune` lets a caller stop at the wrapper and render `jsonSchema`
+  alongside instead.
+
+  `renderInlineMarkdown()` is exported for schema description text. It **lifts code spans out before
+  applying emphasis**, and that ordering is load-bearing rather than tidy: `colors.utilities`
+  describes its families as `` `bg-*` ``, `` `text-*` ``, `` `border-*` `` — literal asterisk
+  _wildcards_. Run emphasis over the raw string and the `*` closing `bg-*` pairs with the one
+  closing `text-*`, italicising the text between two unrelated utilities and eating both asterisks,
+  leaving prose that names families which don't exist. It also now renders single-asterisk emphasis,
+  which the schema does use (`*presentation*`, `*domain properties*`) and which previously printed
+  the asterisks literally.
+
+  Also fixed: `config.md` claimed "Only the wrapper is listed here" under `designSystem` and then
+  emitted the entire token schema anyway — `themes.<name>` _is_ a design system, so the walk
+  descended into it. It now stops at the wrapper and delegates to `authoring.md` as it always said
+  it did.
+
+### Patch Changes
+
+- Updated dependencies [c6b99e7]
+- Updated dependencies [f7bc0a0]
+- Updated dependencies [ceed51f]
+  - @getvitops/utils@4.0.0
+
 ## 3.0.0
 
 ### Major Changes

package/assets/bricks/elements/color-scheme-toggle.php

@@ -2,7 +2,7 @@
 /**
  * Vitops — Color Scheme Toggle element (Bricks Builder).
  *
- * Renders the <color-scheme-toggle> Lit component (src/web-components/WCColorSchemeToggle.ts):
+ * Renders the <wc-color-scheme-toggle> Lit component (src/web-components/WCColorSchemeToggle.ts):
  * a segmented System / Light / Dark theme toggle, hidden until JS loads. Optionally seed
  * the initial `scheme`.
  *
@@ -21,7 +21,7 @@ class Vitops_Element_Color_Scheme_Toggle extends \Bricks\Element {
 	public $category     = 'vitops';
 	public $name         = 'vitops-color-scheme-toggle';
 	public $icon         = 'ti-shine';
-	public $css_selector = 'color-scheme-toggle';
+	public $css_selector = 'wc-color-scheme-toggle';
 
 	public function get_label() {
 		return esc_html__( 'Color Scheme Toggle', 'bricks' );
@@ -56,6 +56,6 @@ class Vitops_Element_Color_Scheme_Toggle extends \Bricks\Element {
 
 		$attr_str = implode( ' ', $attrs );
 
-		echo "<color-scheme-toggle {$attr_str} {$this->render_attributes( '_root' )}></color-scheme-toggle>";
+		echo "<wc-color-scheme-toggle {$attr_str} {$this->render_attributes( '_root' )}></wc-color-scheme-toggle>";
 	}
 }

package/assets/bricks/elements/multi-field.php

@@ -2,7 +2,7 @@
 /**
  * Vitops — Multi Field element (Bricks Builder).
  *
- * Renders the <wc-multifield> Lit component (src/web-components/WCMultiField.ts): a
+ * Renders the <wc-multi-field> Lit component (src/web-components/WCMultiField.ts): a
  * form-associated repeatable input group (add / remove entries, min / max). Default
  * entries are supplied as slotted <input value="…"> children, which the component reads
  * on connect.
@@ -22,7 +22,7 @@ class Vitops_Element_Multi_Field extends \Bricks\Element {
 	public $category     = 'vitops';
 	public $name         = 'vitops-multi-field';
 	public $icon         = 'ti-list';
-	public $css_selector = 'wc-multifield';
+	public $css_selector = 'wc-multi-field';
 
 	public function get_label() {
 		return esc_html__( 'Multi Field', 'bricks' );
@@ -143,6 +143,6 @@ class Vitops_Element_Multi_Field extends \Bricks\Element {
 			}
 		}
 
-		echo "<wc-multifield {$attr_str} {$this->render_attributes( '_root' )}>{$inputs}</wc-multifield>";
+		echo "<wc-multi-field {$attr_str} {$this->render_attributes( '_root' )}>{$inputs}</wc-multi-field>";
 	}
 }

package/assets/css/patterns/consent.css

@@ -75,15 +75,26 @@
     margin-inline-start: auto;
   }
 
-  /* The per-category checkboxes. Two buttons answer a one-category question, so
-     `<CookieConsent />` only renders these when there is more than one — a banner
-     that demands reading is a banner that gets accepted unread. */
+  /* The per-category checkboxes. A row is hidden unless this showing is about it,
+     so the markup can carry every category the site might ever need while the
+     banner still only asks what was actually demanded. */
   .consent__options {
     flex-basis: 100%;
     display: flex;
     flex-wrap: wrap;
     gap: 1rem;
   }
+
+  /* One category is a yes/no question and the Reject/Accept buttons already ask
+     it — a lone checkbox would be a third control for the same decision, and the
+     Save button a second way to press Accept. `<wc-consent>` sets this class at
+     show time because how many rows are on offer is now a runtime fact. */
+  &.consent--single {
+    .consent__options,
+    [data-consent-save] {
+      display: none;
+    }
+  }
 }
 
 /* Open, in the top layer. */