srcdev-nuxt-components 9.1.28 → 9.1.30

package/.claude/settings.json

@@ -36,13 +36,18 @@
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components log --oneline v9.1.22..HEAD)",
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components log --oneline c401cea..HEAD)",
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 3058d63 --stat)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 0f99d7a --stat)"
+      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 0f99d7a --stat)",
+      "Bash(node -e ':*)"
     ],
     "additionalDirectories": [
       "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/content-wrappers/content-width",
       "/Users/simoncornforth/websites/nuxt-components/.claude/skills",
       "/Users/simoncornforth/websites/nuxt-components/app/components/02.molecules/navigation/site-navigation/tests",
-      "/Users/simoncornforth/websites/luxury-locs-by-natasha-nuxt3/app/pages"
+      "/Users/simoncornforth/websites/luxury-locs-by-natasha-nuxt3/app/pages",
+      "/Users/simoncornforth/websites/nuxt-components/app/assets/styles/extends-layer",
+      "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms",
+      "/private/tmp",
+      "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/banner-video"
     ]
   }
 }

package/.claude/settings.local.json

@@ -6,7 +6,8 @@
       "WebFetch(domain:drafts.csswg.org)",
       "Bash(grep '\"\"typescript\"\"' package.json)",
       "Bash(grep '\"\"@vue/language-server\\\\|@volar\\\\|vue-tsc\"\"' package.json)",
-      "Bash(npx nuxi prepare)"
+      "Bash(npx nuxi prepare)",
+      "Bash(ls -la /Users/simoncornforth/websites/luxury-locs-by-natasha-nuxt3/.env*)"
     ]
   }
 }

package/.claude/skills/components/banner-video.md

