@getvitops/generator 2.1.0 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,416 @@
 # @getvitops/generator
 
+## 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
+
+- 6e68ace: **Breaking:** the site config is now a three-section `Config` — `designSystem`,
+  `organization`, `site`.
+
+  The flat `SiteConfig` held the company (`organization`, `contact`, `locations`) and the
+  deployment (`analytics`, `environments`, `seo`, `legal`) as peers, so no single noun
+  described it, and a second site sharing the same company had no way to say so. The three
+  sections split those apart: several sites can now carry one `organization` and differ only
+  in `site`.
+
+  **Migrating.** `designSystem` stays at the root, and the fields already under
+  `organization` stay where they are. Everything else moves into one of two sections:
+  - → `site`: `defaultLocale`, `locales`, `domains`, `dns`, `cloudflare`, `environments`,
+    `abTesting`, `fonts`, `tags`, `postTypes`, `galleries`, `testimonials`, `templates`,
+    `navigation`, `seo`, `analytics`, `notifications`, `tracking`, `security`, `legal`,
+    `icons`, `favicon`, `deployment`
+  - → `organization`: `contact`, `primaryLocation`, `locations`, `services`, `links`
+
+  You do not have to work this out from the list: `vitops validate` detects a pre-3.0 flat
+  config and prints every move by name, rather than reporting a dozen unknown keys.
+
+  ```jsonc
+  {
+    "designSystem": {
+      "themes": {
+        "default": {
+          /* … */
+        },
+      },
+    },
+    "organization": {
+      "name": "Acme",
+      "contact": "hq",
+      "locations": {
+        "hq": {
+          /* … */
+        },
+      },
+    },
+    "site": {
+      "defaultLocale": "en",
+      "domains": {
+        /* … */
+      },
+      "analytics": {
+        /* … */
+      },
+    },
+  }
+  ```
+
+  **Renamed exports** (`@getvitops/generator`): `SiteConfigSchema` → `ConfigSchema`,
+  `SiteConfig` → `Config`, `validateSite` → `validateConfig`, `resolveSiteConfig` →
+  `resolveConfig`, `isSiteConfig` → `isConfig`, `siteJsonSchema` → `configJsonSchema`,
+  `SITE_SCHEMA_URL` → `CONFIG_SCHEMA_URL`, `SiteValidationResult` →
+  `ConfigValidationResult`. `ResolvedInput.site` is now `ResolvedInput.config`. New:
+  `OrganizationConfig` and `SiteSection` for the two sections.
+
+  **Renamed schema file:** `@getvitops/generator/site.schema.json` →
+  `@getvitops/generator/config.schema.json`. Update the `$schema` key in your config.
+
+  Option names are unchanged — `vitops({ site: { input } })`, the Vite plugin's `site`,
+  and `generate({ site })` still point at the config file.
+
+  **The Astro integration is now `vitops()`, not `getvitops()`.** It is a default export,
+  so the name is yours and nothing breaks on upgrade, but every example now reads
+  `import vitops from '@getvitops/astro'` — matching the Vite plugin, which has always been
+  `vitops`. The `@getvitops/*` package scope and the internal `virtual:getvitops/*` module
+  ids are unchanged; neither is an import name.
+
+  **Added:** a generated config authoring reference — `vitops docs config`, `docs/config.md`
+  in the OKF bundle, and _Config reference_ on the docs site. It is walked from the published
+  JSON Schema by the same helper that renders the `design-system.json` reference, so it
+  cannot describe a field validation does not accept.
+
+- b115993: Nav shells, a top-layer animation driver, and a pile of fixes to things that never worked
+
+  ### Breaking
+  - **Two custom elements renamed.** `<copy-button>` → `<wc-copy>`, `<multi-field>` →
+    `<wc-multifield>`. Update your markup. The Bricks element keys
+    (`vitops-copy-button`, `vitops-multi-field`) are **unchanged**, so elements already
+    placed on a Bricks page keep working; so are the `--multi-field-*` custom properties
+    and the `multi-field-*` events.
+  - **`<details>` now animates open and closed** where `prefers-reduced-motion` allows.
+    It was previously instant by deliberate choice — the transition used to deadlock the
+    disclosure shut. Re-verified on Chrome 149 with a real click; both `block-size` and
+    `content-visibility` must stay in the transition list, and dropping the latter
+    reproduces the deadlock.
+  - **Drawers and dialogs now animate on close.** Both drove their entry with
+    `animation:` on `[open]`, which by construction plays once — so the close was
+    instant. They now use the top-layer driver and animate both ways.
+  - **`.rhythm` gives every non-heading block heading-spacing before a heading.** The
+    pairs used to enumerate `p` (later `p, pre, blockquote, table, dl, ul, ol`), so a
+    heading after anything else got paragraph spacing. They are now defined by what a
+    heading _is_ — `h1`–`h6` plus the `font-display` / `font-title` / `font-heading` type
+    roles — and inverted to `:not(<heading>) + <heading>`. Expect slightly more space
+    above headings that follow a code block, table, figure-like `<div>` or component.
+  - **`popover.css` no longer pins `[popover]:popover-open { opacity: 1 }`.** It never
+    animated anything on its own, but it outranked `.transition` and made every
+    top-layer fade impossible. Removing it is what lets the driver work.
+  - **`nav.css`'s `.drawer-menu` timing** now follows `--animation-duration` /
+    `--custom-ease-out` instead of hand-set 0.4s / 0.7s.
+
+  ### Fixed
+  - **`.sitenav--bp-sm` dropdowns could never open.** Its desktop block had drifted onto
+    an older markup shape, selecting `.sitenav__disclosure > .sitenav__submenu` where the
+    submenu is the disclosure's _sibling_. The four "intentionally parallel" breakpoint
+    blocks are now one shared block behind a style query — `md`/`lg`/`xl` were
+    byte-identical and only `sm` had rotted, which is exactly the drift the arrangement
+    invited. 583 → 361 lines.
+  - **Hover dropdowns rendered off-screen.** A closed popover is not in the top layer but
+    keeps the UA's `position: fixed`, and `.dropdown--show-on-hover` reset only `inset` —
+    so the panel faithfully faded in ~3300px from its trigger. Now anchored to it, and it
+    follows on scroll. Affects `.split-link--show-on-hover` too.
+  - **Horizontal overflow on narrow screens.** `.centered > *` floors at
+    `min-inline-size: 0`; `body` gets `overflow-wrap: break-word`; `patterns/code.css`
+    gains the `pre` rules it never had (`max-inline-size: 100%`, `overflow-x: auto`) and
+    gives inline `<code>` `overflow-wrap: anywhere`. Note a scroll container does _not_
+    zero its min-content contribution in Chrome, which is what made a single `<pre>` hold
+    a 390px viewport open at 797px.
+  - **`.split-<a>-<b>` now publishes `--_flex-direction: row`.** Only `.flex-*` did, so
+    `class="split flex-col md-split-1-2"` left the variable reading `column` at every
+    width and a nested `.grouped` collapsed its borders on the wrong axis.
+  - **`.toc-layout` uses `minmax(0, 1fr)`** instead of a bare `1fr`, whose automatic
+    minimum is min-content.
+
+  ### Added
+  - **`patterns/navshell.css` + `<NavShell>` / `<NavShellToggle>`** — a navigation aside
+    beside content at width, collapsing to a toggle and drawer below it. **It nests**: a
+    site nav wrapping an on-this-page nav, each promoting at its own breakpoint, via a
+    style query on an inherited flag rather than four copied blocks. Its content column
+    is a container, so an inner shell measures the space it actually has. The toggle can
+    live outside the shell (a site header) with `toggle="external"`.
+  - **`patterns/navbar.css`** — `.navbar` extracted from `nav.css`, where it was only
+    half of that file's drawer⇄navbar pair, plus `--start` / `--center` / `--end`,
+    `__spacer` and `--sticky` (old `.navbar-sticky` aliased).
+  - **A top-layer animation driver.** `animation.css` gained the fourth driver alongside
+    `animate-view` / `animate-scroll` / `animate-trigger` / `transition`, and every effect
+    gained an `open-<fx>` state variant. Overlays now state _where they start_
+    (`--translate-x-from`) instead of owning a keyframe: `class="drawer drawer--right
+open-fade-in"` composes slide and fade. Applied at zero specificity with identity
+    defaults, so a popover that sets no effect vars is unchanged.
+  - **One scrim.** `--scrim` / `--scrim-filter` tokens and `.no-scrim` in `popover.css`,
+    replacing 18 `::backdrop` blocks across seven partials. `.drawer--modeless` is aliased.
+  - **`<wc-marquee>`** — clones the content enough times to cover the track, so every gap
+    matches including the seam. The CSS-only `.marquee` is unchanged and still works
+    without it; the element only makes the spacing right. `--marquee-gap` added.
+  - **`--width-nav`** joins `--width-measure` / `-breakout` / `-spotlight` as the nav
+    column width.
+  - **`.skip-link`** in `patterns/anchor-link.css`, using a clip rather than the
+    `-100vw` idiom (which overflows in RTL and ignores the scrollbar gutter).
+  - **`.table-wrapper`** documented as the scroll wrapper for wide tables.
+
+  ### Notes
+  - `patterns/nav.css` is marked legacy. Its header promised a Lit nav component that was
+    never written and is not planned — the house pattern is native. Use `navbar`,
+    `sitenav` or `navshell`; removal is a later change.
+  - `scroll-target.css`'s `.is-current` no longer claims to be a JS scroll-spy fallback.
+    There is no such code; `:target-current` is the only working highlight, which today
+    means Chrome.
+  - `elements.js` gains one element (`wc-marquee`), so the shared bundle is slightly
+    larger for every consumer.
+  - A registered custom property's `initial-value` must be computationally independent —
+    `16rem` is not, so `@property` silently drops the whole rule. `navshell` uses an
+    inline fallback instead.
+
+### Patch Changes
+
+- Updated dependencies [6e68ace]
+  - @getvitops/utils@3.0.0
+
 ## 2.1.0
 
 ### Minor 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/copy-button.php

