scavold 0.2.0-rc.7 → 0.2.0

package/COMPONENTS.md

@@ -1,5 +1,9 @@
 # Scavold component and composable reference
 
+<!-- Components and composables are listed in alphabetical order, each group on its
+     own; the sectioning wrappers close the components as one entry. A new one goes
+     where its name sorts, never simply at the end. -->
+
 All components are registered globally by `enhanceApp()` and are available in any
 Markdown page or Vue template without explicit imports. Composables must be imported
 explicitly.
@@ -14,154 +18,299 @@ the broader "when and why" context that hover docs cannot convey.
 
 ---
 
-### `<ScavoldMenu>`
+### `<ScavoldBreadcrumb>`
 
-Renders a `<nav>` element containing a nested list of page links derived from the
-site's page hierarchy. Nothing is rendered when the resolved item set is empty.
+Renders a `<nav class="breadcrumb">` element containing a flat list of links
+representing the path from the root to the current page. Uses the same
+`<ul>/<li>/<a>` structure as `<ScavoldMenu>` so both components can share CSS.
 
-The component has three independent addressing modes — path-based, absolute (from
-root), and relative (from current page) — that cover all common navigation patterns
-without requiring knowledge of the current page's depth.
+Each item in the trail carries `.active` (all ancestor items) and `.current` (the
+last item, if the current page is included). This makes it straightforward to style
+the current crumb differently in CSS.
 
 #### Props
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `from-path` | `string` | — | Select the parent node by path. Supports `{locale}` (full BCP 47 tag, e.g. `de-CH`) and `{lang}` (primary language subtag only, e.g. `de`) placeholders, replaced with the current page's locale at runtime. Takes priority over `from-root` and `from`. Examples: `"de/footer"`, `"{lang}/footer"`, `"{locale}/footer"`. |
-| `from-root` | `number` | — | List items at this absolute depth from root. `1` = top-level pages, `2` = second level, etc. When set, `from` is ignored. If the current page has no ancestor at this depth, nothing is rendered. Ignored when `from-path` is set. |
-| `from` | `number` | `0` | List items relative to the current page. `0` = siblings, `1` = children, `-1` = aunt/uncle level (children of grandparent), etc. Ignored when `from-root` or `from-path` is set. |
-| `depth` | `number` | `0` | Additional levels to descend below the starting level. `0` = flat list, `1` = one level of children, `-1` = unlimited. |
-| `active-only` | `boolean` | `false` | When `true`, only expands children along the branch leading to the current page. Useful with `depth > 0` to show sub-items under the active section only. |
-| `expand` | `boolean` | `false` | When `true`, expands children of all nodes regardless of the active branch. Enables sitemap-style rendering. `active-only` takes precedence when both are set. |
-| `label` | `string` | — | Accessible label for the `<nav>` landmark (`aria-label`). Should be set whenever more than one `<ScavoldMenu>` appears on the same page so screen readers can distinguish them (e.g. `"Main navigation"`, `"Section navigation"`). |
+| `include-current` | `boolean` | `true` | Include the current page as the last crumb |
+| `include-root` | `boolean` | `false` | Include the root node (typically "Home") as the first crumb |
 
 #### Rendered markup
 
 ```html
-<nav>
+<!-- on page de/leistungen.md with include-root omitted -->
+<nav class="breadcrumb">
   <ul>
-    <li class="active">          <!-- .active when node is current or an ancestor -->
-      <a href="/section/">Section</a>
-      <ul>                       <!-- nested only when children are included -->
-        <li class="current">
-          <a href="/section/page/">Page</a>
-        </li>
-      </ul>
+    <li class="active">
+      <a href="/de/">Deutsch</a>    <!-- de/ folder node, label from de/index.md -->
+    </li>
+    <li class="active current">
+      <a href="/de/leistungen/">Leistungen</a>
     </li>
   </ul>
 </nav>
 ```
 
-The `.active` class is set on any item that is an ancestor of the current page or the
-current page itself. The `.current` class is set only on the item that exactly matches
-the current page.
+#### Examples
 
-#### Label resolution
+```html
+<!-- typical usage — section trail + current page -->
+<ScavoldBreadcrumb />
 
-Item labels are resolved in this order:
+<!-- trail without current page, e.g. when page heading serves as final crumb -->
+<ScavoldBreadcrumb :include-current="false" />
 
-1. `label` frontmatter — explicit navigation text, overrides everything
-2. `title` frontmatter — page title, used when no `label` is set
-3. First `#` heading in the page body — extracted at build time as a fallback when neither `label` nor `title` is declared in frontmatter
-4. The last path segment of the page file (e.g. `about` from `de/about.md`) — last resort
+<!-- full trail including home link -->
+<ScavoldBreadcrumb include-root />
+```
 
-#### Hiding pages via front matter
+---
 
-A page can opt out of appearing in menus by setting `hide` in its front matter:
+### `<ScavoldContainer>`
 
-| Value | Effect |
-|---|---|
-| `false` / absent | Visible everywhere (default) |
-| `true` | Kept off every surface: menus, breadcrumbs, page lists and the feed |
-| `"menu"` | Kept out of menus only |
-| `"breadcrumb"` | Kept out of breadcrumbs only |
-| `"list"` | Kept out of page lists only |
-| `"feed"` | Left out of the RSS feed only |
-| `[ "menu", "feed" ]` | Kept off exactly the surfaces named |
+Fallback component for Markdown container blocks whose name has no dedicated
+registered component. Renders as the matching HTML sectioning element if the
+container name is one (`section`, `aside`, etc.), otherwise as a `<div>`.
+
+Any container name works without being declared first — undeclared names are caught
+by this component. Because a typo would otherwise become a silent `<div>`, the build
+reports each undeclared name once:
+
+```
+[scavold] container ':::sectoin' is not declared in .cratly.config.yaml — rendering
+it with ScavoldContainer. Declare it to silence this, or fix the name if it is a typo.
+```
+
+Declaring the container in `.cratly.config.yaml` silences the report and gives it
+typed properties in the cratly editor.
+
+Not intended for direct use. Theme developers should instead create a dedicated
+component for each container name they declare in `.cratly.config.yaml`.
+
+See [`useContainer`](#usecontainer-props) for building custom container components.
 
-```yaml
----
-hide: menu
 ---