@@ -0,0 +1,178 @@
+---
+name: BannerVideo
+description: BannerVideo full-width hero video banner — props, depth tier system, verticalPosition/horizontalPosition, reduced-motion fallback, CSS tokens, consumer styling
+type: reference
+---
+
+# BannerVideo
+
+## Overview
+
+`BannerVideo` renders a full-width banner section that plays a muted, looping mp4 video. A poster image is shown as fallback when the user has `prefers-reduced-motion: reduce` set — handled entirely in CSS, no JS.
+
+The banner is sized via `aspect-ratio` so it scales naturally. The `depth` prop selects a responsive `max-height` tier (`xs` → `xl`) implemented with `clamp()` — no breakpoint props needed. Each tier exposes a `--theme-banner-video-max-height-{depth}` CSS token that consuming pages can override.
+
+### Autoplay mechanism
+
+The video uses `autoplay muted loop playsinline preload="auto"` attributes on the `<video>` element with the src in a `<source>` child. A `:key="src"` on the video element forces Vue to remount it on src changes. `@loadeddata` and `@canplay` events call `tryPlay()`, and a `watch(() => props.src, ..., { immediate: true, flush: 'post' })` calls `kickOffLoad()` (which calls `v.load()` then `tryPlay()`) on mount and src change. `onActivated` handles keep-alive re-activation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Path to the mp4 video source. **Required.** |
+| `poster` | `string` | — | Path to the fallback/poster image. **Required.** Used as the video `poster` attribute and as the `prefers-reduced-motion` fallback. |
+| `alt` | `string` | `""` | Alt text for the fallback `NuxtImg`. |
+| `imgWidth` | `number` | `1920` | Intrinsic width of the poster image — required for NuxtImg/IPX optimisation. |
+| `imgHeight` | `number` | `1080` | Intrinsic height of the poster image — required for NuxtImg/IPX optimisation. |
+| `tag` | `"section" \| "div" \| "header" \| "main" \| "article"` | `"section"` | HTML element rendered as the root. |
+| `depth` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Responsive max-height tier. Each maps to a `clamp()` scale; override via `--theme-banner-video-max-height-{depth}`. |
+| `aspectRatio` | `string` | `"21/9"` | CSS `aspect-ratio` of the container (e.g. `"16/9"`, `"21/9"`, `"4/3"`). |
+| `objectFit` | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"cover"` | How the video and fallback image fill the banner frame. |
+| `verticalPosition` | `"start" \| "center" \| "end"` | `"center"` | Vertical crop position. Maps to `align-self` on the video element and `object-position` Y on the fallback image. |
+| `horizontalPosition` | `"start" \| "center" \| "end"` | `"center"` | Horizontal crop position. Maps to `object-position` X on the fallback image. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Basic usage
+
+```vue
+<BannerVideo
+  src="/videos/hero.mp4"
+  poster="/images/hero-poster.jpg"
+  alt="Studio interior"
+/>
+```
+
+## Common variants
+
+### Depth tiers
+
+```vue
+<!-- xs: clamp(12rem, 15vw, 24rem) — thin strip -->
+<BannerVideo src="…" poster="…" depth="xs" />
+
+<!-- sm: clamp(18rem, 22vw, 36rem) -->
+<BannerVideo src="…" poster="…" depth="sm" />
+
+<!-- md (default): clamp(28rem, 38vw, 56rem) -->
+<BannerVideo src="…" poster="…" />
+
+<!-- lg: clamp(40rem, 52vw, 72rem) -->
+<BannerVideo src="…" poster="…" depth="lg" />
+
+<!-- xl: clamp(52rem, 65vw, 90rem) — near full-screen hero -->
+<BannerVideo src="…" poster="…" depth="xl" aspect-ratio="16/9" />
+```
+
+### Custom focal point
+
+```vue
+<BannerVideo
+  src="/videos/hero.mp4"
+  poster="/images/hero-poster.jpg"
+  alt="Studio interior"
+  vertical-position="end"
+  horizontal-position="center"
+/>
+```
+
+### Full bleed with no block margin
+
+```vue
+<BannerVideo
+  src="/videos/hero.mp4"
+  poster="/images/hero-poster.jpg"
+  alt="Studio interior"
+  :style-class-passthrough="['full-bleed', 'mbe-0']"
+/>
+```
+
+## Positioning explained
+
+The video element uses `height: auto; min-height: 100%` so it overflows the container naturally when aspect ratios differ. `overflow: hidden` on the root clips it. `verticalPosition` maps to `align-self` on the video (shifting which portion of the overflow is visible) and to `object-position` Y on the fallback image.
+
+`horizontalPosition` only affects the fallback image via `object-position` X — the video fills full width so horizontal alignment is a no-op on the video element itself.
+
+| verticalPosition | align-self | object-position Y |
+|---|---|---|
+| `"start"` | `start` | `top` |
+| `"center"` (default) | `center` | `center` |
+| `"end"` | `end` | `bottom` |
+
+| horizontalPosition | object-position X |
+|---|---|
+| `"start"` | `left` |
+| `"center"` (default) | `center` |
+| `"end"` | `right` |
+
+## imgWidth / imgHeight
+
+Always match the intrinsic dimensions of the poster file. NuxtImg uses them to avoid the `w=1536` fallback (not in Vercel's allowed widths: 640, 750, 828, 1080, 1200, 1920, 2048, 3840).
+
+| Image type | imgWidth | imgHeight |
+|---|---|---|
+| Landscape / banner (16:9) | `1920` | `1080` |
+| Wide banner (12:5) | `1920` | `800` |
+| Square | `800` | `800` |
+
+## CSS custom properties
+
+Private tokens (set via `data-depth` + CSS selectors, not inline style):
+
+| Property | Default (md tier) | Controlled by |
+|---|---|---|
+| `--_max-height` | `clamp(28rem, 38vw, 56rem)` | `data-depth` selector |
+
+Inline style tokens (set from props):
+
+| Property | Default | Set by prop |
+|---|---|---|
+| `--_aspect-ratio` | `21/9` | `aspectRatio` |
+| `--_align-self` | `center` | `verticalPosition` |
+| `--_justify-self` | `center` | `horizontalPosition` |
+
+### Depth token defaults
+
+| depth | token | clamp value |
+|---|---|---|
+| `xs` | `--theme-banner-video-max-height-xs` | `clamp(12rem, 15vw, 24rem)` |
+| `sm` | `--theme-banner-video-max-height-sm` | `clamp(18rem, 22vw, 36rem)` |
+| `md` | `--theme-banner-video-max-height-md` | `clamp(28rem, 38vw, 56rem)` |
+| `lg` | `--theme-banner-video-max-height-lg` | `clamp(40rem, 52vw, 72rem)` |
+| `xl` | `--theme-banner-video-max-height-xl` | `clamp(52rem, 65vw, 90rem)` |
+
+**Override a tier in a consuming page:**
+
+```css
+.my-page {
+  --theme-banner-video-max-height-md: clamp(32rem, 45vw, 64rem);
+}
+```
+
+## CSS classes
+
+| Class | Applied when |
+|---|---|
+| `.banner-video` | Always — the root element |
+| `.video` | The `<video>` element |
+| `.fallback` | The `<NuxtImg>` fallback — hidden by default, shown via `prefers-reduced-motion` CSS |
+
+## Consumer styling
+
+Use an unscoped style block scoped by a page or section wrapper class. No `:deep()` needed — the component's styles live in `@layer components` so page styles win automatically.
+
+```vue
+<style>
+.my-page {
+  /* Override the md tier's clamp range for this page */
+  --theme-banner-video-max-height-md: clamp(32rem, 45vw, 64rem);
+}
+</style>
+```
+
+## Notes
+
+- `loading="eager"` and `decoding="async"` are hardcoded on the fallback `NuxtImg` — it is above the fold by definition.
+- The video has `autoplay muted loop playsinline preload="auto"` — intentional and not configurable. This component is for ambient background video only, not user-controlled media.
+- `prefers-reduced-motion` is handled in CSS (`.video { display: none }` + `.fallback { display: block }`), not via JS.
+- Storybook: the `"none"` image provider is active, so `poster` paths pass through unchanged. Always provide explicit `img-width` and `img-height` to avoid the `w=1536` fallback in deployed Storybook.

package/.claude/skills/components/grid-stack.md

@@ -0,0 +1,133 @@
+---
+name: GridStack
+description: GridStack CSS Grid z-axis stacking component — slot API, z-order rules, sizing behaviour, consumer patterns (video+overlay, image+text)
+type: reference
+---
+
+# GridStack
+
+## Overview
+
+`GridStack` stacks slot content in the z-axis using a single `grid-template-areas: "stack"` — no `position: absolute` needed. Every slot is wrapped in a `.grid-stack__layer` div sharing that grid area. The container sizes itself from the tallest layer; all layers stretch to fill that height.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | HTML element rendered as the root. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Slot API
+
+Any named slot is accepted — there are no declared slot names. Convention is `layer-1`, `layer-2`, `layer-3` etc., but any name works. The component iterates `$slots` and wraps each in a `.grid-stack__layer`.
+
+**Z-order rule: DOM order = z-order. The last slot is on top.**
+
+```vue
+<GridStack>
+  <template #layer-1><!-- base, behind everything --></template>
+  <template #layer-2><!-- middle --></template>
+  <template #layer-3><!-- on top --></template>
+</GridStack>
+```
+
+## Basic usage
+
+```vue
+<GridStack>
+  <template #layer-1>
+    <img src="/images/hero.jpg" alt="" />
+  </template>
+  <template #layer-2>
+    <div class="hero-overlay">
+      <h1>Heading over image</h1>
+    </div>
+  </template>
+</GridStack>
+```
+
+## Common patterns
+
+### Video background + overlay
+
+```vue
+<GridStack>
+  <template #layer-1>
+    <BannerVideo
+      src="/videos/hero.mp4"
+      poster="/images/hero-poster.jpg"
+      alt=""
+      depth="lg"
+    />
+  </template>
+  <template #layer-2>
+    <div class="video-overlay">
+      <h1>Content over video</h1>
+    </div>
+  </template>
+</GridStack>
+```
+
+### Decorative background + content
+
+```vue
+<GridStack tag="section">
+  <template #layer-1>
+    <div class="decorative-bg" aria-hidden="true"></div>
+  </template>
+  <template #layer-2>
+    <div class="section-content">
+      <p>Real content here</p>
+    </div>
+  </template>
+</GridStack>
+```
+
+## Sizing
+
+The container height is determined by the tallest child layer. All layers stretch to match. If layers have different intrinsic heights, the shorter ones will stretch — use `align-self` on the layer's inner content to control vertical position within the stretched space.
+
+To pin the stack to a fixed height, set it on the root from the consuming page:
+
+```css
+.my-page {
+  .grid-stack {
+    block-size: 60rem;
+  }
+}
+```
+
+## CSS classes
+
+| Class | Element |
+|---|---|
+| `.grid-stack` | Root element |
+| `.grid-stack__layer` | Wrapper div around each slot — all share `grid-area: stack` |
+
+## Consumer styling
+
+No `:deep()` needed — `@layer components` means page styles win automatically.
+
+```vue
+<style>
+.my-page {
+  .grid-stack {
+    border-radius: 1.2rem;
+    overflow: hidden; /* clips layers to rounded corners */
+  }
+
+  /* Style the overlay layer by targeting content inside it */
+  .my-overlay {
+    display: grid;
+    place-items: center;
+    pointer-events: none; /* let clicks through to the layer below */
+  }
+}
+</style>
+```
+
+## Notes
+
+- `pointer-events: none` on overlay layers (and `pointer-events: auto` on interactive children within them) is the standard pattern for overlays that shouldn't block interaction with layers behind them.
+- There is no built-in `z-index` — stacking is handled purely by DOM order. If a consumer applies `z-index` on a layer for other reasons, be aware it creates a new stacking context.
+- The slot name is used as the Vue `:key` on the layer wrapper, so slot names must be unique.

package/.claude/skills/components/scroll-reveal-frame.md

@@ -0,0 +1,136 @@
+---
+name: ScrollRevealFrame
+description: ScrollRevealFrame generic parallax clipping frame — props, slot API, CSS tokens, browser support, when to use vs ScrollRevealImage
+type: reference
+---
+
+# ScrollRevealFrame
+
+## Overview
+
+`ScrollRevealFrame` is a generic clipping frame that pans its slot content vertically as it scrolls through the viewport — driven entirely by CSS Scroll-driven Animations. No scroll event listeners, no `requestAnimationFrame`, no `IntersectionObserver`.
+
+Use `ScrollRevealFrame` when the content inside the frame is **anything other than a single `NuxtImg`** — a grid of images, a video, a card, arbitrary markup. For a single optimised image with focal-point control, use `ScrollRevealImage` instead (it wraps this component).
+
+## How it works
+
+- The `<figure>` root is a fixed-height clipping window (`overflow: hidden`) that registers a named `view-timeline`.
+- The inner `.reveal-content` wrapper is taller than the frame by `parallaxOffset` and animates `translateY` as the frame scrolls through the viewport.
+- Slot content fills that wrapper — anything inside pans as a unit.
+
+Browser support (as of 2026): Chrome 115+, Edge 115+, Firefox 114+, Safari 17.2+. Older browsers fall back to a static cropped view.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `frameHeight` | `string` | `"540px"` | Height of the visible clipping frame. Any CSS length unit (`px`, `vh`, `rem`). |
+| `parallaxOffset` | `string` | `"36rem"` | Distance the content travels vertically across the full scroll range. Larger = more dramatic reveal. |
+| `radius` | `string` | `"0px"` | `border-radius` applied to the clipping frame. Slot content stays contained within the rounded shape. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<figure>`. |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Content to pan. It fills a `div.reveal-content` that is taller than the frame by `parallaxOffset`. |
+
+## Basic usage — single image
+
+```vue
+<ScrollRevealFrame frame-height="540px" parallax-offset="36rem">
+  <img
+    src="/images/hero.jpg"
+    alt="Hero"
+    style="width: 100%; height: 100%; object-fit: cover; display: block;"
+  />
+</ScrollRevealFrame>
+```
+
+## Grid of images
+
+Wrap each `<img>` / `<NuxtImg>` in a `<div>` cell — `object-fit` on an `<img>` that is a direct grid item still lets the intrinsic dimensions influence the cell size. The wrapper takes the grid sizing; the image fills it.
+
+```vue
+<ScrollRevealFrame frame-height="480px" parallax-offset="36rem">
+  <div class="image-grid">
+    <div class="image-grid__cell">
+      <NuxtImg src="/images/a.jpg" alt="A" :width="800" :height="800" class="image-grid__img" />
+    </div>
+    <div class="image-grid__cell">
+      <NuxtImg src="/images/b.jpg" alt="B" :width="800" :height="800" class="image-grid__img" />
+    </div>
+    <div class="image-grid__cell">
+      <NuxtImg src="/images/c.jpg" alt="C" :width="800" :height="800" class="image-grid__img" />
+    </div>
+  </div>
+</ScrollRevealFrame>
+```
+
+```css
+.image-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-rows: repeat(1, 1fr); /* adjust for row count */
+  gap: 4px;
+  height: 100%;
+}
+
+.image-grid__cell {
+  overflow: hidden;
+  min-height: 0; /* prevent grid blowout from intrinsic image size */
+}
+
+.image-grid__img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+```
+
+## Responsive frame height
+
+The `frameHeight` prop sets `--_frame-height` as an inline style. To vary it responsively, override the CSS custom property in a scoped style block:
+
+```css
+.my-page {
+  .reveal-frame {
+    --_frame-height: 320px;
+
+    @media (width >= 768px) {
+      --_frame-height: 540px;
+    }
+  }
+}
+```
+
+## CSS custom properties
+
+These are set from props via inline `:style` but can be overridden in CSS for responsive or contextual control.
+
+| Property | Default | Set by prop |
+|----------|---------|-------------|
+| `--_frame-height` | `540px` | `frameHeight` |
+| `--_parallax-offset` | `36rem` | `parallaxOffset` |
+| `--_radius` | `0px` | `radius` |
+
+## Choosing parallaxOffset
+
+The animation spans the full time the frame is in the viewport. On a typical desktop (~900px viewport, 540px frame) the total scroll travel is ~1440px. A rule of thumb:
+
+| Frame height | Recommended parallaxOffset |
+|---|---|
+| `320px` | `20rem–24rem` |
+| `480px` | `28rem–36rem` |
+| `540px` | `36rem` (default) |
+| `70vh` | `48rem–60rem` |
+
+Values below `20rem` tend to look static at normal scroll speeds.
+
+## Notes
+
+- `overflow: hidden` is on the root `<figure>` — content that needs to escape (dropdowns, tooltips) must be portalled outside.
+- The named `view-timeline` (`--reveal-frame-timeline`) is scoped to the component. Multiple `ScrollRevealFrame` instances on the same page are independent.
+- Reduced-motion: the animation is disabled and the content falls back to a static centred crop via `@media (prefers-reduced-motion: reduce)`.
+- Do not put `ScrollRevealFrame` inside a container with `overflow: hidden` or `overflow: clip` — this breaks the `view-timeline` scroll detection.

