scavold 0.2.0-rc.1

package/COMPONENTS.md

@@ -0,0 +1,862 @@
+# Scavold component and composable reference
+
+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.
+
+TypeScript-typed props give inline documentation in VS Code (Volar extension) and
+JetBrains IDEs — hover a prop in a template to see its description. This file covers
+the broader "when and why" context that hover docs cannot convey.
+
+---
+
+## Components
+
+---
+
+### `<ScavoldMenu>`
+
+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.
+
+#### 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"`). |
+
+#### 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>
+```
+
+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.
+
+#### Label resolution
+
+Item labels are resolved in this order:
+
+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
+
+#### Hiding pages via front matter
+
+A page can opt out of appearing in menus by setting `hide` in its front matter:
+
+| Value | Effect |
+|---|---|
+| `false` / absent | Visible everywhere (default) |
+| `true` | Hidden in menus **and** breadcrumbs |
+| `"menu"` | Hidden in menus only |
+| `"breadcrumb"` | Hidden in breadcrumbs only |
+
+```yaml
+---
+hide: menu
+---
+```
+
+#### Examples
+
+```html
+<!-- top-level pages — typical site header nav -->
+<ScavoldMenu :from-root="1" />
+
+<!-- second level of the active top-level section only -->
+<ScavoldMenu :from-root="2" active-only />
+
+<!-- children of the current page -->
+<ScavoldMenu :from="1" />
+
+<!-- siblings of the current page -->
+<ScavoldMenu />
+
+<!-- full site hierarchy as a sitemap -->
+<ScavoldMenu :from-root="1" :depth="-1" />
+
+<!-- two levels starting from the active top-level section, active branch expanded -->
+<ScavoldMenu :from-root="1" :depth="1" active-only />
+
+<!-- fixed path — same footer nav regardless of locale -->
+<ScavoldMenu from-path="de/footer" label="Footer-Navigation" />
+
+<!-- locale-aware via primary language tag — works when paths use "de", "en", etc. -->
+<ScavoldMenu from-path="{lang}/footer" label="Footer-Navigation" />
+
+<!-- locale-aware via full BCP 47 tag — use when paths include region codes like "de-CH" -->
+<ScavoldMenu from-path="{locale}/footer" label="Footer-Navigation" />
+```
+
+---
+
+### `<ScavoldBreadcrumb>`
+
+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.
+
+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 |
+|---|---|---|---|
+| `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
+<!-- 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>
+```
+
+#### Examples
+
+```html
+<!-- typical usage — section trail + current page -->
+<ScavoldBreadcrumb />
+
+<!-- trail without current page, e.g. when page heading serves as final crumb -->
+<ScavoldBreadcrumb :include-current="false" />
+
+<!-- full trail including home link -->
+<ScavoldBreadcrumb include-root />
+```
+
+---
+
+### `<ScavoldLocaleMenu>`
+
+Renders a `<nav class="locale-nav">` element containing a list of links to the
+available translations of the current page. Nothing is rendered when the resolved
+link set is empty, or (by default) when only a single locale is available.
+
+The component has three locale detection modes covering common multi-language
+site patterns without requiring knowledge of the site structure from the author.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `detection` | `"auto" \| "explicit" \| "inherited" \| "global"` | `"auto"` | How to discover available locales. See Detection modes below. |
+| `include-current` | `boolean` | `false` | Include the current locale as a non-navigating item in the list. Useful when the switcher always shows the full set. |
+| `hide-if-single` | `boolean` | `true` | Render nothing when only one (or zero) locale links are available after filtering. |
+| `label` | `string` | `"Language"` (i18n) | Accessible label for the `<nav>` landmark (`aria-label`). |
+
+#### Detection modes
+
+| Mode | Description |
+|---|---|
+| `"auto"` | Tries `explicit`, then `inherited`, then `global`; uses the first mode that yields at least one link. Good default for sites with mixed translation coverage. |
+| `"explicit"` | Only locales declared in the **current page's own** `translations` frontmatter. Nothing is shown for pages that have no `translations` entry. |
+| `"inherited"` | For each locale, follows the ancestor chain upward and links to the translation declared by the **nearest ancestor** (including the current page) that has a `translations` entry for that locale. A section `index.md` can therefore declare `translations` once and cover all its descendants that have no direct counterpart in the other locale — the switcher will link to the section rather than showing nothing. |
+| `"global"` | Every locale present **anywhere in the hierarchy**. Link goes to the topmost page of that locale regardless of `translations` declarations. Use when no per-page `translations` are maintained at all. |
+
+#### Rendered markup
+
+```html
+<nav class="locale-nav" aria-label="Language">
+  <ul>
+    <li lang="de">
+      <span aria-current="true">de</span>   <!-- current locale: span not link -->
+    </li>
+    <li lang="en">
+      <a href="/en/" hreflang="en" aria-label="en">en</a>
+    </li>
+  </ul>
+</nav>
+```
+
+The `.current` class is set on the `<li>` of the current locale. The current locale
+renders as a `<span>` rather than an `<a>` since navigating to the current page makes
+no sense.
+
+#### `translations` frontmatter
+
+Detection modes `"explicit"` and `"inherited"` rely on a `translations` map in page
+front matter:
+
+```yaml
+---
+locale: de
+translations:
+  en: en/about_us.md
+---
+```
+
+Paths are relative to `pages_folder`.
+
+For `"inherited"` mode the common pattern is to declare `translations` on a section
+`index.md` rather than on every individual page. Pages in that section that have no
+own `translations` entry will fall back to the section link:
+
+```
+pages/
+  de/
+    products/
+      index.md      ← declares translations: { en: en/products/index.md }
+      widget-a.md   ← no translations — inherited mode links to en/products/
+      widget-b.md   ← no translations — inherited mode links to en/products/
+      widget-c.md   ← own translations: { en: en/products/widget-c.md } — links directly
+  en/
+    products/
+      index.md
+      widget-c.md   ← only widget-c has an English counterpart
+```
+
+#### Examples
+
+```html
+<!-- simplest: show other locales declared on this page or any ancestor -->
+<ScavoldLocaleMenu />
+
+<!-- always show all locales; link to topmost page in each locale -->
+<ScavoldLocaleMenu detection="global" />
+
+<!-- show all including current locale -->
+<ScavoldLocaleMenu detection="global" include-current />
+
+<!-- explicit only; keep visible even when only one locale is listed -->
+<ScavoldLocaleMenu detection="explicit" :hide-if-single="false" />
+```
+
+---
+
+### `<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.
+
+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:
+
+```yaml
+---
+redirect:
+  de: /de/
+  en: /en/
+  "*": /en/
+---
+```
+
+On mount the component walks `navigator.languages` in order, trying an exact match
+then a language-prefix match against the redirect map keys, and calls
+`location.replace()` on the first hit. This replaces the redirect page in history
+so the back button never loops back to it.
+
+A `<noscript>` `<meta http-equiv="refresh">` fallback targets the `"*"` catch-all
+for browsers without JavaScript.
+
+The component renders no visible content of its own. It is used automatically by
+`<ScavoldLayout>` and is not normally placed directly in templates.
+
+---
+
+### `<ScavoldMenuItems>`
+
+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`.
+
+---
+
+### `<ScavoldVideo>`
+
+Renders a `<video>` element for a video embedded via the `:::video` container block.
+Nothing is rendered when no `src` argument is provided.
+
+#### Markdown syntax
+
+```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 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. |
+
+Boolean flags are written without a value:
+
+```markdown
+::: video src=./clip.mp4 autoplay loop
+:::
+```
+
+#### Rendered markup
+
+```html
+<video src="..." poster="..." preload="metadata" controls playsinline>
+  <!-- slot content -->
+</video>
+```
+
+The `controls` and `playsinline` attributes are always present. `autoplay`, `loop`,
+`muted`, and `poster` are only emitted when the corresponding argument is set.
+
+#### Background mode (`overlay`)
+
+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`):
+
+```markdown
+::: video src=./hero.mp4 poster=./hero.jpg overlay autoplay loop
+# Welcome
+Content rendered on top of the looping background video.
+:::
+```
+
+```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>
+```
+
+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:
+
+```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 */
+}
+```
+
+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.
+
+#### 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, overlay, controls } = useVideo( props );
+```
+
+---
+
+### `<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 |
+|---|---|---|---|
+| `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 |
+
+#### Rendered markup
+
+```html
+<picture>
+  <source type="image/webp" srcset="..." sizes="..." />
+  <source srcset="..." sizes="..." />
+  <img src="..." alt="..." sizes="..." loading="lazy" decoding="async" />
+</picture>
+```
+
+---
+
+### `<ScavoldContainer>`
+
+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>`.
+
+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` below for building custom container components.
+
+---
+
+### `<ScavoldSection>`, `<ScavoldAside>`, `<ScavoldArticle>`, `<ScavoldHeader>`, `<ScavoldFooter>`, `<ScavoldNav>`, `<ScavoldMain>`
+
+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
+
+---
+
+### `useHierarchy()`
+
+```js
+import { useHierarchy } from "./scavold/composables/hierarchy";
+```
+
+Provides access to the full page hierarchy tree and utilities for traversing it.
+Must be called inside a component's `setup` function (or `<script setup>`).
+
+#### Returns
+
+| Name | Type | Description |
+|---|---|---|
+| `hierarchy` | `ComputedRef<HierarchyNode>` | Root node of the full page hierarchy tree |
+| `current` | `ComputedRef<HierarchyNode \| undefined>` | Node for the currently viewed page |
+| `ancestorAtDepth` | `(node, targetDepth) => HierarchyNode \| undefined` | Returns the ancestor of `node` at `targetDepth` levels below root. Used by `ScavoldMenu` for `from-root` mode. Returns `undefined` if `node` is not deep enough. |
+| `isOnActivePath` | `(node) => boolean` | Returns `true` if `node` is the current page or one of its ancestors |
+| `collectItems` | `(parent, depth, activeOnly, expand) => MenuItem[]` | Recursively collects menu items from `parent`'s children. Used internally by `ScavoldMenu`. |
+| `collectAncestors` | `(includeCurrent, includeRoot) => MenuItem[]` | Returns the ancestor chain from root to the current page as a flat `MenuItem` array. Used internally by `ScavoldBreadcrumb`. |
+| `currentLocale` | `ComputedRef<string>` | The resolved locale for the current page. Falls back to the browser locale when no page or ancestor declares one. |
+| `collectLocaleLinks` | `(detection, includeCurrent?) => LocaleLink[]` | Returns available locale links for the current page. See `ScavoldLocaleMenu` for detection mode details. |
+| `resolveByPath` | `(rawPath: string) => HierarchyNode \| undefined` | Resolves a path string to a hierarchy node. Supports `{locale}` (full BCP 47 tag) and `{lang}` (primary language subtag) placeholders. Tries the interpolated path as-is, then with `/index.md`, then with `.md` appended. |
+
+#### `HierarchyNode` properties
+
+| Property | Type | Description |
+|---|---|---|
+| `path` | `string` | Relative path of the Markdown source file |
+| `isPage` | `boolean` | `true` for actual pages, `false` for intermediate folder nodes |
+| `frontmatter` | `object` | Parsed front matter data |
+| `frontmatter.hide` | `boolean \| "menu" \| "breadcrumb"` | Excludes this node from menus, breadcrumbs, or both. See [Hiding pages via front matter](#hiding-pages-via-front-matter). |
+| `frontmatter.order` | `number?` | Sort position among siblings. Pages with a lower value appear first; pages without `order` follow in filename order. |
+| `frontmatter.url` | `string?` | Alias output path. When set, VitePress builds the page at this URL instead of the path derived from the source file. Conflicts (two pages with the same alias) are a build error. |
+| `title` | `string?` | Display title — from frontmatter `title` or the first `#` heading |
+| `label` | `string?` | Navigation label — from frontmatter `label`; falls back to `title` in menus |
+| `url` | `string?` | Normalised alias output path (e.g. `de/impressum.md`) when `frontmatter.url` is set. Used by `nodeHref` as the page's href. |
+| `locale` | `string?` | Resolved locale (BCP 47), inherited from ancestors |
+| `parent` | `HierarchyNode?` | Parent node — non-enumerable, not serialised to JSON |
+| `subs` | `object?` | Child nodes keyed by path segment, sorted by `order` then filename |
+
+#### `MenuItem` properties
+
+| Property | Type | Description |
+|---|---|---|
+| `node` | `HierarchyNode` | The hierarchy node this item represents |
+| `active` | `boolean` | `true` if this node is the current page or an ancestor of it |
+| `current` | `boolean` | `true` if this node is exactly the current page |
+| `children` | `MenuItem[]` | Nested items, populated according to `depth` / `activeOnly` / `expand` |
+
+#### `LocaleLink` properties
+
+| Property | Type | Description |
+|---|---|---|
+| `locale` | `string` | BCP 47 locale code |
+| `href` | `string` | Root-relative URL for this locale |
+| `current` | `boolean` | `true` if this locale matches the current page's locale |
+
+#### Example — custom menu component
+
+```vue
+<script setup>
+import { useHierarchy } from "./scavold/composables/hierarchy";
+
+const { current, collectItems } = useHierarchy();
+
+// Children of current page, unlimited depth, active branch expanded
+const items = computed( () =>
+    collectItems( current.value, -1, true, false )
+);
+</script>
+```
+
+---
+
+### `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"` |
+
+---
+
+### `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.
+
+#### 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
+import { useRedirect } from "./scavold/composables/useRedirect.js";
+```
+
+Provides redirect-related state derived from the current page's front matter.
+Use this when building a custom layout that needs to handle locale-conditional
+redirects without wrapping in `<ScavoldLayout>`.
+
+#### Returns
+
+| Name | Type | Description |
+|---|---|---|
+| `isLocaleRedirect` | `ComputedRef<boolean>` | `true` when the current page's `redirect` front matter is an object (locale-conditional redirect), `false` otherwise |
+
+#### Example
+
+```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="my-layout"><!-- … --></div>
+</template>
+```
+
+---
+
+### `useScavoldI18n()` / `registerScavoldI18n()`
+
+```js
+import { useScavoldI18n } from "./scavold/composables/useI18n.js";
+```
+
+Scavold uses [@cepharum/vue3-i18n](https://www.npmjs.com/package/@cepharum/vue3-i18n) for all
+framework-owned UI strings (e.g. the breadcrumb `aria-label`). Translations live in
+the `@scavold` namespace so they never collide with a consuming theme's own keys.
+
+`registerScavoldI18n()` is called automatically by `scavoldEnhanceApp` — theme
+developers do not need to call it manually.
+
+#### `useScavoldI18n()` — for custom Scavold components
+
+Returns a `t()` helper that looks up keys in the `@scavold` namespace:
+
+```js
+const { t } = useScavoldI18n();
+const label = t("nav.breadcrumb"); // ComputedRef<string>, reactive to locale changes
+```
+
+#### Built-in translation keys
+
+| Key | Default (en) | Description |
+|---|---|---|
+| `@scavold.nav.breadcrumb` | `"Breadcrumb"` | `aria-label` on the breadcrumb `<nav>` |
+
+#### Providing translations in your theme
+
+Call `useL10n().setLoader()` in your `enhanceApp` as usual. To override a Scavold
+key, include it under `@scavold.*` in your translation files:
+
+```js
+// .vitepress/theme/index.js
+import { useL10n } from "@cepharum/vue3-i18n";
+
+async function enhanceApp( context ) {
+    await scavoldEnhanceApp( context );
+
+    useL10n().setLoader( locale =>
+        import( `./l10n/${locale}.json` )
+    );
+}
+```
+
+```json
+// .vitepress/theme/l10n/de.json
+{
+    "@scavold": {
+        "nav": {
+            "breadcrumb": "Seitennavigation"
+        }
+    },
+    "MY_APP": {
+        "title": "Willkommen"
+    }
+}
+```
+
+The default loader runs last and wins over the `@scavold` namespace loader, so any
+key placed under `@scavold` in the theme's own translation file silently overrides
+the Scavold default.
+
+---
+
+## Design patterns
+
+---
+
+### Responsive images — let components own `sizes`, not content authors
+
+The `sizes` attribute on `<ScavoldImage>` (and the global `image_sizes` default in
+`.cratly.config.yaml`) is a **design concern**, not a content concern. It describes
+how large an image is rendered in a specific layout context — something only the
+theme developer knows. Content authors should never need to set or even see it.
+
+**Do not** rely on the global `image_sizes` default to cover all cases. A value
+tuned for prose (e.g. `(min-width: 40rem) 560px, calc(100vw - 3rem)`) will cause
+the browser to fetch undersized variants for full-width hero images, and vice versa.
+
+**Do** build layout-aware wrapper components that hardcode the correct `sizes` for
+their context and pass it through to `<ScavoldImage>`:
+
+```vue
+<!-- HeroImage.vue — always full-width -->
+<ScavoldImage :src="src" :srcset="srcset" sizes="100vw" />
+
+<!-- ThumbImage.vue — fixed grid cell -->
+<ScavoldImage :src="src" :srcset="srcset" sizes="(min-width: 60rem) 320px, 50vw" />
+```
+
+Content authors pick the component (`HeroImage`, `ThumbImage`, etc.) that matches
+their intent. The `sizes` value is baked into the component and invisible to them.
+
+**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
+downsides: it causes layout shift (no dimensions known during SSR, space cannot be
+reserved), loses browser preload scanning (images load later), and produces a flash
+of empty space on every navigation during hydration. The `sizes` + `srcset` approach
+was specifically designed to avoid all of these.
+
+The global `image_sizes` in `.cratly.config.yaml` is a fallback for images that have
+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.
+