@@ -2,7 +2,7 @@
 /**
  * Vitops — Copy Button element (Bricks Builder).
  *
- * Renders the <copy-button> Lit component (src/web-components/WCCopy.ts): a
+ * Renders the <wc-copy> Lit component (src/web-components/WCCopy.ts): a
  * copy-to-clipboard button, hidden until connected (Clipboard API gate). The `value`
  * is copied; `label` is the button text (falls back to slotted text).
  *
@@ -21,7 +21,7 @@ class Vitops_Element_Copy extends \Bricks\Element {
 	public $category     = 'vitops';
 	public $name         = 'vitops-copy-button';
 	public $icon         = 'ti-clipboard';
-	public $css_selector = 'copy-button';
+	public $css_selector = 'wc-copy';
 
 	public function get_label() {
 		return esc_html__( 'Copy Button', 'bricks' );
@@ -60,6 +60,6 @@ class Vitops_Element_Copy extends \Bricks\Element {
 		$attr_str = implode( ' ', $attrs );
 		$fallback = ! empty( $s['label'] ) ? esc_html( $s['label'] ) : esc_html__( 'Copy to clipboard', 'bricks' );
 
-		echo "<copy-button {$attr_str} {$this->render_attributes( '_root' )}>{$fallback}</copy-button>";
+		echo "<wc-copy {$attr_str} {$this->render_attributes( '_root' )}>{$fallback}</wc-copy>";
 	}
 }

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

@@ -2,7 +2,7 @@
 /**
  * Vitops — Multi Field element (Bricks Builder).
  *
- * Renders the <multi-field> 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 = 'multi-field';
+	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 "<multi-field {$attr_str} {$this->render_attributes( '_root' )}>{$inputs}</multi-field>";
+		echo "<wc-multi-field {$attr_str} {$this->render_attributes( '_root' )}>{$inputs}</wc-multi-field>";
 	}
 }

package/assets/css/animation.css

@@ -529,6 +529,85 @@
   }
 }
 
+/* ===========================================
+ * Tier 1c: Top layer (popover / dialog open-close)
+ * The `open-<fx>` state variants (generated, like hover-/focus-/active-) already
+ * supply the VALUES. What a top-layer element additionally needs is mechanism,
+ * and that is the same for every effect — so it lives here, once:
+ *
+ *   <div popover class="drawer drawer--start transition open-slide-right">
+ *
+ * Before this existed there was no driver for the top layer, so every overlay
+ * pattern hand-rolled one: drawer.css drove entry with four @keyframes and
+ * `animation:`, which only plays on OPEN (its close was instant), while
+ * sitenav.css used a transition and animated both ways. Same job, two
+ * mechanisms, two behaviours.
+ * =========================================== */
+
+/* Applied to the top layer BY DEFAULT, and at `:where()` zero specificity.
+ *
+ * Not an opt-in class, unlike the other three drivers, for two reasons. It is
+ * free: every endpoint below defaults to identity (opacity 1, translate 0,
+ * scale 1), so a popover that sets no effect vars transitions between two
+ * identical states and looks exactly as it did before. And it preserves the DX
+ * the keyframes had — `.drawer--right` animated without asking the author for a
+ * driver class, and it still does; it just states its start as
+ * `--translate-x-from: 100%` instead of owning a keyframe.
+ *
+ * Zero specificity means any pattern that wants different motion simply
+ * declares it. */
+:where([popover], dialog) {
+  opacity: var(--t-opacity, var(--opacity-from, 1));
+  translate: var(--t-translate-x, var(--translate-x-from, 0))
+    var(--t-translate-y, var(--translate-y-from, 0));
+  scale: var(--t-scale-x, var(--scale-x-from, 1)) var(--t-scale-y, var(--scale-y-from, 1));
+  rotate: var(--t-rotate, var(--rotate-from, 0deg));
+  clip-path: var(--t-clip, var(--clip-from, none));
+
+  /* `display` and `overlay` are discrete, and BOTH must transition or the
+     element is yanked out of the top layer the instant it closes — you get an
+     entry animation and no exit, which is exactly the asymmetry drawer.css had.
+     `allow-discrete` is what keeps it rendered for the duration. */
+  transition-property: opacity, translate, scale, rotate, clip-path, display, overlay;
+  transition-duration: var(--animation-duration);
+  transition-timing-function: var(--custom-ease-out);
+  transition-behavior: allow-discrete;
+}
+
+/* The open flip. Mirrors what the generated `open-<fx>` variants do, so the
+   common case needs no effect class at all; an explicit `open-<fx>` still wins
+   on specificity and can pick a different effect. */
+:where([popover]:popover-open, dialog[open]) {
+  --t-opacity: var(--opacity-to, 1);
+  --t-translate-x: var(--translate-x-to, 0);
+  --t-translate-y: var(--translate-y-to, 0);
+  --t-scale-x: var(--scale-x-to, 1);
+  --t-scale-y: var(--scale-y-to, 1);
+  --t-rotate: var(--rotate-to, 0deg);
+  --t-clip: var(--clip-to, none);
+}
+
+/* The entry half. A closed popover is `display: none`, so it has no
+   before-change style and the open transition would simply not run —
+   @starting-style supplies one.
+ *
+ * It declares the PROPERTIES rather than resetting the `--t-*` custom
+ * properties, which sidesteps a specificity trap: the generated
+ * `.open-<fx>:popover-open` rules are (0,2,0), set `--t-*`, and are imported
+ * after this file, so a custom-property reset here would have to outrank them.
+ * Setting `opacity`/`translate`/… directly at (0,2,0) instead competes only with
+ * the (0,0,0) base rule above, which it beats regardless of what any effect
+ * class does. */
+@starting-style {
+  :is([popover], dialog):is(:popover-open, [open]) {
+    opacity: var(--opacity-from, 1);
+    translate: var(--translate-x-from, 0) var(--translate-y-from, 0);
+    scale: var(--scale-x-from, 1) var(--scale-y-from, 1);
+    rotate: var(--rotate-from, 0deg);
+    clip-path: var(--clip-from, none);
+  }
+}
+
 /* Respect reduced-motion: drop keyframes, transitions, and continuous floats so
    elements settle at their natural resolved state. Plain selectors + !important
    so this reliably overrides the driver/float rules (a legitimate a11y override). */