+
+### `<ScavoldCover>`
+
+Shows an image or a video across the full width of the window and at least as high as
+the window, cropped to fit — a cover, or hero, at the top of a page. Written as a
+`:::cover` container block; whatever the block contains is laid on top of the picture.
+
+#### Markdown syntax
+
+```markdown
+::: cover src=/wind-farm.jpg focus="center top" label="Wind turbines at dusk"
+# With new energy into the future
+:::
+
+::: cover src=/turbines.mp4 poster=/turbines.jpg
+:::
 ```
 
-#### Examples
+#### Arguments
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `src` | `media-file` | required | Image or video. A file ending in `.mp4`, `.m4v`, `.webm`, `.ogv` or `.mov` is played as a video, anything else is shown as an image. |
+| `poster` | `media-file` | — | Only for a video: still image shown until it plays, and instead of playing for visitors who asked for reduced motion. |
+| `focus` | `string` | `50% 50%` | Part of the picture kept visible when the window crops it, as a CSS `object-position` — `center top`, `30% 60%`. |
+| `label` | `string` | — | Alternative text of an image, accessible label of a video. Left out, the picture is treated as decoration. |
+| `tone` | `"light" \| "dark"` | — | Whether the content on top is meant to be light (over a dark picture) or dark (over a bright one). Only marks the cover with `scavold-cover--light` or `scavold-cover--dark`; what that looks like is the theme's. Left out, or with any other value, the cover carries neither class. |
+
+#### Rendered markup
 
 ```html
-<!-- top-level pages — typical site header nav -->
-<ScavoldMenu :from-root="1" />
+<!-- image, tone=light -->
+<div class="scavold-cover scavold-cover--light" style="--scavold-cover-focus: center top">
+  <picture class="scavold-cover__media">
+    <source type="image/webp" srcset="..." sizes="(min-aspect-ratio: 2400/1350) 100vw, 177.78vh" />
+    <source srcset="..." sizes="..." />
+    <img src="..." alt="..." sizes="..." loading="eager" fetchpriority="high" decoding="async" />
+  </picture>
+  <div class="scavold-cover__overlay"><!-- block content --></div>
+</div>
 
-<!-- second level of the active top-level section only -->
-<ScavoldMenu :from-root="2" active-only />
+<!-- video -->
+<div class="scavold-cover scavold-cover--video">
+  <video class="scavold-cover__media" src="..." poster="..." preload="metadata" muted loop playsinline></video>
+  <div class="scavold-cover__overlay"><!-- block content --></div>
+  <button type="button" class="scavold-cover__toggle" aria-label="Pause video">…</button>
+</div>
+```
 
-<!-- children of the current page -->
-<ScavoldMenu :from="1" />
+An image comes with all its variants. Its `sizes` value is derived from its aspect
+ratio: a picture covering an upright phone screen is drawn much wider than the screen,
+and the browser has to fetch a variant for that width, not for the width of the screen.
+It is loaded at once rather than lazily, since a cover is the first thing on a page.
 
