@moonarc/core 0.1.0

package/src/components/HoverVideo.astro

@@ -0,0 +1,179 @@
+---
+/**
+ * HoverVideo — a poster card that plays a muted clip while the pointer (or
+ * focus) is on it and rewinds when it leaves. The card is a link; the video
+ * is decoration behind it: muted, playsinline, loop, preload="none", so the
+ * page pays nothing until a hover. On coarse pointers a play/pause button
+ * appears instead of the hover; under reduced motion it never autoplays and
+ * the same button is the only way to play. Without JavaScript the poster
+ * and the link stand, and the button (which would do nothing) is not shown.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import AnimatedIcons from './AnimatedIcons.astro';
+
+interface Props extends HTMLAttributes<'figure'> {
+  /** The clip; short, muted. Several formats (webm, mp4) as an array — the browser plays the first it can. */
+  src: string | string[];
+  /** Poster image, shown until it plays and after it rewinds. */
+  poster: string;
+  /** Where the card goes; default the clip itself. */
+  href?: string;
+  title?: string;
+  /** A line under the title. */
+  meta?: string;
+  /** CSS aspect ratio. */
+  ratio?: string;
+  /** Accessible name of the play button. */
+  label?: string;
+}
+
+const { src, poster, href: link, title, meta, ratio = '16 / 10', label = 'Play preview', class: className, style, ...rest } = Astro.props;
+const sources = Array.isArray(src) ? src : [src];
+// the card is always a link, so it takes keyboard focus (which plays the clip): without href it opens the clip itself
+const href = link ?? sources[0];
+const type = (u: string) => (/\.webm(\?|$)/.test(u) ? 'video/webm' : /\.mp4(\?|$)/.test(u) ? 'video/mp4' : undefined);
+const inline = [`--ma-hvideo-ratio:${ratio}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<figure class:list={['ma-hvideo', className]} data-ma-hvideo style={inline} {...rest}>
+  <video class="ma-hvideo__video" poster={poster} muted playsinline loop preload="none" tabindex="-1" aria-hidden="true">
+    {sources.map((u) => <source src={u} type={type(u)} />)}
+  </video>
+  <button type="button" class="ma-hvideo__play" aria-label={label} aria-pressed="false">
+    <AnimatedIcons icon="play" size="1.1em" />
+  </button>
+  <figcaption class="ma-hvideo__caption">
+    <a href={href} class="ma-hvideo__link">
+      {title && <span class="ma-hvideo__title">{title}</span>}
+      {meta && <span class="ma-hvideo__meta">{meta}</span>}
+      <slot />
+    </a>
+  </figcaption>
+</figure>
+
+<style is:global>
+  @layer components {
+    :where(.ma-hvideo) {
+      position: relative;
+      margin: 0;
+      aspect-ratio: var(--ma-hvideo-ratio, 16 / 10);
+      border: 1px solid var(--ma-edge);
+      border-radius: 1rem;
+      overflow: clip;
+      background: var(--ma-ink);
+      color: #fff;
+      isolation: isolate;
+    }
+    :where(.ma-hvideo__video) {
+      display: block;
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+      scale: 1;
+      transition: scale var(--ma-dur-gentle) var(--ma-ease);
+    }
+    :where(.ma-hvideo:is(:hover, :focus-within) .ma-hvideo__video) {
+      scale: 1.04;
+    }
+    /* the card is the link: the caption's anchor stretches over the whole figure, the play button sits above it */
+    :where(.ma-hvideo__caption) {
+      position: absolute;
+      inset: auto 0 0;
+      padding: 2.5rem 1rem 0.875rem;
+      background: linear-gradient(transparent, rgb(0 0 0 / 0.6));
+    }
+    :where(.ma-hvideo__link) {
+      display: grid;
+      align-content: center;
+      min-block-size: 24px;
+      gap: 0.15rem;
+      color: inherit;
+      text-decoration: none;
+    }
+    :where(.ma-hvideo__link)::after {
+      content: '';
+      position: absolute;
+      inset: 0;
+    }
+    :where(.ma-hvideo__title) {
+      font-size: 0.9375rem;
+      font-weight: 600;
+      letter-spacing: -0.01em;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    :where(.ma-hvideo__meta) {
+      font-family: ui-monospace, monospace;
+      font-size: 0.6875rem;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      opacity: 0.75;
+    }
+    :where(.ma-hvideo:has(.ma-hvideo__link:focus-visible)) {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+    }
+    /* the play button: only where a hover cannot happen, or must not */
+    :where(.ma-hvideo__play) {
+      position: absolute;
+      top: 0.75rem;
+      right: 0.75rem;
+      z-index: 1;
+      display: none;
+      place-items: center;
+      width: 2.5rem;
+      height: 2.5rem;
+      border: 1px solid var(--ma-edge);
+      border-radius: 999px;
+      background: var(--ma-panel);
+      color: var(--ma-ink);
+      font-size: 1rem;
+      cursor: pointer;
+      transition: scale var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-hvideo__play:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+    }
+    /* data-live: the script bound, so the button does something */
+    @media (hover: none), (pointer: coarse), (prefers-reduced-motion: reduce) {
+      :where(.ma-hvideo[data-live] .ma-hvideo__play) {
+        display: grid;
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-hvideo__video),
+      :where(.ma-hvideo:is(:hover, :focus-within) .ma-hvideo__video),
+      :where(.ma-hvideo__play) {
+        scale: 1;
+        transition: none;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount, prefersReducedMotion } from '../lib/runtime';
+
+  onMount<HTMLElement>('[data-ma-hvideo]', (el, { signal }) => {
+    const v = el.querySelector('video')!;
+    const btn = el.querySelector('button')!;
+    const play = () => v.play().then(() => btn.setAttribute('aria-pressed', 'true')).catch(() => {});
+    const stop = () => {
+      v.pause();
+      v.currentTime = 0;
+      btn.setAttribute('aria-pressed', 'false');
+    };
+    btn.addEventListener('click', () => (v.paused ? play() : stop()), { signal });
+    signal.addEventListener('abort', () => v.pause());
+    el.dataset.live = '';
+    if (!matchMedia('(hover: hover) and (pointer: fine)').matches) return;
+    // hover and focus play; reduced motion is read at each hover so the page's switch applies at once
+    const hover = () => !prefersReducedMotion() && play();
+    el.addEventListener('pointerenter', hover, { signal });
+    el.addEventListener('focusin', hover, { signal });
+    el.addEventListener('pointerleave', stop, { signal });
+    el.addEventListener('focusout', stop, { signal });
+  });
+</script>

package/src/components/HoverVideo.meta.ts

@@ -0,0 +1,37 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'HoverVideo',
+  slug: 'hover-video',
+  title: 'Hover Video',
+  description: 'A poster card that plays a muted clip while the pointer or focus is on it and rewinds when it leaves. The card is a link, the video decoration behind it with preload="none", so nothing loads until a hover; coarse pointers get a play/pause button, reduced motion never autoplays. The script is play(), pause() and a rewind.',
+  summary: 'A poster card that plays a muted clip on hover or focus and rewinds on leave. Nothing loads before the hover.',
+  category: 'ui',
+  tier: 'B',
+  trigger: ['hover'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<HoverVideo poster="…">',
+  usage: `<HoverVideo\n  src={['/work/loop.webm', '/work/loop.mp4']}\n  poster="/work/loop.jpg"\n  href="/work/identity/"\n  title="Identity for a bakery"\n  meta="Brand · 2025"\n/>`,
+  props: [
+    { name: 'src', type: 'string | string[]', description: 'The clip; short and silent (it is muted anyway). An array is several formats (webm first, then mp4), and the browser plays the first it can.' },
+    { name: 'poster', type: 'string', description: 'The poster image, shown until it plays and after it rewinds.' },
+    { name: 'href', type: 'string', description: 'Where the card links; default the clip (the first source), so the card is always a link and keyboard focus can play it.' },
+    { name: 'title', type: 'string', description: 'Caption title.' },
+    { name: 'meta', type: 'string', description: 'A mono line under the title.' },
+    { name: 'ratio', type: 'string', default: "'16 / 10'", description: 'CSS aspect ratio of the card.' },
+    { name: 'label', type: 'string', default: "'Play preview'", description: 'Accessible name of the play button.' },
+  ],
+  reducedMotion: 'Never autoplays: the poster stands, the play/pause button appears and is the only way to play. Read live, so the page\'s switch applies on the next hover.',
+  clientRouter: 'Bound through the shared runtime; a playing clip is paused before the swap.',
+  craft: [
+    'preload="none" is the budget: a grid of twelve cards downloads nothing until one is hovered, and a poster is the whole cost of the page.',
+    'The card is the link and the video is aria-hidden decoration: the title is what the link says, the clip is what the eye gets.',
+    'Leaving rewinds to the poster, so every hover starts the clip from its first frame and the grid never shows twelve clips paused at random moments.',
+    'The video element scales 4 % on hover on the gentle duration, which lifts the card without a shadow. Poster and clip are the same element, so the first frame replaces the poster in place, with no cross-fade.',
+    'Where a hover cannot happen (touch) or must not (reduced motion) the same script wires a real button with aria-pressed, and AnimatedIcons turns its triangle into the pause bars. The button shows only once the script has bound, so without JavaScript nobody is offered a control that does nothing.',
+  ],
+  related: ['video-dialog', 'lightbox', 'animated-icons'],
+  intents: ['play video on hover', 'hover to play preview', 'video card hover', 'muted autoplay on hover astro', 'portfolio video thumbnails', 'work grid video preview'],
+  replaces: ['HoverVideo (Cult UI)', 'VideoCard (Aceternity)', 'react-hover-video-player'],
+  fixture: { props: { src: '/x.mp4', poster: 'data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 4 3%22%3E%3Crect width=%224%22 height=%223%22 fill=%22%23888%22/%3E%3C/svg%3E', title: 'Fixture content for HoverVideo' }, expect: 'Fixture content for HoverVideo' },
+} satisfies ComponentMeta;

package/src/components/ImageCompare.astro

@@ -0,0 +1,212 @@
+---
+/**
+ * ImageCompare — before and after, a line you drag between them. A native
+ * <input type="range"> lies over the whole box, invisible: the drag, the
+ * click-to-jump, the arrow keys, the touch and the screen reader are the
+ * browser's. The script writes the value to one custom property; the
+ * "after" image is clipped to it with clip-path: inset() and the handle
+ * sits on it. While the thumb is held there is no transition; a keyboard
+ * step or a click glides on the fast token. Without JavaScript the line
+ * stands at `start` and both halves show. Right to left, the range runs
+ * from the right, so "before" sits on the inline start (the right) and the
+ * line still follows the pointer.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** The image under the inline-start (left; right on a right-to-left page) or top half. */
+  before: string;
+  /** The image under the inline-end or bottom half. */
+  after: string;
+  beforeAlt?: string;
+  afterAlt?: string;
+  /** Initial position, 0–100. */
+  start?: number;
+  orientation?: 'horizontal' | 'vertical';
+  /** Corner labels; false hides them. */
+  labels?: [string, string] | false;
+  /** Accessible name of the slider. */
+  label?: string;
+}
+
+const { before, after, beforeAlt = '', afterAlt = '', start = 50, orientation = 'horizontal', labels = ['Before', 'After'], label = 'Compare', class: className, style, ...rest } = Astro.props;
+const inline = [`--ma-imgcmp:${Math.max(0, Math.min(100, start))}%`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-imgcmp', className]} data-ma-imgcmp data-orientation={orientation} style={inline} {...rest}>
+  <img class="ma-imgcmp__before" src={before} alt={beforeAlt} draggable="false" />
+  <img class="ma-imgcmp__after" src={after} alt={afterAlt} draggable="false" />
+  {labels && (
+    <>
+      <span class="ma-imgcmp__label ma-imgcmp__label--a" aria-hidden="true">{labels[0]}</span>
+      <span class="ma-imgcmp__label ma-imgcmp__label--b" aria-hidden="true">{labels[1]}</span>
+    </>
+  )}
+  <span class="ma-imgcmp__handle" aria-hidden="true">
+    <span class="ma-imgcmp__knob">
+      <svg viewBox="0 0 20 20" width="16" height="16"><path d="M7 6l-4 4 4 4M13 6l4 4-4 4" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" /></svg>
+    </span>
+  </span>
+  <input type="range" class="ma-imgcmp__range" min="0" max="100" step="0.5" value={start} aria-label={label} />
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-imgcmp) {
+      position: relative;
+      display: grid;
+      overflow: clip;
+      border-radius: 0.75rem;
+      background: var(--ma-edge);
+      user-select: none;
+      -webkit-user-select: none;
+    }
+    :where(.ma-imgcmp__before),
+    :where(.ma-imgcmp__after) {
+      grid-area: 1 / 1;
+      display: block;
+      width: 100%;
+      height: auto;
+      object-fit: cover;
+    }
+    /* the after image shows from the line to the right; while the thumb is held the clip follows with no lag */
+    :where(.ma-imgcmp__after) {
+      clip-path: inset(0 0 0 var(--ma-imgcmp, 50%));
+      transition: clip-path var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-imgcmp__handle) {
+      position: absolute;
+      top: 0;
+      bottom: 0;
+      left: var(--ma-imgcmp, 50%);
+      display: grid;
+      place-items: center;
+      width: 2px;
+      background: var(--ma-panel);
+      box-shadow: 0 0 0 1px rgb(0 0 0 / 0.15);
+      translate: -50% 0;
+      pointer-events: none;
+      transition: left var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-imgcmp:has(.ma-imgcmp__range:active) .ma-imgcmp__after),
+    :where(.ma-imgcmp:has(.ma-imgcmp__range:active) .ma-imgcmp__handle) {
+      transition: none;
+    }
+    :where(.ma-imgcmp__knob) {
+      display: grid;
+      place-items: center;
+      width: 2.5rem;
+      height: 2.5rem;
+      border: 1px solid var(--ma-edge);
+      border-radius: 999px;
+      background: var(--ma-panel);
+      color: var(--ma-ink);
+      box-shadow: 0 8px 24px -12px rgb(0 0 0 / 0.5);
+      transition: scale var(--ma-duration) var(--ma-ease), box-shadow var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-imgcmp:has(.ma-imgcmp__range:active) .ma-imgcmp__knob),
+    :where(.ma-imgcmp:has(.ma-imgcmp__range:hover) .ma-imgcmp__knob) {
+      scale: 1.08;
+    }
+    :where(.ma-imgcmp:has(.ma-imgcmp__range:focus-visible) .ma-imgcmp__knob) {
+      box-shadow: 0 0 0 3px var(--ma-ink);
+    }
+    /* the real control, invisible over the whole box: drag, click, keys, touch and the screen reader are native */
+    :where(.ma-imgcmp__range) {
+      position: absolute;
+      inset: 0;
+      width: 100%;
+      height: 100%;
+      margin: 0;
+      opacity: 0;
+      cursor: ew-resize;
+      touch-action: pan-y;
+    }
+    :where(.ma-imgcmp__label) {
+      position: absolute;
+      top: 0.75rem;
+      padding: 0.25em 0.6em;
+      border-radius: 999px;
+      background: var(--ma-panel);
+      color: var(--ma-ink);
+      font-family: ui-monospace, monospace;
+      font-size: 0.6875rem;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      pointer-events: none;
+    }
+    :where(.ma-imgcmp__label--a) {
+      inset-inline-start: 0.75rem;
+    }
+    :where(.ma-imgcmp__label--b) {
+      inset-inline-end: 0.75rem;
+    }
+    /* right to left: a horizontal range runs from the right, so the value is measured from the right edge and "after" shows to
+       the left of the line (inset() and translate have no logical form). [dir] and not :dir(): Chrome has :dir() only
+       from 120, and :where() drops it silently before that. An ltr island one level inside an rtl page is set back */
+    :where([dir='rtl'] .ma-imgcmp:not([data-orientation='vertical']) .ma-imgcmp__after, .ma-imgcmp[dir='rtl']:not([data-orientation='vertical']) .ma-imgcmp__after) {
+      clip-path: inset(0 var(--ma-imgcmp, 50%) 0 0);
+    }
+    :where([dir='rtl'] .ma-imgcmp:not([data-orientation='vertical']) .ma-imgcmp__handle, .ma-imgcmp[dir='rtl']:not([data-orientation='vertical']) .ma-imgcmp__handle) {
+      left: auto;
+      right: var(--ma-imgcmp, 50%);
+      translate: 50% 0;
+      transition-property: right;
+    }
+    :where([dir='rtl'] [dir='ltr'] .ma-imgcmp:not([data-orientation='vertical']) .ma-imgcmp__after, [dir='rtl'] .ma-imgcmp[dir='ltr']:not([data-orientation='vertical']) .ma-imgcmp__after) {
+      clip-path: inset(0 0 0 var(--ma-imgcmp, 50%));
+    }
+    :where([dir='rtl'] [dir='ltr'] .ma-imgcmp:not([data-orientation='vertical']) .ma-imgcmp__handle, [dir='rtl'] .ma-imgcmp[dir='ltr']:not([data-orientation='vertical']) .ma-imgcmp__handle) {
+      left: var(--ma-imgcmp, 50%);
+      right: auto;
+      translate: -50% 0;
+      transition-property: left;
+    }
+    /* vertical: the line runs across; the range is written top to bottom */
+    :where(.ma-imgcmp[data-orientation='vertical'] .ma-imgcmp__after) {
+      clip-path: inset(var(--ma-imgcmp, 50%) 0 0 0);
+    }
+    :where(.ma-imgcmp[data-orientation='vertical'] .ma-imgcmp__handle) {
+      top: var(--ma-imgcmp, 50%);
+      bottom: auto;
+      left: 0;
+      right: 0;
+      width: auto;
+      height: 2px;
+      translate: 0 -50%;
+      transition: top var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-imgcmp[data-orientation='vertical'] .ma-imgcmp__knob svg) {
+      rotate: 90deg;
+    }
+    /* direction: ltr keeps the vertical range top to bottom on a right-to-left page too (rtl would run it bottom to top) */
+    :where(.ma-imgcmp[data-orientation='vertical'] .ma-imgcmp__range) {
+      writing-mode: vertical-lr;
+      direction: ltr;
+      cursor: ns-resize;
+      touch-action: pan-x;
+    }
+    :where(.ma-imgcmp[data-orientation='vertical'] .ma-imgcmp__label--b) {
+      top: auto;
+      bottom: 0.75rem;
+      inset-inline-end: auto;
+      inset-inline-start: 0.75rem;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-imgcmp__after),
+      :where(.ma-imgcmp__handle),
+      :where(.ma-imgcmp__knob) {
+        transition: none;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+
+  onMount<HTMLElement>('[data-ma-imgcmp]', (el, { signal }) => {
+    const range = el.querySelector('input')!;
+    range.addEventListener('input', () => el.style.setProperty('--ma-imgcmp', `${range.value}%`), { signal });
+  });
+</script>

package/src/components/ImageCompare.meta.ts

@@ -0,0 +1,39 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'ImageCompare',
+  slug: 'image-compare',
+  title: 'Image Compare',
+  description: 'Compares a before and an after image with a line you drag between them. A native range input lies over the box, invisible, so dragging, clicking to jump, the arrow keys, touch and the screen reader are the browser\'s; the script writes its value to one custom property and the after image is clipped to it. Held, it follows with no lag; stepped, it glides on the fast token.',
+  summary: 'A before and after image slider on a native range input: drag, click, arrow keys and touch all work.',
+  category: 'ui',
+  tier: 'B',
+  trigger: ['pointer', 'click'],
+  support: { baseline: 'newly', needs: ['clip-path', 'has', 'range-vertical'], fallback: 'without :has() the line glides while held too; without vertical ranges, orientation="vertical" keeps a horizontal range over the box, so its line follows a sideways drag' },
+  readout: '<ImageCompare start={50}>',
+  usage: `<ImageCompare\n  before="/work/sketch.jpg"\n  after="/work/final.jpg"\n  beforeAlt="Pencil sketch of the poster"\n  afterAlt="The printed poster"\n  start={40}\n/>\n\n<ImageCompare before={a} after={b} orientation="vertical" labels={['Day', 'Night']} />`,
+  props: [
+    { name: 'before', type: 'string', description: 'The image on the inline start (the left, or the right on a right-to-left page), or the top.' },
+    { name: 'after', type: 'string', description: 'The image on the inline end, or the bottom.' },
+    { name: 'beforeAlt', type: 'string', default: "''", description: 'Alt text of the before image.' },
+    { name: 'afterAlt', type: 'string', default: "''", description: 'Alt text of the after image.' },
+    { name: 'start', type: 'number', default: '50', description: 'Initial position of the line, 0–100. Without JavaScript the line stands here.' },
+    { name: 'orientation', type: "'horizontal' | 'vertical'", default: "'horizontal'", description: 'Which way the line runs; vertical writes the range top to bottom.' },
+    { name: 'labels', type: '[string, string] | false', default: "['Before', 'After']", description: 'Corner labels.' },
+    { name: 'label', type: 'string', default: "'Compare'", description: 'Accessible name of the slider.' },
+  ],
+  reducedMotion: 'No gliding: the line moves at once on a key or a click too.',
+  clientRouter: 'Bound through the shared runtime; one input listener per instance, aborted before the swap.',
+  craft: [
+    'The control is a real range input over the whole box: keyboard, screen reader ("Compare, slider, 50 %"), touch and click-to-jump come with it, and the drag needs no pointer capture of its own.',
+    'The script is one line (the value into a custom property), and the geometry is CSS: clip-path: inset() on the after image and the handle\'s inset read the same property.',
+    'Held, the clip must not lag: :has(input:active) removes the transition while the thumb is down and restores it for a keyboard step or a click, which then glide on the fast token.',
+    'Both images are laid in one grid cell so the box is the size of the picture and the two can never drift apart; clip-path costs no layout.',
+    'touch-action: pan-y on the horizontal range: a sideways drag moves the line, a vertical one scrolls the page.',
+    'Right to left, the native range runs from the right, so the clip and the handle are measured from the right under a dir="rtl" ancestor and the line stays under the pointer; the vertical range is pinned to direction: ltr so it always runs top to bottom.',
+  ],
+  related: ['lightbox', 'scroll-expand', 'drawer'],
+  intents: ['before after slider', 'image comparison slider', 'compare two images drag', 'before after image astro', 'juxtapose images', 'split image reveal'],
+  replaces: ['Compare (Aceternity)', 'ImageComparison (Motion Primitives)', 'react-compare-image', 'Juxtapose'],
+  fixture: { props: { before: 'data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 4 3%22%3E%3Crect width=%224%22 height=%223%22 fill=%22%23888%22/%3E%3C/svg%3E', after: 'data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 4 3%22%3E%3Crect width=%224%22 height=%223%22 fill=%22%23444%22/%3E%3C/svg%3E', label: 'Fixture content for ImageCompare' }, expect: 'Fixture content for ImageCompare' },
+} satisfies ComponentMeta;

package/src/components/ImageTrail.astro

@@ -0,0 +1,169 @@
+---
+/**
+ * ImageTrail — small images pop up along the pointer's path and fade away
+ * behind it. The images are a server-rendered pool (one <img> each, lazy,
+ * hidden); the script only writes a position and restarts one keyframe on
+ * the next image in the pool every time the pointer has travelled
+ * `threshold` px, so nothing is created on move (a move reads the box's
+ * position, a restart one offsetWidth). The pop and the fade are CSS on
+ * the preset's curve, the lifetime is a duration token. Only listens
+ * inside its own box. On touch and coarse pointers the script never binds,
+ * under reduced motion (read on every move) it spawns nothing, and the
+ * first image sits still in the centre, under the slotted content — the
+ * same thing the HTML shows without JavaScript.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Image {
+  src: string;
+  alt?: string;
+}
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Up to 12 images (URLs or { src, alt }); the trail cycles through them. */
+  images: (string | Image)[];
+  /** Pointer travel in px between two images. */
+  threshold?: number;
+  /** How long an image stays: a duration token, not milliseconds. */
+  lifetime?: 'fast' | 'base' | 'slow';
+  /** Image width in px; height follows the image. */
+  size?: number;
+  /** Maximum tilt in degrees; each image leans with the direction the pointer was moving. */
+  tilt?: number;
+}
+
+const { as: Tag = 'div', images, threshold = 80, lifetime = 'base', size = 140, tilt = 8, class: className, style, ...rest } = Astro.props;
+const pool: Image[] = images.slice(0, 12).map((i) => (typeof i === 'string' ? { src: i } : i));
+const inline = [`--ma-trail-threshold:${threshold}`, `--ma-trail-size:${size}px`, `--ma-trail-tilt:${tilt}deg`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-trail', className]} data-ma-trail data-life={lifetime} style={inline} {...rest}>
+  <slot />
+  <span class="ma-trail__pool" aria-hidden="true">
+    {pool.map((img, i) => <img src={img.src} alt={img.alt ?? ''} loading="lazy" decoding="async" draggable="false" style={`--ma-i:${i}`} />)}
+  </span>
+</Tag>
+
+<style is:global>
+  @layer components {
+    :where(.ma-trail) {
+      position: relative;
+      isolation: isolate;
+      overflow: hidden;
+      /* the lifetime is a token; the pop is the preset's own curve */
+      --ma-trail-life: var(--ma-dur-ambient);
+    }
+    :where(.ma-trail[data-life='fast']) {
+      --ma-trail-life: var(--ma-duration);
+    }
+    :where(.ma-trail[data-life='slow']) {
+      --ma-trail-life: calc(var(--ma-dur-ambient) * 2);
+    }
+    :where(.ma-trail__pool) {
+      position: absolute;
+      inset: 0;
+      pointer-events: none;
+      z-index: 1;
+      /* the pool is the container the resting image is centred in (cqw / cqh below) */
+      container-type: size;
+    }
+    :where(.ma-trail__pool img) {
+      position: absolute;
+      left: 0;
+      top: 0;
+      width: var(--ma-trail-size, 140px);
+      height: auto;
+      border-radius: 0.5rem;
+      object-fit: cover;
+      opacity: 0;
+      /* --ma-trail-x / --ma-trail-y: the spawn point; --ma-trail-r: the lean, both written by the script */
+      translate: calc(var(--ma-trail-x, 50cqw) - 50%) calc(var(--ma-trail-y, 50cqh) - 50%);
+      rotate: var(--ma-trail-r, 0deg);
+      will-change: opacity, scale;
+    }
+    :where(.ma-trail__pool img[data-live]) {
+      animation: ma-trail var(--ma-trail-life) var(--ma-ease-out) both;
+    }
+    /* no script (or none allowed): the first image, still, in the centre — under the slotted content, which it would cover */
+    :where(html:not([data-ma-js]) .ma-trail__pool) {
+      z-index: -1;
+    }
+    :where(html:not([data-ma-js]) .ma-trail__pool img:first-child) {
+      opacity: 1;
+    }
+    @media (hover: none), (pointer: coarse), (prefers-reduced-motion: reduce) {
+      :where(.ma-trail__pool) {
+        z-index: -1;
+      }
+      :where(.ma-trail__pool img) {
+        animation: none;
+        opacity: 0;
+      }
+      /* centred and upright even when the trail has used it: reduced motion can be switched on after a few spawns */
+      :where(.ma-trail__pool img:first-child) {
+        opacity: 1;
+        translate: calc(50cqw - 50%) calc(50cqh - 50%);
+        rotate: 0deg;
+      }
+    }
+  }
+
+  @keyframes ma-trail {
+    0% {
+      opacity: 0;
+      scale: 0.6;
+    }
+    18% {
+      opacity: 1;
+      scale: 1;
+    }
+    70% {
+      opacity: 1;
+      scale: 1;
+    }
+    100% {
+      opacity: 0;
+      scale: 1.04;
+    }
+  }
+</style>
+
+<script>
+  import { onMount, prefersReducedMotion } from '../lib/runtime';
+
+  onMount<HTMLElement>('[data-ma-trail]', (el, { signal }) => {
+    if (!matchMedia('(hover: hover) and (pointer: fine)').matches) return;
+    const imgs = el.querySelectorAll<HTMLElement>('.ma-trail__pool img');
+    if (!imgs.length) return;
+    const threshold = Number(el.style.getPropertyValue('--ma-trail-threshold')) || 80;
+    let lx = -1e9;
+    let ly = 0;
+    let n = 0;
+    el.addEventListener(
+      'pointermove',
+      (e) => {
+        // read on every move, so the page's motion switch applies both ways without a reload
+        if (prefersReducedMotion()) return;
+        const r = el.getBoundingClientRect();
+        const x = e.clientX - r.left;
+        const y = e.clientY - r.top;
+        const dx = x - lx;
+        const dy = y - ly;
+        if (dx * dx + dy * dy < threshold * threshold) return;
+        lx = x;
+        ly = y;
+        const img = imgs[n++ % imgs.length]!;
+        img.removeAttribute('data-live');
+        void img.offsetWidth; // restart the keyframes on a recycled image
+        img.style.setProperty('--ma-trail-x', `${x}px`);
+        img.style.setProperty('--ma-trail-y', `${y}px`);
+        img.style.setProperty('--ma-trail-r', `calc(${Math.max(-1, Math.min(1, dx / threshold)).toFixed(2)} * var(--ma-trail-tilt))`);
+        img.setAttribute('data-live', '');
+      },
+      { signal, passive: true },
+    );
+    el.addEventListener('animationend', (e) => (e.target as HTMLElement).removeAttribute('data-live'), { signal });
+  });
+</script>