package/.claude/skills/components/scroll-reveal-image.md

@@ -0,0 +1,161 @@
+---
+name: ScrollRevealImage
+description: ScrollRevealImage single-image parallax reveal — props, focalX usage, CSS tokens, browser support, when to use vs ScrollRevealFrame
+type: reference
+---
+
+# ScrollRevealImage
+
+## Overview
+
+`ScrollRevealImage` is a convenience wrapper around `ScrollRevealFrame` for the common case of a single optimised image. It adds `NuxtImg` (with intrinsic dimension props for Vercel/IPX optimisation) and a `focalX` prop to pin the horizontal crop axis as the image pans vertically.
+
+For arbitrary slot content — a grid of images, video, markup — use `ScrollRevealFrame` directly.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Image source path. **Required.** |
+| `alt` | `string` | `""` | Alt text for the image. |
+| `imgWidth` | `number` | `1920` | Intrinsic width of the source image — required for NuxtImg optimisation. |
+| `imgHeight` | `number` | `1080` | Intrinsic height of the source image — required for NuxtImg optimisation. |
+| `frameHeight` | `string` | `"540px"` | Height of the visible clipping frame. Any CSS length unit (`px`, `vh`, `rem`). |
+| `parallaxOffset` | `string` | `"36rem"` | Distance the image travels vertically across the full scroll range. Larger = more dramatic reveal. |
+| `focalX` | `string` | `"50%"` | Horizontal focal point — CSS `object-position` x-axis value. Controls which horizontal slice stays in view. |
+| `radius` | `string` | `"0px"` | `border-radius` applied to the clipping frame. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<figure>`. |
+
+## Basic usage
+
+```vue
+<ScrollRevealImage
+  src="/images/hero.jpg"
+  alt="Hair portrait"
+  :img-width="1280"
+  :img-height="1920"
+/>
+```
+
+## Common variants
+
+### Short banner frame
+
+```vue
+<ScrollRevealImage
+  src="/images/banner.webp"
+  alt="Banner"
+  :img-width="1920"
+  :img-height="800"
+  frame-height="320px"
+  parallax-offset="24rem"
+/>
+```
+
+### Rounded corners
+
+```vue
+<ScrollRevealImage
+  src="/images/hero.jpg"
+  alt="Portrait"
+  :img-width="1280"
+  :img-height="1920"
+  frame-height="480px"
+  radius="2.4rem"
+/>
+```
+
+### Horizontal focal point
+
+```vue
+<ScrollRevealImage
+  src="/images/hero.jpg"
+  alt="Portrait"
+  :img-width="1280"
+  :img-height="1920"
+  focal-x="75%"
+/>
+```
+
+### Tall frame — maximum travel
+
+```vue
+<ScrollRevealImage
+  src="/images/hero.jpg"
+  alt="Portrait"
+  :img-width="1280"
+  :img-height="1920"
+  frame-height="70vh"
+  parallax-offset="60rem"
+/>
+```
+
+## focalX explained
+
+The vertical position of the image is driven by the scroll animation (`translateY`). `focalX` controls the **horizontal** crop so the subject stays centred when the frame is narrower than the image.
+
+| Value | Crops toward |
+|-------|-------------|
+| `"0%"` or `"left"` | Left edge |
+| `"50%"` (default) | Centre |
+| `"75%"` | Right of centre — useful for a subject offset to the right |
+| `"100%"` or `"right"` | Right edge |
+
+Internally, `focalX` sets `object-position: <focalX> 0%` on the `<img>`. The `Y` is always `0%` because the animation handles vertical travel.
+
+## imgWidth / imgHeight
+
+Always provide these to match the intrinsic dimensions of the source file. NuxtImg uses them to:
+- Generate the correct `srcset` via the IPX pipeline
+- Avoid the `w=1536` fallback (not in Vercel's allowed widths: 640, 750, 828, 1080, 1200, 1920, 2048, 3840)
+
+Common pairs:
+
+| Image type | imgWidth | imgHeight |
+|-----------|----------|-----------|
+| Portrait (3:4) | `1280` | `1920` |
+| Landscape / banner (16:9) | `1920` | `1080` |
+| Wide banner (12:5) | `1920` | `800` |
+| Square | `800` | `800` |
+
+## Responsive frame height
+
+Override `--_frame-height` in a scoped style block for responsive control:
+
+```css
+.my-page {
+  .reveal-frame {
+    --_frame-height: 320px;
+
+    @media (width >= 768px) {
+      --_frame-height: 480px;
+    }
+
+    @media (width >= 1024px) {
+      --_frame-height: 540px;
+    }
+  }
+}
+```
+
+## CSS custom properties
+
+Set from props via inline `:style` — override in CSS for responsive or contextual control.
+
+| Property | Default | Set by prop |
+|----------|---------|-------------|
+| `--_frame-height` | `540px` | `frameHeight` |
+| `--_parallax-offset` | `36rem` | `parallaxOffset` |
+| `--_radius` | `0px` | `radius` |
+| `--_focal-x` | `50%` | `focalX` |
+
+## Choosing parallaxOffset
+
+See `scroll-reveal-frame.md` for the full guide. For portrait images the default `36rem` is a reliable starting point. Landscape/banner images in shorter frames work better with `20rem–24rem`.
+
+## Notes
+
+- `loading="lazy"` and `decoding="async"` are hardcoded on the `<img>`. If this component is the LCP image, override with `loading="eager"` via a CSS-only approach is not possible — use `ScrollRevealFrame` with a manual `NuxtImg` instead and set `:loading="'eager'"`.
+- Do not place inside a container with `overflow: hidden` or `overflow: clip` — breaks the `view-timeline` scroll detection inherited from `ScrollRevealFrame`.
+- Reduced-motion: animation is disabled and the image falls back to a static crop centred at `object-position: <focalX> 50%`.
+- Storybook: the `"none"` image provider is active (`nuxt.config.ts`), so `src` paths pass through unchanged. Always provide explicit `img-width` and `img-height` props to avoid the `w=1536` fallback in deployed Storybook.

package/.claude/skills/index.md

@@ -26,7 +26,9 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── storybook-add-font.md       — add a new font to Storybook
 ├── testing-add-unit-test.md    — create a Vitest unit test with snapshots
 ├── testing-add-playwright.md   — create a Playwright visual regression test
-├── theming-override-default.md      — override the default theme with a custom colour scale
+├── setup-postinstall.md             — automate nuxt prepare + Claude skills copy via postinstall so neither is forgotten after npm install
+├── theming-override-default.md      — replace the entire default theme with a custom colour scale (full palette swap)
+├── theming-partial-override.md      — override a specific token category (forms, buttons, colours) without a full theme replacement
 ├── colour-scheme-disable.md         — disable light/dark scheme support in a consumer app
 ├── component-dynamic-slots.md        — named dynamic slots ($slots iteration) vs indexed dynamic slots (itemCount pattern)
 ├── component-local-style-override.md — styleClassPassthrough + scoped style block for per-usage visual customisation
@@ -35,8 +37,10 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── component-aria-landmark.md        — useAriaLabelledById composable: aria-labelledby for section/main/article/aside tags
 ├── component-export-types.md         — move inline component types to app/types/components/ barrel for consumer imports
 ├── component-inline-action-button.md — InputButtonCore variant="inline" pattern for buttons embedded in custom input wrappers
+├── vue-video-autoplay.md             — autoplay on client-side navigation: use <source> child (not :src on <video>), :key, and explicit v.load()
 ├── icon-sets.md                      — icon set packages required by layer components, FOUC prevention, component→package map
 ├── robots-env-aware.md               — @nuxtjs/robots: allow crawling on prod domain only, block on preview/staging via env var
+├── new-app-scaffold.md               — scaffold a new Nuxt consumer app extending this layer (package.json, nuxt.config, app structure, CLAUDE.md)
 ├── release-notes.md                  — produce release notes as a fenced markdown block from git log
 ├── composable-whatsapp.md            — useWhatsApp: open pre-filled wa.me link from form payload; runtime config, security, usage
 ├── composable-zod-validation.md      — useZodValidation: schema-driven form validation, error binding, submit flow, API error push
@@ -61,6 +65,10 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── glass-panel.md          — GlassPanel props, slots, CSS token API (--glass-panel-bg/border-color/shadow/highlight), theming override
     ├── navigation-horizontal.md — NavigationHorizontal props, NavItemData type, CSS token API, import path gotcha
     ├── input-copy-core.md      — InputCopyCore: readonly copy-to-clipboard input; props, emits, slots, CSS classes, usage
+    ├── banner-video.md         — BannerVideo: full-width hero video banner, depth tier system, objectFit/objectPosition, reduced-motion fallback, CSS tokens
+    ├── grid-stack.md           — GridStack: CSS Grid z-axis stacking, slot API, z-order rules, sizing, video+overlay and image+text patterns
+    ├── scroll-reveal-frame.md  — ScrollRevealFrame: generic parallax clipping frame, slot API, image grid pattern, CSS tokens, browser support
+    ├── scroll-reveal-image.md  — ScrollRevealImage: single-image parallax reveal, focalX, imgWidth/imgHeight, responsive frame height
     ├── site-navigation.md      — SiteNavigation: responsive nav with auto-collapse, burger menu, decorator indicators, CSS token API
     └── social-icons-list.md    — SocialIconsList: data-driven social icon links, ISocialIcon type, logos: icon names, CSS tokens
 ```