@getvitops/core 2.1.0 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,361 @@
 # @getvitops/core
 
+## 4.0.0
+
+### Major Changes
+
+- 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.
+
+- Every custom element now carries the `wc-` prefix. **Two renames affect existing markup:**
+  - `<color-scheme-toggle>` → **`<wc-color-scheme-toggle>`**
+  - `<wc-multifield>` → **`<wc-multi-field>`**
+
+  Update your templates. An unknown element name is not an error — the browser treats it as an
+  inert `HTMLUnknownElement` — so a missed rename shows up as a control that renders and simply
+  never works, with nothing in the console.
+
+  `<wc-multifield>` was itself renamed in 3.0 (from `<multi-field>`), and hyphenating it now
+  means the tag matches its pattern name and its Bricks element everywhere else in the toolchain;
+  `3.0` shipped the inconsistency by accident.
+
+  **Unchanged:** the Bricks element keys (`vitops-color-scheme-toggle`, `vitops-multi-field`), so
+  elements already placed on a Bricks page keep working; the custom properties; and the events.
+
+  The remaining renames are prefix-only and reach no consumer: `<color-wheel>`, `<icon-picker>`,
+  `<oklch-color-picker>` and `<typography-config>` are registered but shipped in **no bundle** (the
+  editor-v2 track), so those tags were already inert in a consumer project — `vitops docs components`
+  now says so per element rather than leaving it to be discovered.
+
+### Minor Changes
+
+- 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
+
+- 14813fa: Fix `<wc-entries>`, `<wc-carousel>` and `<wc-marquee>` silently failing to enhance when inserted
+  dynamically.
+
+  All three parse their slotted markup in `connectedCallback` and return early when they find
+  nothing. That is fine when `elements.js` loads as a deferred module, because the document is
+  fully parsed before any definition registers. But an element upgraded _during_ insertion is
+  connected **before its children exist** — verified: an `innerHTML` write runs
+  `connectedCallback` with zero children.
+
+  So on an Astro view-transition swap, a client-side navigation, an `innerHTML` write or a cloned
+  template, `<wc-entries>` never built its table, `<wc-carousel>` never cloned its slides or
+  started autoplay, and `<wc-marquee>` never took over from the CSS-only path. Nothing errored;
+  the un-enhanced fallback just stayed on screen, which is why this went unnoticed.
+
+  Initialisation is now expressed as a function that reports whether it found its markup, and is
+  retried once the insertion completes (`initFromLightDom`). Setup is guarded so a retry after a
+  genuinely empty state can't double-apply — an `<wc-entries>` building its table twice would
+  have been the obvious way to fix this badly.
+
+  `<wc-tree>` uses the same helper. If you write a light-DOM component, use it too; the hazard is
+  documented in `web-components/utils/upgrade.ts`.
+
+- a9d7916: Fix `sitenav` shipping its drawer geometry into its navbar state.
+
+  A `.sitenav` carrying both a drawer-direction modifier and a breakpoint promotion rendered its navbar one full panel-width toward the inline-end at and above the promotion width — off the page, with a horizontal scrollbar and anything laid out after the panel pushed out of view. Reported downstream against `sitenav--bp-lg sitenav--drawer-end`; it affected every `--bp-*` value and both drawer directions.
+
+  One cause, three symptoms. `@container` contributes no specificity, so when the four per-breakpoint blocks were consolidated into a single style query in 3.0.0, the wide-state reset lost the `.sitenav--bp-*` class that had been winning it the tie. Every narrow-state rule with a heavier selector then won _inside the wide state_:
+  - `.sitenav--drawer-end .sitenav__panel` (0,2,0) beat the navbar's `translate: none` (0,1,0) — the reported bug.
+  - The mobile accordion's `.sitenav__item--branch > .sitenav__submenu { overflow: hidden }` (0,2,0) beat the dropdown's `overflow: visible`, which **clipped away every third-level megamenu** at width. Its `padding-inline-start: 1rem` leaked in the same way.
+  - The wide block's counter-rule for depth caps beat the base `.sitenav__submenu { display: flex }`, so a `sitenav__item--desktop-branch` dropdown lost its column direction and gap.
+
+  The drawer and the navbar are now mutually exclusive branches of the same style query — `@container style(--_sitenav-wide: 0)` alongside the existing `: 1` — so there is no cascade contest to lose rather than a contest that is currently being won. A new test in core asserts the invariant across every two-state pattern.
+
+  **Two visible changes at width, both intended:** dropdown padding is now symmetric `0.5rem` (it was `1rem` on the inline-start side only), and depth-capped dropdowns regain their `0.25rem` gap.
+
+  Also fixed in the same pattern: `.sitenav__panel` never undid the UA `[popover]` sheet's `margin: auto` and `height: fit-content`, so `inset-block: 0` bought nothing and the drawer rendered as a content-height card floating in the vertical centre instead of filling the edge. It is now a full-height drawer, and the auto margins no longer absorb free space when a promoted `.sitenav` is stretched rather than content-sized.
+
+  Note the narrow state now also depends on `@container style()` (Chrome 111 / Safari 18 / Firefox 128), which the wide state already required. On an older engine the sitenav degrades to a popover holding an expanded link list — usable and accessible, but neither drawer nor navbar.
+
+- 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
 
 ### Patch Changes

package/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/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/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';