-<!-- siblings of the current page -->
-<ScavoldMenu />
+A video plays muted in a loop, started by script — unless the visitor's system asks
+for reduced motion, in which case the still image stays and the button offers to start
+it. It plays while at least half of it is on screen — half of the window, for one higher
+than the window — and pauses when scrolled away. A video the visitor paused stays
+paused until they start it again, and one they turned the sound up on keeps playing
+when scrolled away. The button is always there: moving content that lasts more
+than five seconds has to be pausable (WCAG 2.2.2). Its label follows the state and comes
+from the [`@scavold.cover.*` translations](#built-in-translation-keys).
 
-<!-- full site hierarchy as a sitemap -->
-<ScavoldMenu :from-root="1" :depth="-1" />
+#### Fitting it into the theme
 
-<!-- two levels starting from the active top-level section, active branch expanded -->
-<ScavoldMenu :from-root="1" :depth="1" active-only />
+The component ships functional layout CSS only. It leaves the column it is written in
+by `margin-inline: calc(50% - 50vw)`, which assumes a column centred in the window. Two
+things are the theme's to settle:
 
-<!-- fixed path — same footer nav regardless of locale -->
-<ScavoldMenu from-path="de/footer" label="Footer-Navigation" />
+```css
+/* 100vw includes a classic scrollbar, so the cover would stick out by its width */
+html { overflow-x: clip; }
 
-<!-- locale-aware via primary language tag — works when paths use "de", "en", etc. -->
-<ScavoldMenu from-path="{lang}/footer" label="Footer-Navigation" />
+/* leave room for a fixed header; the default is the window height, 100svh */
+.scavold-cover { --scavold-cover-height: calc(100svh - var(--header-height)); }
+```
 
-<!-- locale-aware via full BCP 47 tag — use when paths include region codes like "de-CH" -->
-<ScavoldMenu from-path="{locale}/footer" label="Footer-Navigation" />
+The overlay is an empty grid cell over the picture; position its content, add a scrim
+for legibility and restyle `.scavold-cover__toggle` as the design asks.
+
+The `tone` an author picked is the theme's to honour. Scavold sets no colour for it;
+a theme gives each tone the colours of its design, including headings and links its
+prose styles colour on their own:
+
+```css
+.scavold-cover--light .scavold-cover__overlay { color: #fff; }
+.scavold-cover--dark .scavold-cover__overlay { color: #000; }
 ```
 
----
+#### A cover opening the page
 
-### `<ScavoldBreadcrumb>`
+Where the theme's own parts go around a cover is the theme's choice; Scavold places
+none of them. It only tells, in two ways, that a page opens with a container:
 
-Renders a `<nav class="breadcrumb">` element containing a flat list of links
-representing the path from the root to the current page. Uses the same
-`<ul>/<li>/<a>` structure as `<ScavoldMenu>` so both components can share CSS.
+- the container carries an empty `data-leading` attribute;
+- the page data carry `leadingContainer`, the name of that container (`"cover"`), or
+  `null` when the page opens with anything else. A layout renders its own parts before
+  the page content, so this is known at build time, ahead of the content.
 
-Each item in the trail carries `.active` (all ancestor items) and `.current` (the
-last item, if the current page is included). This makes it straightforward to style
-the current crumb differently in CSS.
+A theme that wants its breadcrumb below a cover opening the page, rather than above
+it, combines both. The layout leaves out the breadcrumb on such a page:
+
+```vue
+<!-- Layout.vue -->
+<script setup>
+import { useData } from "vitepress";
+const { page } = useData();
+</script>
+
+<template>
+  <ScavoldBreadcrumb v-if="page.leadingContainer !== 'cover'" />
+  <Content />
+</template>
+```
+
+…and the cover is mapped to a component of the site's own that wraps the built-in one
+and adds the breadcrumb after it when it is the leading one:
+
+```yaml
+# .cratly.config.yaml — the editor keeps offering the cover's own properties
+containers:
+  cover:
+    component: SiteCover
+```
+
+```vue
+<!-- .vitepress/theme/components/SiteCover.vue -->
+<script setup>
+import ScavoldCover from "scavold/components/ScavoldCover.vue";
+import ScavoldBreadcrumb from "scavold/components/ScavoldBreadcrumb.vue";
+
+defineOptions( { inheritAttrs: false } );
+</script>
+
+<template>
+  <ScavoldCover v-bind="$attrs"><slot /></ScavoldCover>
+  <ScavoldBreadcrumb v-if="$attrs['data-leading'] != null" />
+</template>
+```
+
+```js
+// .vitepress/theme/index.js — the container renders the component by name
+async function enhanceApp( context ) {
+    await scavoldEnhanceApp( context );
+    context.app.component( "SiteCover", SiteCover );
+}
+```
+
+Below a cover the breadcrumb sits inside the content column, so the theme's prose
+styles reach its list; keep them out where they differ from the breadcrumb's own.
+
+Visual and reading order stay the same this way, which a reordering stylesheet could
+not promise.
+
+---
+
+### `<ScavoldImage>`
+
+Renders a responsive `<picture>` element for local images. Not intended for direct
+use in templates — it is emitted automatically by the Markdown image renderer when a
+local image path is encountered. Custom components that need to display a media-file
+frontmatter field can use it directly.
 
 #### Props
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `include-current` | `boolean` | `true` | Include the current page as the last crumb |
-| `include-root` | `boolean` | `false` | Include the root node (typically "Home") as the first crumb |
+| `src` | `string` | required | URL of the largest fallback image variant |
+| `srcset` | `string` | `""` | `srcset` string for the original format (JPEG/PNG) |
+| `webp-srcset` | `string` | `""` | `srcset` string for the WebP variants |
+| `sizes` | `string` | `"100vw"` | CSS `sizes` attribute applied to all sources |
+| `alt` | `string` | `""` | Alt text for the `<img>` element |
+| `loading` | `string` | `"lazy"` | `loading` attribute of the `<img>`; `"eager"` for an image at the top of a page |
+| `fetchpriority` | `string` | — | `fetchpriority` attribute of the `<img>`, e.g. `"high"` for the largest image above the fold |
 
 #### Rendered markup
 
 ```html
-<!-- on page de/leistungen.md with include-root omitted -->
-<nav class="breadcrumb">
-  <ul>
-    <li class="active">
-      <a href="/de/">Deutsch</a>    <!-- de/ folder node, label from de/index.md -->
-    </li>
-    <li class="active current">
-      <a href="/de/leistungen/">Leistungen</a>
-    </li>
-  </ul>
-</nav>
+<picture>
+  <source type="image/webp" srcset="..." sizes="..." />
+  <source srcset="..." sizes="..." />
+  <img src="..." alt="..." sizes="..." loading="lazy" decoding="async" />
+</picture>
 ```
 
-#### Examples
+---
 
-```html
-<!-- typical usage — section trail + current page -->
-<ScavoldBreadcrumb />
+### `<ScavoldLayout>`
 
-<!-- trail without current page, e.g. when page heading serves as final crumb -->
-<ScavoldBreadcrumb :include-current="false" />
+Base layout wrapper that intercepts pages with locale-conditional redirect front
+matter and renders `<ScavoldLocaleRedirect>` in their place. All other pages render
+the default slot.
 
-<!-- full trail including home link -->
-<ScavoldBreadcrumb include-root />
+Consuming themes wrap their own layout root element in this component so they
+automatically inherit redirect handling without duplicating the detection logic:
+
+```vue
+<template>
+  <ScavoldLayout>
+    <div class="site-shell">
+      <!-- header, main, footer … -->
+    </div>
+  </ScavoldLayout>
+</template>
+```
+
+Themes that need finer control can skip `<ScavoldLayout>` and compose the two
+building blocks themselves using `useRedirect` and `<ScavoldLocaleRedirect>`:
+
+```vue
+<script setup>
+import { useRedirect } from "./scavold/composables/useRedirect.js";
+import ScavoldLocaleRedirect from "./scavold/components/ScavoldLocaleRedirect.vue";
+
+const { isLocaleRedirect } = useRedirect();
+</script>
+
+<template>
+  <ScavoldLocaleRedirect v-if="isLocaleRedirect" />
+  <div v-else class="site-shell"><!-- … --></div>
+</template>
 ```
 
 ---
@@ -263,48 +412,10 @@ pages/
 
 ---
 
-### `<ScavoldLayout>`
-
-Base layout wrapper that intercepts pages with locale-conditional redirect front
-matter and renders `<ScavoldLocaleRedirect>` in their place. All other pages render
-the default slot.
+### `<ScavoldLocaleRedirect>`
 
-Consuming themes wrap their own layout root element in this component so they
-automatically inherit redirect handling without duplicating the detection logic:
-
-```vue
-<template>
-  <ScavoldLayout>
-    <div class="site-shell">
-      <!-- header, main, footer … -->
-    </div>
-  </ScavoldLayout>
-</template>
-```
-
-Themes that need finer control can skip `<ScavoldLayout>` and compose the two
-building blocks themselves using `useRedirect` and `<ScavoldLocaleRedirect>`:
-
-```vue
-<script setup>
-import { useRedirect } from "./scavold/composables/useRedirect.js";
-import ScavoldLocaleRedirect from "./scavold/components/ScavoldLocaleRedirect.vue";
-
-const { isLocaleRedirect } = useRedirect();
-</script>
-
-<template>
-  <ScavoldLocaleRedirect v-if="isLocaleRedirect" />
-  <div v-else class="site-shell"><!-- … --></div>
-</template>
-```
-
----
-
-### `<ScavoldLocaleRedirect>`
-
-Handles locale-conditional redirect pages declared with an object-form `redirect`
-in front matter:
+Handles locale-conditional redirect pages declared with an object-form `redirect`
+in front matter:
 
 ```yaml
 ---
@@ -328,138 +439,136 @@ The component renders no visible content of its own. It is used automatically by
 
 ---
 
-### `<ScavoldMenuItems>`
+### `<ScavoldMenu>`
 
-Internal recursive component used by `<ScavoldMenu>` to render `<ul>/<li>` trees.
-Not intended for direct use. Documented here for theme developers who want to build
-their own menu component using `useHierarchy`.
+Renders a `<nav>` element containing a nested list of page links derived from the
+site's page hierarchy. Nothing is rendered when the resolved item set is empty.
 
----
+The component has three independent addressing modes — path-based, absolute (from
+root), and relative (from current page) — that cover all common navigation patterns
+without requiring knowledge of the current page's depth.
 
-### `<ScavoldVideo>`
+With `menu`, it renders a **named menu** instead: the pages choosing that menu in
+their [`menus`](./FRONTMATTER.md#menus) front matter, wherever they sit among the folders.
+The names are declared in `.cratly.config.yaml`; where a menu goes is up to the theme.
 
-Renders a `<video>` element for a video embedded via the `:::video` container block.
-Nothing is rendered when no `src` argument is provided.
+#### Props
 
-#### Markdown syntax
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `menu` | `string` | — | Render the named menu declared under this name in `.cratly.config.yaml`: the pages choosing it in their `menus` front matter, in page-tree order. `from-path` and `from-root` then narrow the part of the site searched — `from-path="{lang}"` keeps a multilingual site's menu to one language — and `from` is ignored. `depth`, `active-only` and `expand` descend below each listed page. A page choosing the menu along with one of its ancestors is listed below that ancestor when `depth` allows sub-pages, and beside it when the menu is flat. |
+| `from-path` | `string` | — | Select the parent node by path. Supports `{locale}` (full BCP 47 tag, e.g. `de-CH`) and `{lang}` (primary language subtag only, e.g. `de`) placeholders, replaced with the current page's locale at runtime. Takes priority over `from-root` and `from`. Examples: `"de/footer"`, `"{lang}/footer"`, `"{locale}/footer"`. |
+| `from-root` | `number` | — | List items at this absolute depth from root. `1` = top-level pages, `2` = second level, etc. When set, `from` is ignored. If the current page has no ancestor at this depth, nothing is rendered. Ignored when `from-path` is set. |
+| `from` | `number` | `0` | List items relative to the current page. `0` = siblings, `1` = children, `-1` = aunt/uncle level (children of grandparent), etc. Ignored when `from-root` or `from-path` is set. |
+| `depth` | `number` | `0` | Additional levels to descend below the starting level. `0` = flat list, `1` = one level of children, `-1` = unlimited. |
+| `active-only` | `boolean` | `false` | When `true`, only expands children along the branch leading to the current page. Useful with `depth > 0` to show sub-items under the active section only. |
+| `expand` | `boolean` | `false` | When `true`, expands children of all nodes regardless of the active branch. Enables sitemap-style rendering. `active-only` takes precedence when both are set. |
+| `label` | `string` | — | Accessible label for the `<nav>` landmark (`aria-label`). Should be set whenever more than one `<ScavoldMenu>` appears on the same page so screen readers can distinguish them (e.g. `"Main navigation"`, `"Section navigation"`). |
 
-```markdown
-::: video src=./clip.mp4 poster=./thumb.jpg
-Optional caption or fallback text for browsers that do not support the video element.
-:::
+#### Rendered markup
+
+```html
+<nav>
+  <ul>
+    <li class="active">          <!-- .active when node is current or an ancestor -->
+      <a href="/section/">Section</a>
+      <ul>                       <!-- nested only when children are included -->
+        <li class="current">
+          <a href="/section/page/">Page</a>
+        </li>
+      </ul>
+    </li>
+  </ul>
+</nav>
 ```
 
-#### Arguments
+The `.active` class is set on any item that is an ancestor of the current page or the
+current page itself. The `.current` class is set only on the item that exactly matches
+the current page.
 
-| Argument | Type | Default | Description |
-|---|---|---|---|
-| `src` | `string` | required | URL of the video file |
-| `poster` | `string` | — | URL of the poster image shown before playback |
-| `autoplay` | flag | — | Play automatically on load. Forces `muted` (browser requirement) |
-| `loop` | flag | — | Loop the video when it ends |
-| `muted` | flag | — | Mute the audio track |
-| `overlay` | flag | — | Render the video as a background and lay the block's body content on top of it (hero/background mode). See below. |
-| `controls` | flag | — | Show native playback controls. Always shown in the default player; opt-in in `overlay` mode, which is chrome-free by default. |
-| `preload` | `"none" \| "metadata" \| "auto"` | `"metadata"` | Browser preload hint |
-| `label` | `string` | — | Accessible label (`aria-label`) announced by screen readers. Use when the surrounding context does not already describe the video. |
+#### Label resolution
 
-Boolean flags are written without a value:
+Item labels are resolved in this order:
 
-```markdown
-::: video src=./clip.mp4 autoplay loop
-:::
-```
+1. `label` frontmatter — explicit navigation text, overrides everything
+2. `title` frontmatter — page title, used when no `label` is set
+3. First `#` heading in the page body — extracted at build time as a fallback when neither `label` nor `title` is declared in frontmatter
+4. The last path segment of the page file (e.g. `about` from `de/about.md`) — last resort
 
-#### Rendered markup
+#### Hiding pages via front matter
 
-```html
-<video src="..." poster="..." preload="metadata" controls playsinline>
-  <!-- slot content -->
-</video>
+A page can opt out of appearing in menus by setting `hide` in its front matter:
+
+| Value | Effect |
+|---|---|
+| `false` / absent | Visible everywhere (default) |
+| `true` | Kept off every surface: menus, breadcrumbs, page lists and the feed |
+| `"menu"` | Kept out of menus only |
+| `"breadcrumb"` | Kept out of breadcrumbs only |
+| `"list"` | Kept out of page lists only |
+| `"feed"` | Left out of the RSS feed only |
+| `[ "menu", "feed" ]` | Kept off exactly the surfaces named |
+
+```yaml
+---
+hide: menu
+---
 ```
 
-The `controls` and `playsinline` attributes are always present. `autoplay`, `loop`,
-`muted`, and `poster` are only emitted when the corresponding argument is set.
+Hiding from menus rules over any choice in `menus`.
 
-#### Background mode (`overlay`)
+#### Choosing named menus via front matter
 
-With the `overlay` flag the video becomes a background and the block's body content
-is layered on top of it — the classic hero pattern. The video is chrome-free by
-default (add `controls` to bring the native controls back), and a typical hero
-combines `overlay` with `autoplay` + `loop` (both imply/allow `muted`):
+Without `menu`, the component lists only pages that leave `menus` out or choose
+`auto` among others. A page choosing named menus only appears in those:
 
-```markdown
-::: video src=./hero.mp4 poster=./hero.jpg overlay autoplay loop
-# Welcome
-Content rendered on top of the looping background video.
-:::
+```yaml
+---
+menus: footer            # in the footer, not in the page tree's menus
+---
 ```
 
-```html
-<div class="scavold-video scavold-video--overlay">
-  <video class="scavold-video__media" src="..." poster="..." autoplay loop muted
-         preload="metadata" playsinline></video>
-  <div class="scavold-video__overlay">
-    <!-- slot content -->
-  </div>
-</div>
-```
+#### Examples
 
-The component only ships **functional** layout CSS (the video and the content share
-one CSS-grid cell, so the content defines the block height and the video covers the
-area behind it via `object-fit: cover`). All visual styling — a darkening scrim,
-text colour, alignment, a `min-height` for the hero — belongs to the consuming theme,
-which can hook onto the `.scavold-video`, `.scavold-video__media`, and
-`.scavold-video__overlay` classes:
+```html
+<!-- top-level pages — typical site header nav -->
+<ScavoldMenu :from-root="1" />
 
-```css
-/* theme CSS */
-.scavold-video--overlay { min-height: 60vh; }
-.scavold-video__overlay {
-  display: grid;
-  place-content: center;
-  padding: 2rem;
-  color: white;
-  background: rgba( 0, 0, 0, 0.4 ); /* scrim for legibility */
-}
-```
+<!-- second level of the active top-level section only -->
+<ScavoldMenu :from-root="2" active-only />
 
-Without the `overlay` flag the block behaves exactly as before: a plain inline
-player whose body content is only fallback text for browsers that cannot play video.
+<!-- children of the current page -->
+<ScavoldMenu :from="1" />
 
-#### Captions and accessibility
+<!-- siblings of the current page -->
+<ScavoldMenu />
 
-WCAG requires captions for prerecorded video with audio. Add a `<track>` element via
-the slot:
+<!-- full site hierarchy as a sitemap -->
+<ScavoldMenu :from-root="1" :depth="-1" />
 
-```markdown
-::: video src=./clip.mp4
-<track kind="captions" src="./clip.vtt" srclang="de" label="Deutsch" default />
-:::
-```
+<!-- two levels starting from the active top-level section, active branch expanded -->
+<ScavoldMenu :from-root="1" :depth="1" active-only />
 
-The `label` argument provides an `aria-label` on the `<video>` element for cases where
-the surrounding page context does not already describe the video.
+<!-- fixed path — same footer nav regardless of locale -->
+<ScavoldMenu from-path="de/footer" label="Footer-Navigation" />
 
-#### Replacing with a custom component
+<!-- locale-aware via primary language tag — works when paths use "de", "en", etc. -->
+<ScavoldMenu from-path="{lang}/footer" label="Footer-Navigation" />
 
-Register a component under the name `ScavoldVideo` before calling `scavoldEnhanceApp`,
-or map the `video` container name to your component in `augmentConfig`:
+<!-- locale-aware via full BCP 47 tag — use when paths include region codes like "de-CH" -->
+<ScavoldMenu from-path="{locale}/footer" label="Footer-Navigation" />
 
-```js
-export default defineConfig( await augmentConfig( config, {
-    containers: { video: "MyVideoPlayer" },
-} ) );
+<!-- named menu: the pages choosing "footer", wherever they sit, within the current language -->
+<ScavoldMenu menu="footer" from-path="{lang}" label="Footer-Navigation" />
 ```
 
-Custom components can reuse the resolution logic via `useVideo` and `videoProps`:
+---
 
-```js
-import { useVideo, videoProps } from "./scavold/composables/useVideo.js";
+### `<ScavoldMenuItems>`
 
-const props = defineProps( { ...videoProps } );
-const { src, poster, autoplay, loop, muted, preload, overlay, controls } = useVideo( props );
-```
+Internal recursive component used by `<ScavoldMenu>` to render `<ul>/<li>` trees.
+Not intended for direct use. Documented here for theme developers who want to build
+their own menu component using `useHierarchy`.
 
 ---
 
@@ -598,90 +707,277 @@ them discoverable.
 
 ---
 
-### `<ScavoldImage>`
+### `<ScavoldVideo>`
 
-Renders a responsive `<picture>` element for local images. Not intended for direct
-use in templates — it is emitted automatically by the Markdown image renderer when a
-local image path is encountered. Custom components that need to display a media-file
-frontmatter field can use it directly.
+Renders a video player in the text column for a video embedded via the `:::video`
+container block — a clip visitors watch and listen to, pause and wind back. Nothing is
+rendered when no `src` argument is provided. For a video across the whole window,
+with content laid on top, use [`<ScavoldCover>`](#scavoldcover).
 
-#### Props
+#### Markdown syntax
 
-| Prop | Type | Default | Description |
+```markdown
+::: video src=./clip.mp4 poster=./thumb.jpg
+Optional caption or fallback text for browsers that do not support the video element.
+:::
+```
+
+#### Arguments
+
+| Argument | Type | Default | Description |
 |---|---|---|---|
-| `src` | `string` | required | URL of the largest fallback image variant |
-| `srcset` | `string` | `""` | `srcset` string for the original format (JPEG/PNG) |
-| `webp-srcset` | `string` | `""` | `srcset` string for the WebP variants |
-| `sizes` | `string` | `"100vw"` | CSS `sizes` attribute applied to all sources |
-| `alt` | `string` | `""` | Alt text for the `<img>` element |
+| `src` | `string` | required | URL of the video file |
+| `poster` | `string` | — | URL of the poster image shown before playback |
+| `autoplay` | flag | — | Play automatically while on screen, unless the visitor asks for reduced motion. Forces `muted` (browser requirement) |
+| `loop` | flag | — | Loop the video when it ends |
+| `muted` | flag | — | Mute the audio track |
+| `preload` | `"none" \| "metadata" \| "auto"` | `"metadata"` | Browser preload hint |
+| `label` | `string` | — | Accessible label (`aria-label`) announced by screen readers. Use when the surrounding context does not already describe the video. |
+
+Boolean flags are written without a value:
+
+```markdown
+::: video src=./clip.mp4 autoplay loop
+:::
+```
 
 #### Rendered markup
 
 ```html
-<picture>
-  <source type="image/webp" srcset="..." sizes="..." />
-  <source srcset="..." sizes="..." />
-  <img src="..." alt="..." sizes="..." loading="lazy" decoding="async" />
-</picture>
+<video class="scavold-video" src="..." poster="..." preload="metadata" controls playsinline>
+  <!-- slot content -->
+</video>
+```
+
+The `controls` and `playsinline` attributes are always present: every video can be
+paused, which WCAG 2.2.2 asks of anything moving for longer than five seconds. `loop`,
+`muted` and `poster` are only emitted when the corresponding argument is set.
+
+`autoplay` is not emitted: the attribute starts a video before hydration, wherever it
+is on the page, and before anyone could ask whether the visitor wants reduced motion.
+The video is started by script instead. A visitor whose system asks for reduced motion
+finds it paused, with the controls to start it. For everyone else it plays while at
+least half of it is on screen — half of the window, for one higher than the window —
+and pauses when scrolled away. A video the visitor paused stays paused until they
+start it again, and one they turned the sound up on keeps playing when scrolled away.
+
+#### Captions and accessibility
+
+WCAG requires captions for prerecorded video with audio. Add a `<track>` element via
+the slot:
+
+```markdown
+::: video src=./clip.mp4
+<track kind="captions" src="./clip.vtt" srclang="de" label="Deutsch" default />
+:::
+```
+
+The `label` argument provides an `aria-label` on the `<video>` element for cases where
+the surrounding page context does not already describe the video.
+
+#### Replacing with a custom component
+
+Register a component under the name `ScavoldVideo` before calling `scavoldEnhanceApp`,
+or map the `video` container name to your component in `augmentConfig`:
+
+```js
+export default defineConfig( await augmentConfig( config, {
+    containers: { video: "MyVideoPlayer" },
+} ) );
+```
+
+Custom components can reuse the resolution logic via `useVideo` and `videoProps`:
+
+```js
+import { useVideo, videoProps } from "./scavold/composables/useVideo.js";
+
+const props = defineProps( { ...videoProps } );
+const { src, poster, autoplay, loop, muted, preload, ariaLabel } = useVideo( props );
+```
+
+---
+
+### Sectioning wrappers
+
+`<ScavoldArticle>`, `<ScavoldAside>`, `<ScavoldFooter>`, `<ScavoldHeader>`, `<ScavoldMain>`,
+`<ScavoldNav>`, `<ScavoldSection>`
+
+Thin wrapper components for the seven HTML sectioning elements. Each renders its
+corresponding element, forwarding `class` and `data-*` attributes from the container
+arguments.
+
+These are the default targets for their respective container names. A theme developer
+can replace any of them by registering a component with the same name before calling
+`scavoldEnhanceApp`, or by passing an explicit override to `augmentConfig`:
+
+```js
+// .vitepress/config.js
+export default defineConfig( await augmentConfig( config, {
+    containers: {
+        section: "MySiteSection",
+    }
+} ) );
+```
+
+```js
+// .vitepress/theme/index.js
+async function enhanceApp( context ) {
+    app.component( "ScavoldSection", MySiteSection ); // registered before scavold
+    await scavoldEnhanceApp( context );
+}
+```
+
+---
+
+## Composables
+
+---
+
+### `formatTimestamp( timestamp, options )`
+
+```js
+import { formatTimestamp } from "scavold/lib/dateFormat.js";
+```
+
+Renders a timestamp the way page lists do, for a theme's own components — a byline
+under a post's title, for instance. Free of Vue and VitePress, so build-time code can
+use it too.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `locale` | `string` | the runtime's | Locale to phrase the result in |
+| `dateStyle` | `"short" \| "medium" \| "long" \| "full" \| "iso"` | `"long"` | Style of the date; `iso` writes `2020-10-20` in every language |
+| `timeStyle` | same values | — | Style of the time of day; omitted, only the date is rendered |
+| `timeZone` | `string` | `"UTC"` | IANA name of the zone the timestamp is read in |
+
+The result depends on the arguments alone, never on the machine it runs on, so
+pre-rendered markup and the browser agree — a timestamp that changes on hydration
+would tear the markup apart. A timestamp that cannot be read renders as an empty
+string rather than as `Invalid Date`.
+
+---
+
+### `useAutoplay( videoRef, enabled )`
+
+```js
+import { useAutoplay } from "scavold/composables/useAutoplay.js";
+```
+
+The autoplay behaviour of `<ScavoldVideo>` and `<ScavoldCover>`, for a site's own
+video component: plays the video muted while at least half of it is on screen, pauses
+it when scrolled away, leaves it alone once the visitor paused it or turned the sound
+up, and does nothing for visitors who ask for reduced motion.
+
+```js
+const video = ref( null );          // template ref of the <video>
+useAutoplay( video, () => autoplay.value );
+```
+
+Leave the `autoplay` attribute off the element; it would start the video regardless.
+
+---
+
+### `useContainer( props )`
+
+```js
+import { useContainer, containerProps } from "./scavold/composables/useContainer.js";
+```
+
+Shared composable for custom container components. Parses the props emitted by the
+Markdown container renderer and exposes derived values ready for template binding.
+
+#### Usage
+
+```vue
+<script setup>
+import { useContainer, containerProps } from "./scavold/composables/useContainer.js";
+
+const props = defineProps( {
+    ...containerProps,
+    background: String, // custom KV argument: background=/media/hero.jpg
+} );
+
+const { containerName, classes, dataAttrs } = useContainer( props );
+</script>
+
+<template>
+  <section
+    :class="[containerName, classes]"
+    :style="background ? `--bg: url(${background})` : ''"
+    v-bind="dataAttrs"
+  >
+    <slot />
+  </section>
+</template>
 ```
 
----
+#### `containerProps`
 
-### `<ScavoldContainer>`
+The shared props definition every container component must declare. Spread it into
+`defineProps` to avoid duplicating the base prop declarations.
 
-Fallback component for Markdown container blocks whose name has no dedicated
-registered component. Renders as the matching HTML sectioning element if the
-container name is one (`section`, `aside`, etc.), otherwise as a `<div>`.
+| Prop | Type | Description |
+|---|---|---|
+| `class` | `string` | Space-separated boolean flags from the container opening line |
+| `data-container` | `string` | The container name as written in Markdown |
 
-Any container name works without being declared first — undeclared names are caught
-by this component. Because a typo would otherwise become a silent `<div>`, the build
-reports each undeclared name once:
+All `key=value` pairs from the opening line are passed as additional props with a
+`data-` prefix (e.g. `background=/img.jpg` → prop `data-background`). Declare them
+explicitly in `defineProps` to use them.
 
-```
-[scavold] container ':::sectoin' is not declared in .cratly.config.yaml — rendering
-it with ScavoldContainer. Declare it to silence this, or fix the name if it is a typo.
-```
+Flags arrive **both ways**: as part of `class` and as an empty `data-<flag>` prop, so
+a boolean container parameter can be declared as a prop (this is how `useVideo` reads
+`autoplay` and `loop`) while purely presentational flags keep working as
+class names. A flag a component does not declare falls through into the markup as an
+empty attribute — `::: section highlight` renders `<section class="highlight"
+data-highlight>`.
 
-Declaring the container in `.cratly.config.yaml` silences the report and gives it
-typed properties in the cratly editor.
+A container that opens the page — its fence is the first thing in the page body —
+additionally receives an empty `data-leading` attribute. It is information only and
+changes nothing by itself; a component or a stylesheet can tell from it that this
+block stands at the very top. The same fact reaches the layout ahead of the content as
+`page.leadingContainer` (see [A cover opening the page](#a-cover-opening-the-page)).
 
-Not intended for direct use. Theme developers should instead create a dedicated
-component for each container name they declare in `.cratly.config.yaml`.
+#### Returns
 
-See `useContainer` below for building custom container components.
+| Name | Type | Description |
+|---|---|---|
+| `containerName` | `ComputedRef<string>` | The container name (value of `data-container`) |
+| `rootTag` | `ComputedRef<string>` | `containerName` if it is a sectioning element, otherwise `"div"` |
+| `classes` | `ComputedRef<string>` | The `class` prop value |
+| `dataAttrs` | `ComputedRef<object>` | All `data-*` props as a plain object, suitable for `v-bind` |
 
----
+#### Markdown syntax reminder
 
-### `<ScavoldSection>`, `<ScavoldAside>`, `<ScavoldArticle>`, `<ScavoldHeader>`, `<ScavoldFooter>`, `<ScavoldNav>`, `<ScavoldMain>`
+```markdown
+::: hero dark centered background=/media/hero.jpg
+Content here.
+:::
+```
 
-Thin wrapper components for the seven HTML sectioning elements. Each renders its
-corresponding element, forwarding `class` and `data-*` attributes from the container
-arguments.
+This emits `class="dark centered"`, `data-container="hero"`, and
+`data-background="/media/hero.jpg"` onto the component.
 
-These are the default targets for their respective container names. A theme developer
-can replace any of them by registering a component with the same name before calling
-`scavoldEnhanceApp`, or by passing an explicit override to `augmentConfig`:
+---
+
+### `useCover( props )`
 
 ```js
-// .vitepress/config.js
-export default defineConfig( await augmentConfig( config, {
-    containers: {
-        section: "MySiteSection",
-    }
-} ) );
+import { useCover, coverProps } from "scavold/composables/useCover.js";
 ```
 
+Resolves the arguments of a `:::cover` block for a site's own cover component, so it
+renders the same picture the way its design asks:
+
 ```js
-// .vitepress/theme/index.js
-async function enhanceApp( context ) {
-    app.component( "ScavoldSection", MySiteSection ); // registered before scavold
-    await scavoldEnhanceApp( context );
-}
+const props = defineProps( { ...coverProps } );
+const { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone } = useCover( props );
 ```
 
----
-
-## Composables
+`srcset`, `webpSrcset` and `sizes` are filled for an image only; the build provides
+the variants and the dimensions `sizes` is derived from. `tone` is `"light"`, `"dark"`
+or empty, one of `COVER_TONES`. `isVideoUrl( url )` and `coverSizes( width, height )`
+are exported as well.
 
 ---
 
@@ -767,46 +1063,6 @@ const items = computed( () =>
 
 ---
 
-### `useVideo( props )`
-
-```js
-import { useVideo, videoProps } from "./scavold/composables/useVideo.js";
-```
-
-Composable for custom video components. Resolves the `:::video` container props into
-clean, typed values ready for template binding. `autoplay` automatically forces `muted`
-to satisfy browser autoplay policies.
-
-#### `videoProps`
-
-Spread into `defineProps` to declare all video-related props at once.
-
-| Prop | Argument | Description |
-|---|---|---|
-| `dataSrc` | `src=…` | Video file URL |
-| `dataPoster` | `poster=…` | Poster image URL |
-| `dataAutoplay` | `autoplay` | Present when the `autoplay` flag is set |
-| `dataLoop` | `loop` | Present when the `loop` flag is set |
-| `dataMuted` | `muted` | Present when the `muted` flag is set |
-| `dataOverlay` | `overlay` | Present when the `overlay` flag is set (background mode) |
-| `dataControls` | `controls` | Present when the `controls` flag is set |
-| `dataPreload` | `preload=…` | One of `"none"`, `"metadata"`, `"auto"` |
-
-#### Returns
-
-| Name | Type | Description |
-|---|---|---|
-| `src` | `ComputedRef<string>` | Video URL |
-| `poster` | `ComputedRef<string>` | Poster URL, empty string if absent |
-| `autoplay` | `ComputedRef<boolean>` | `true` when `autoplay` flag is set |
-| `loop` | `ComputedRef<boolean>` | `true` when `loop` flag is set |
-| `muted` | `ComputedRef<boolean>` | `true` when `muted` flag is set or `autoplay` is true |
-| `overlay` | `ComputedRef<boolean>` | `true` when the `overlay` flag is set (render as background) |
-| `controls` | `ComputedRef<boolean>` | `true` in the default player; in overlay mode only when the `controls` flag is set |
-| `preload` | `ComputedRef<string>` | Resolved preload value, defaults to `"metadata"` |
-
----
-
 ### `usePageList( props )`
 
 ```js
@@ -878,107 +1134,6 @@ argument arrives as `data…`, in the same way as `videoProps`: `dataFrom` for `
 
 ---
 
-### `formatTimestamp( timestamp, options )`
-
-```js
-import { formatTimestamp } from "scavold/lib/dateFormat.js";
-```
-
-Renders a timestamp the way page lists do, for a theme's own components — a byline
-under a post's title, for instance. Free of Vue and VitePress, so build-time code can
-use it too.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `locale` | `string` | the runtime's | Locale to phrase the result in |
-| `dateStyle` | `"short" \| "medium" \| "long" \| "full" \| "iso"` | `"long"` | Style of the date; `iso` writes `2020-10-20` in every language |
-| `timeStyle` | same values | — | Style of the time of day; omitted, only the date is rendered |
-| `timeZone` | `string` | `"UTC"` | IANA name of the zone the timestamp is read in |
-
-The result depends on the arguments alone, never on the machine it runs on, so
-pre-rendered markup and the browser agree — a timestamp that changes on hydration
-would tear the markup apart. A timestamp that cannot be read renders as an empty
-string rather than as `Invalid Date`.
-
----
-
-### `useContainer( props )`
-
-```js
-import { useContainer, containerProps } from "./scavold/composables/useContainer.js";
-```
-
-Shared composable for custom container components. Parses the props emitted by the
-Markdown container renderer and exposes derived values ready for template binding.
-
-#### Usage
-
-```vue
-<script setup>
-import { useContainer, containerProps } from "./scavold/composables/useContainer.js";
-
-const props = defineProps( {
-    ...containerProps,
-    background: String, // custom KV argument: background=/media/hero.jpg
-} );
-
-const { containerName, classes, dataAttrs } = useContainer( props );
-</script>
-
-<template>
-  <section
-    :class="[containerName, classes]"
-    :style="background ? `--bg: url(${background})` : ''"
-    v-bind="dataAttrs"
-  >
-    <slot />
-  </section>
-</template>
-```
-
-#### `containerProps`
-
-The shared props definition every container component must declare. Spread it into
-`defineProps` to avoid duplicating the base prop declarations.
-
-| Prop | Type | Description |
-|---|---|---|
-| `class` | `string` | Space-separated boolean flags from the container opening line |
-| `data-container` | `string` | The container name as written in Markdown |
-
-All `key=value` pairs from the opening line are passed as additional props with a
-`data-` prefix (e.g. `background=/img.jpg` → prop `data-background`). Declare them
-explicitly in `defineProps` to use them.
-
-Flags arrive **both ways**: as part of `class` and as an empty `data-<flag>` prop, so
-a boolean container parameter can be declared as a prop (this is how `useVideo` reads
-`overlay`, `autoplay` and `loop`) while purely presentational flags keep working as
-class names. A flag a component does not declare falls through into the markup as an
-empty attribute — `::: section highlight` renders `<section class="highlight"
-data-highlight>`.
-
-#### Returns
-
-| Name | Type | Description |
-|---|---|---|
-| `containerName` | `ComputedRef<string>` | The container name (value of `data-container`) |
-| `rootTag` | `ComputedRef<string>` | `containerName` if it is a sectioning element, otherwise `"div"` |
-| `classes` | `ComputedRef<string>` | The `class` prop value |
-| `dataAttrs` | `ComputedRef<object>` | All `data-*` props as a plain object, suitable for `v-bind` |
-
-#### Markdown syntax reminder
-
-```markdown
-::: hero dark centered background=/media/hero.jpg
-Content here.
-:::
-```
-
-This emits `class="dark centered"`, `data-container="hero"`, and
-`data-background="/media/hero.jpg"` onto the component.
-
----
-
 ### `useRedirect()`
 
 ```js
@@ -1040,6 +1195,8 @@ const label = t("nav.breadcrumb"); // ComputedRef<string>, reactive to locale ch
 | Key | Default (en) | Description |
 |---|---|---|
 | `@scavold.nav.breadcrumb` | `"Breadcrumb"` | `aria-label` on the breadcrumb `<nav>` |
+| `@scavold.cover.play` | `"Play video"` | Label of a cover video's button while the video is paused |
+| `@scavold.cover.pause` | `"Pause video"` | Label of a cover video's button while the video plays |
 
 #### Providing translations in your theme
 
@@ -1079,6 +1236,44 @@ the Scavold default.
 
 ---
 
+### `useVideo( props )`
+
+```js
+import { useVideo, videoProps } from "./scavold/composables/useVideo.js";
+```
+
+Composable for custom video components. Resolves the `:::video` container props into
+clean, typed values ready for template binding. `autoplay` automatically forces `muted`
+to satisfy browser autoplay policies.
+
+#### `videoProps`
+
+Spread into `defineProps` to declare all video-related props at once.
+
+| Prop | Argument | Description |
+|---|---|---|
+| `dataSrc` | `src=…` | Video file URL |
+| `dataPoster` | `poster=…` | Poster image URL |
+| `dataAutoplay` | `autoplay` | Present when the `autoplay` flag is set |
+| `dataLoop` | `loop` | Present when the `loop` flag is set |
+| `dataMuted` | `muted` | Present when the `muted` flag is set |
+| `dataPreload` | `preload=…` | One of `"none"`, `"metadata"`, `"auto"` |
+| `dataLabel` | `label=…` | Accessible label |
+
+#### Returns
+
+| Name | Type | Description |
+|---|---|---|
+| `src` | `ComputedRef<string>` | Video URL |
+| `poster` | `ComputedRef<string>` | Poster URL, empty string if absent |
+| `autoplay` | `ComputedRef<boolean>` | `true` when `autoplay` flag is set |
+| `loop` | `ComputedRef<boolean>` | `true` when `loop` flag is set |
+| `muted` | `ComputedRef<boolean>` | `true` when `muted` flag is set or `autoplay` is true |
+| `preload` | `ComputedRef<string>` | Resolved preload value, defaults to `"metadata"` |
+| `ariaLabel` | `ComputedRef<string \| undefined>` | Accessible label, `undefined` when the author set none |
+
+---
+
 ## Design patterns
 
 ---
@@ -1107,6 +1302,12 @@ their context and pass it through to `<ScavoldImage>`:
 
 Content authors pick the component (`HeroImage`, `ThumbImage`, etc.) that matches
 their intent. The `sizes` value is baked into the component and invisible to them.
+The built-in [`<ScavoldCover>`](#scavoldcover) works this way.
+
+A container argument declared as `media-file` that names an image reaches the
+component with everything it needs for this: besides its URL, as `data-<arg>`, the
+build adds `data-<arg>-srcset`, `data-<arg>-webp-srcset`, `data-<arg>-width` and
+`data-<arg>-height` — the variants and the upright dimensions of the source.
 
 **Why not measure at runtime?** A `ResizeObserver`-based approach that reads the
 container's pixel size and sets `src` dynamically is accurate but has serious
@@ -1119,4 +1320,3 @@ The global `image_sizes` in `.cratly.config.yaml` is a fallback for images that
 no layout-aware component wrapping them. Set it to the most common case in the
 theme (typically the prose column width) and override via dedicated components for
 everything else.
-