@@ -543,6 +622,17 @@
   .transition {
     transition: none !important;
   }
+  /* The top-layer driver is applied by default rather than by class, so it needs
+     naming here explicitly — `.transition` above does not cover it. `display`
+     and `overlay` must still change, they just must not be animated, and
+     `transition: none` is exactly that. */
+  [popover],
+  dialog {
+    transition: none !important;
+  }
+  :where([popover], dialog)::backdrop {
+    transition: none !important;
+  }
 }
 
 /* ===========================================

package/assets/css/global.css

@@ -32,6 +32,16 @@
    around them. */
 body {
   margin: 0;
+
+  /* Long unbreakable strings are the single most common source of horizontal
+     page scroll, and prose is full of them — URLs, file paths, CSS selectors.
+     `break-word` rather than `anywhere` on purpose: it only takes effect when a
+     word would otherwise overflow, and it does NOT contribute to min-content
+     sizing, so no existing layout's intrinsic measurements move. (`anywhere`
+     does affect min-content, which would silently resize every intrinsically
+     sized box in a consumer's site.) Inline <code> gets the stronger `anywhere`
+     in patterns/code.css, where a break mid-token is the correct trade. */
+  overflow-wrap: break-word;
 }
 
 @media (prefers-reduced-motion: no-preference) {

package/assets/css/index.css

@@ -33,7 +33,12 @@
 @import './patterns/tooltip.css';
 @import './patterns/dropdown.css';
 @import './patterns/split-link.css';
+/* navbar before sitenav: sitenav's wide state composes it. */
+@import './patterns/navbar.css';
 @import './patterns/sitenav.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';
 @import './patterns/notification.css';
 @import './patterns/lightbox.css';
 @import './patterns/overlay.css';