@getvitops/core 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,187 @@
 # @getvitops/core
 
+## 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
+
+- Updated dependencies [20e518e]
+- Updated dependencies [9bf975a]
+  - @getvitops/utils@2.1.0
+
 ## 2.0.0
 
 ### Major 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';

package/css/layout-utilities.css

@@ -156,43 +156,57 @@
     grid-column: fullbleed;
   }
 }
+/* Every ratio publishes `--_flex-direction` alongside `flex-direction`. Only the
+   `.flex-*` utilities used to do that, so `class="split flex-col md-split-1-2"`
+   left the variable reading `column` at ALL widths — and patterns/grouped.css
+   resolves its collapsed-border axis from a `@container style(--_flex-direction:
+   column)` query, so a `.grouped` inside a re-rowed split collapsed on the wrong
+   axis with nothing to indicate why. */
 .split-1-2 {
   flex-direction: row;
+  --_flex-direction: row;
   --_split-a: 1;
   --_split-b: 2;
 }
 .split-2-1 {
   flex-direction: row;
+  --_flex-direction: row;
   --_split-a: 2;
   --_split-b: 1;
 }
 .split-1-3 {
   flex-direction: row;
+  --_flex-direction: row;
   --_split-a: 1;
   --_split-b: 3;
 }
 .split-3-1 {
   flex-direction: row;
+  --_flex-direction: row;
   --_split-a: 3;
   --_split-b: 1;
 }
 .split-1-4 {
   flex-direction: row;
+  --_flex-direction: row;
   --_split-a: 1;
   --_split-b: 4;
 }
 .split-4-1 {
   flex-direction: row;
+  --_flex-direction: row;
   --_split-a: 4;
   --_split-b: 1;
 }
 .split-2-3 {
   flex-direction: row;
+  --_flex-direction: row;
   --_split-a: 2;
   --_split-b: 3;
 }
 .split-3-2 {
   flex-direction: row;
+  --_flex-direction: row;
   --_split-a: 3;
   --_split-b: 2;
 }
@@ -393,41 +407,49 @@
 @container (min-width: 30rem) {
   .sm-split-1-2 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 2;
   }
   .sm-split-2-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 2;
     --_split-b: 1;
   }
   .sm-split-1-3 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 3;
   }
   .sm-split-3-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 3;
     --_split-b: 1;
   }
   .sm-split-1-4 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 4;
   }
   .sm-split-4-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 4;
     --_split-b: 1;
   }
   .sm-split-2-3 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 2;
     --_split-b: 3;
   }
   .sm-split-3-2 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 3;
     --_split-b: 2;
   }
@@ -441,41 +463,49 @@
 @container (min-width: 48rem) {
   .md-split-1-2 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 2;
   }
   .md-split-2-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 2;
     --_split-b: 1;
   }
   .md-split-1-3 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 3;
   }
   .md-split-3-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 3;
     --_split-b: 1;
   }
   .md-split-1-4 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 4;
   }
   .md-split-4-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 4;
     --_split-b: 1;
   }
   .md-split-2-3 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 2;
     --_split-b: 3;
   }
   .md-split-3-2 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 3;
     --_split-b: 2;
   }
@@ -489,41 +519,49 @@
 @container (min-width: 64rem) {
   .lg-split-1-2 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 2;
   }
   .lg-split-2-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 2;
     --_split-b: 1;
   }
   .lg-split-1-3 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 3;
   }
   .lg-split-3-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 3;
     --_split-b: 1;
   }
   .lg-split-1-4 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 4;
   }
   .lg-split-4-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 4;
     --_split-b: 1;
   }
   .lg-split-2-3 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 2;
     --_split-b: 3;
   }
   .lg-split-3-2 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 3;
     --_split-b: 2;
   }
@@ -537,41 +575,49 @@
 @container (min-width: 80rem) {
   .xl-split-1-2 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 2;
   }
   .xl-split-2-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 2;
     --_split-b: 1;
   }
   .xl-split-1-3 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 3;
   }
   .xl-split-3-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 3;
     --_split-b: 1;
   }
   .xl-split-1-4 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 1;
     --_split-b: 4;
   }
   .xl-split-4-1 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 4;
     --_split-b: 1;
   }
   .xl-split-2-3 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 2;
     --_split-b: 3;
   }
   .xl-split-3-2 {
     flex-direction: row;
+    --_flex-direction: row;
     --_split-a: 3;
     --_split-b: 2;
   }

package/css/layout.css

@@ -46,10 +46,82 @@
 .rhythm > * + * {
   margin-top: calc(var(--rhythm-base) * var(--rhythm-p-p));
 }
-.rhythm > :where(h1, h2, h3, h4, h5, h6) + p {
+/* The heading pairs are defined by what a heading IS, not by a list of what can
+   sit next to one.
+   These used to enumerate the other side (`p`, then `p, pre, blockquote, table,
+   dl, ul, ol`), and an enumeration is a list that is always one element short:
+   first a `<pre>` got paragraph-to-paragraph spacing before a heading, then a
+   `<div class="marquee">` did. Any block is content; only headings are special.
+   So the rules invert — `:not(<heading>) + <heading>` — and nothing has to be
+   added here again.
+
+   `:where()` keeps the whole selector at (0,1,0), the same weight as the generic
+   `* + *` above, so SOURCE ORDER is what makes these win. Keep them below it,
+   and keep the media pairs below these — `figure + h2` matches both, and the
+   media rule is meant to take it.
+
+   A heading is also a TYPE ROLE, not just a tag: this framework's own idiom is
+   `<p class="font-heading">` inside a card, which is a heading in every sense
+   that matters to rhythm.
+
+   Those three are matched with `[class~="…"]`, not `.font-heading`, and the
+   difference is not cosmetic. `LAYER_CONTRACT` asserts that a utility's class
+   name appears first in `vitops.utilities`; writing `.font-display` here — in a
+   partial that lands in `vitops.components` — reads to that guard exactly like a
+   utility defined in the wrong layer, and it fails the build. The attribute form
+   says what is true: this rule REFERENCES the class, it does not define it. */
+.rhythm
+  > :where(
+    h1,
+    h2,
+    h3,
+    h4,
+    h5,
+    h6,
+    [class~='font-display'],
+    [class~='font-title'],
+    [class~='font-heading']
+  )
+  + :not(
+    :where(
+      h1,
+      h2,
+      h3,
+      h4,
+      h5,
+      h6,
+      [class~='font-display'],
+      [class~='font-title'],
+      [class~='font-heading']
+    )
+  ) {
   margin-top: calc(var(--rhythm-base) * var(--rhythm-h-p));
 }
-.rhythm > p + :where(h1, h2, h3, h4, h5, h6) {
+.rhythm
+  > :not(
+    :where(
+      h1,
+      h2,
+      h3,
+      h4,
+      h5,
+      h6,
+      [class~='font-display'],
+      [class~='font-title'],
+      [class~='font-heading']
+    )
+  )
+  + :where(
+    h1,
+    h2,
+    h3,
+    h4,
+    h5,
+    h6,
+    [class~='font-display'],
+    [class~='font-title'],
+    [class~='font-heading']
+  ) {
   margin-top: calc(var(--rhythm-base) * var(--rhythm-p-h));
 }
 .rhythm > :where(h1, h2, h3, h4, h5, h6) + :where(h1, h2, h3, h4, h5, h6) {
@@ -81,6 +153,11 @@
   --width-measure: 65ch;
   --width-breakout: 90ch;
   --width-spotlight: 120ch;
+  /* A navigation column beside content (`navshell`). In `rem`, not `ch`, unlike
+     the three above: those are reading measures and scale with the text they
+     hold, while a nav column is chrome sized in the page's own rhythm — it
+     should not get wider because the prose font has a wide `0` glyph. */
+  --width-nav: 16rem;
   --gutter: clamp(1rem, 4cqi, 3rem);
 }
 
@@ -110,6 +187,14 @@ body {
 
 .centered > * {
   grid-column: measure;
+  /* A grid item's automatic minimum size is its MIN-CONTENT size, and every
+     track here is definite (`--_measure` is a min() of two lengths; the rest are
+     minmax(0, …)). So a track child holding something with a large min-content —
+     a wide <pre>, a long unbreakable token — pushes past its track and the whole
+     document scrolls sideways. This caps the container; wrapping or scrolling
+     the CONTENT (see global.css and patterns/code.css) is what stops the visual
+     overflow. */
+  min-inline-size: 0;
 }
 
 /* Vertical rhythm region (usually on the Section) */