@moonarc/core 0.1.0

package/src/components/ImageTrail.meta.ts

@@ -0,0 +1,36 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'ImageTrail',
+  slug: 'image-trail',
+  title: 'Image Trail',
+  description: 'Small images pop up along the pointer\'s path and fade behind it. The images are a server-rendered pool of lazy <img> elements; every `threshold` px the script positions the next one and restarts its keyframes, so nothing is created on move. The pop and the fade are CSS on the preset curve, the lifetime a duration token. On touch and under reduced motion the first image simply rests in the centre, under the slotted content.',
+  summary: "Images that pop up along the cursor's path and fade behind it, drawn from a pool of lazy images.",
+  category: 'pointer',
+  tier: 'B',
+  trigger: ['pointer'],
+  support: { baseline: 'widely', needs: ['container-units'] },
+  readout: '<ImageTrail images={[…]} threshold={80}>',
+  usage: `<ImageTrail images={['/a.jpg', '/b.jpg', '/c.jpg', '/d.jpg']} class="h-[28rem]">\n  <h2 class="relative">Move over me</h2>\n</ImageTrail>`,
+  props: [
+    { name: 'images', type: '(string | { src, alt? })[]', description: 'Up to 12 images; the trail cycles through them in order.' },
+    { name: 'threshold', type: 'number', default: '80', description: 'Pointer travel in px between two images. Lower is denser.' },
+    { name: 'lifetime', type: "'fast' | 'base' | 'slow'", default: "'base'", description: 'How long an image stays, as a duration token: the preset duration, the ambient duration, or twice it.' },
+    { name: 'size', type: 'number', default: '140', description: 'Image width in px; the height follows the image.' },
+    { name: 'tilt', type: 'number', default: '8', description: 'Maximum lean in degrees; each image tilts with the direction the pointer was moving.' },
+    { name: 'as', type: 'HTMLTag', default: "'div'", description: 'Element to render.' },
+  ],
+  reducedMotion: 'Nothing spawns (the script reads the setting on every move, so the page\'s own switch applies both ways without a reload); the first image sits still in the centre of the box, under the slotted content, which is also what the HTML shows without JavaScript and on touch.',
+  clientRouter: 'Bound through the shared runtime: the listeners are aborted before the swap; the pool is server HTML on every page.',
+  craft: [
+    'The images are a pool: they exist in the HTML, lazy and hidden, and the script only moves the next one and restarts its animation. The trail never allocates, never decodes on move, and the first image is there without JavaScript. Each move reads the box\'s position once (getBoundingClientRect), and a restart reads offsetWidth once.',
+    'Spawn on distance, not on time: an image every N px reads as a trail at any pointer speed; an image every N ms reads as a stutter when the pointer is slow.',
+    'The lean follows the pointer\'s direction, clamped to ±tilt, so the trail bends the way the hand moved.',
+    'Pop on the exit curve, hold, then fade: three phases in one keyframe set on the lifetime token, so a preset or an override changes all of them at once.',
+    'The pool is a size container so the resting image is centred with cqw / cqh and no measurement. At rest the pool drops under the slotted content (z-index -1 inside the isolated box), so a heading in the middle stays readable; live, the trail passes over it.',
+  ],
+  related: ['cursor', 'spotlight', 'tilt'],
+  intents: ['image trail on cursor', 'images follow mouse', 'photo trail hover effect', 'cursor image trail astro', 'hover image reveal along mouse path'],
+  replaces: ['ImageTrail (React Bits)', 'ImageTrail (Motion Primitives)', 'Image trail (Codrops)'],
+  fixture: { props: { images: ['/a.jpg', '/b.jpg'] }, expect: 'class="ma-trail"' },
+} satisfies ComponentMeta;

package/src/components/Lightbox.astro

@@ -0,0 +1,236 @@
+---
+/**
+ * Lightbox — thumbnails that open full size, the image growing out of its
+ * own thumbnail and returning to it. Built on <Dialog morph>: the dialog is
+ * native, the growth is a same-document view transition through lib/morph
+ * (no view transitions, or reduced motion → it opens as a plain dialog).
+ * The full image is loaded when it opens; the thumbnails are the images on
+ * the page, and without JavaScript each is a link to the full file.
+ * ← → and the buttons move through the set; the return target follows.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import Dialog from './Dialog.astro';
+
+interface Item {
+  src: string;
+  alt: string;
+  /** Thumbnail; default the full image. */
+  thumb?: string;
+  caption?: string;
+}
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Dialog id; unique per page. */
+  id: string;
+  items: Item[];
+  /** Thumbnail columns. */
+  columns?: number;
+  /** Thumbnail aspect ratio (CSS). */
+  ratio?: string;
+  /** Accessible name of the gallery and the dialog. */
+  label?: string;
+  /** Accessible names of the previous, next and close buttons. */
+  prevLabel?: string;
+  nextLabel?: string;
+  closeLabel?: string;
+  /** Add the inline click handler for browsers without invoker commands. */
+  polyfill?: boolean;
+}
+
+const { id, items, columns = 3, ratio = '1', label = 'Gallery', prevLabel = 'Previous image', nextLabel = 'Next image', closeLabel = 'Close', polyfill = false, class: className, style, ...rest } = Astro.props;
+const inline = [`--ma-lightbox-cols:${columns}`, `--ma-lightbox-ratio:${ratio}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-lightbox', className]} data-ma-lightbox style={inline} {...rest}>
+  <div class="ma-lightbox__grid" role="group" aria-label={label}>
+    {
+      items.map((it, i) => (
+        <a href={it.src} class="ma-lightbox__thumb" data-i={i} data-caption={it.caption}>
+          <img src={it.thumb ?? it.src} alt={it.alt} loading="lazy" decoding="async" draggable="false" />
+        </a>
+      ))
+    }
+  </div>
+  <Dialog id={id} morph polyfill={polyfill} closeLabel={closeLabel} class="ma-lightbox__dialog" aria-label={label}>
+    <Fragment slot="trigger" />
+    <figure class="ma-lightbox__figure">
+      <img class="ma-lightbox__img" alt="" data-lb-img />
+      <figcaption class="ma-lightbox__caption" aria-live="polite">
+        <span data-lb-caption></span>
+        <span class="ma-lightbox__count" data-lb-count></span>
+      </figcaption>
+    </figure>
+    {items.length > 1 && (
+      <>
+        <button type="button" class="ma-lightbox__nav ma-lightbox__nav--prev" data-lb="-1" aria-label={prevLabel}>
+          <svg aria-hidden="true" viewBox="0 0 16 16" width="16" height="16"><path d="M10 3L5 8l5 5" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" /></svg>
+        </button>
+        <button type="button" class="ma-lightbox__nav ma-lightbox__nav--next" data-lb="1" aria-label={nextLabel}>
+          <svg aria-hidden="true" viewBox="0 0 16 16" width="16" height="16"><path d="M6 3l5 5-5 5" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" /></svg>
+        </button>
+      </>
+    )}
+  </Dialog>
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-lightbox__grid) {
+      display: grid;
+      grid-template-columns: repeat(var(--ma-lightbox-cols, 3), 1fr);
+      gap: 0.5rem;
+    }
+    :where(.ma-lightbox__thumb) {
+      display: block;
+      aspect-ratio: var(--ma-lightbox-ratio, 1);
+      border: 1px solid var(--ma-edge);
+      border-radius: 0.75rem;
+      overflow: clip;
+      background: var(--ma-edge);
+    }
+    :where(.ma-lightbox__thumb img) {
+      display: block;
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+      transition: scale var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-lightbox__thumb:hover img) {
+      scale: 1.04;
+    }
+    :where(.ma-lightbox__thumb:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 3px;
+    }
+    /* the dialog is the image: no panel padding, clipped corners, sized by the picture */
+    :where(.ma-lightbox) .ma-dialog {
+      width: fit-content;
+      max-width: min(92vw, 80rem);
+      max-height: 92dvh;
+      overflow: clip;
+    }
+    :where(.ma-lightbox) .ma-dialog__panel {
+      padding: 0;
+    }
+    :where(.ma-lightbox) .ma-dialog__close button {
+      background: var(--ma-panel);
+      opacity: 0.9;
+    }
+    :where(.ma-lightbox__figure) {
+      margin: 0;
+    }
+    :where(.ma-lightbox__img) {
+      display: block;
+      width: auto;
+      height: auto;
+      max-width: min(92vw, 80rem);
+      max-height: calc(92dvh - 3rem);
+      min-width: 16rem;
+      min-height: 12rem;
+      object-fit: contain;
+      background: var(--ma-edge);
+      transition: opacity var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-dialog[data-loading] .ma-lightbox__img) {
+      opacity: 0.4;
+    }
+    :where(.ma-lightbox__caption) {
+      display: flex;
+      align-items: baseline;
+      justify-content: space-between;
+      gap: 1rem;
+      min-height: 3rem;
+      padding: 0.75rem 1rem;
+      font-size: 0.8125rem;
+      opacity: 0.85;
+    }
+    :where(.ma-lightbox__count) {
+      font-family: ui-monospace, monospace;
+      font-size: 0.6875rem;
+      letter-spacing: 0.06em;
+      /* under the caption's 0.85: 0.8 × 0.85 keeps the counter at 4.5 : 1 on the panel (0.7 read 4.44 : 1) */
+      opacity: 0.8;
+      white-space: nowrap;
+    }
+    :where(.ma-lightbox__nav) {
+      position: absolute;
+      top: calc(50% - 1.5rem);
+      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: inherit;
+      cursor: pointer;
+      opacity: 0.85;
+      transition: opacity var(--ma-duration-fast) var(--ma-ease-out), scale var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-lightbox__nav:hover) {
+      opacity: 1;
+      scale: 1.06;
+    }
+    :where(.ma-lightbox__nav:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+    }
+    :where(.ma-lightbox__nav--prev) {
+      left: 0.75rem;
+    }
+    :where(.ma-lightbox__nav--next) {
+      right: 0.75rem;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-lightbox__thumb img),
+      :where(.ma-lightbox__nav) {
+        transition: none;
+        scale: 1;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+  import { morphOpen, target } from '../lib/morph';
+
+  onMount<HTMLElement>('[data-ma-lightbox]', (root, { signal }) => {
+    const dialog = root.querySelector('dialog') as HTMLDialogElement;
+    const thumbs = [...root.querySelectorAll<HTMLAnchorElement>('.ma-lightbox__thumb')];
+    const img = dialog.querySelector<HTMLImageElement>('[data-lb-img]')!;
+    const cap = dialog.querySelector<HTMLElement>('[data-lb-caption]')!;
+    const count = dialog.querySelector<HTMLElement>('[data-lb-count]')!;
+    let i = 0;
+    // the full image is loaded when shown; the return target of the morph follows the image on screen
+    const show = (n: number) => {
+      i = (n + thumbs.length) % thumbs.length;
+      const t = thumbs[i]!;
+      if (img.src !== t.href) {
+        dialog.setAttribute('data-loading', '');
+        img.src = t.href;
+      }
+      img.alt = t.querySelector('img')!.alt;
+      cap.textContent = t.dataset.caption ?? '';
+      count.textContent = `${i + 1} / ${thumbs.length}`;
+      target(dialog, t);
+    };
+    img.addEventListener('load', () => dialog.removeAttribute('data-loading'), { signal });
+    thumbs.forEach((t, n) =>
+      t.addEventListener(
+        'click',
+        (e) => {
+          e.preventDefault();
+          show(n);
+          morphOpen(dialog, t);
+        },
+        { signal },
+      ),
+    );
+    // the two buttons and the two arrow keys are one step each way
+    dialog.addEventListener('click', (e) => { const b = (e.target as Element).closest<HTMLElement>('[data-lb]'); b && show(i + +b.dataset.lb!); }, { signal });
+    dialog.addEventListener('keydown', (e) => { const d = { ArrowRight: 1, ArrowLeft: -1 }[e.key]; d && show(i + d); }, { signal });
+    // focus lands on the thumbnail of the image that was open, not the one that was clicked
+    dialog.addEventListener('close', () => thumbs[i]!.focus(), { signal });
+  });
+</script>

package/src/components/Lightbox.meta.ts

@@ -0,0 +1,40 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Lightbox',
+  slug: 'lightbox',
+  title: 'Lightbox',
+  description: 'A thumbnail gallery whose images open full size: the image grows out of its own thumbnail on a same-document view transition and returns to it on close, and ← → move through the set. Built on Dialog morph: the dialog is native (Escape, the backdrop where closedby is supported, the close button, the focus trap), the growth is lib/morph, the caption and the count are a polite live region, and without JavaScript each thumbnail is a link to the full file.',
+  summary: 'A gallery lightbox where each image grows out of its thumbnail, with arrow keys to move through the set.',
+  category: 'ui',
+  tier: 'B',
+  trigger: ['click'],
+  support: { baseline: 'newly', needs: ['dialog', 'view-transitions'], fallback: 'without view transitions, or under reduced motion, the dialog opens as a plain dialog; without closedby (Safari) a backdrop click does nothing, and Escape and the close button still close it' },
+  readout: '<Lightbox columns={3}>',
+  usage: `<Lightbox\n  id="gallery"\n  columns={3}\n  items={[\n    { src: '/work/one.jpg', thumb: '/work/one-thumb.jpg', alt: 'Poster, 2025', caption: 'Poster, 2025' },\n    { src: '/work/two.jpg', thumb: '/work/two-thumb.jpg', alt: 'Book cover', caption: 'Book, 2024' },\n    { src: '/work/three.jpg', alt: 'Sign system' },\n  ]}\n/>`,
+  props: [
+    { name: 'id', type: 'string', description: 'Dialog id; unique per page.' },
+    { name: 'items', type: '{ src: string; alt: string; thumb?: string; caption?: string }[]', description: 'The set. thumb defaults to src; alt is required: it names the thumbnail link and the full image.' },
+    { name: 'columns', type: 'number', default: '3', description: 'Thumbnail columns.' },
+    { name: 'ratio', type: 'string', default: "'1'", description: 'Thumbnail aspect ratio.' },
+    { name: 'label', type: 'string', default: "'Gallery'", description: 'Accessible name of the group and the dialog.' },
+    { name: 'prevLabel', type: 'string', default: "'Previous image'", description: 'Accessible name of the previous button.' },
+    { name: 'nextLabel', type: 'string', default: "'Next image'", description: 'Accessible name of the next button.' },
+    { name: 'closeLabel', type: 'string', default: "'Close'", description: 'Accessible name of the close button.' },
+    { name: 'polyfill', type: 'boolean', default: 'false', description: 'Inline the invoker click handler (403 B raw). The thumbnails open through the script, so the Lightbox itself needs it for nothing; kept for parity.' },
+  ],
+  reducedMotion: 'No morph: the dialog opens with the Dialog\'s 150 ms cross-fade and closes the same way.',
+  clientRouter: 'Bound through the shared runtime; the view-transition-name exists only for the duration of a morph, so a navigation never sees it.',
+  craft: [
+    'The dialog is the picture: no panel padding, clipped corners, sized by the image up to 92 % of the viewport, so the morph is thumbnail → image, not thumbnail → box with an image in it.',
+    'The full file is loaded when the image opens and never before; the thumbnails are the page\'s own <img> elements, lazy and decoded async. While it loads the image dims to 40 % rather than showing nothing.',
+    'The return target follows the image on screen: after ← → the dialog morphs back into the thumbnail of the image you were looking at, and focus lands there too.',
+    'The caption and the "2 / 3" count are one polite live region: a step with ← → or the buttons is read out, and the focus stays on the button that made it.',
+    'One gallery is one component, set by `items` instead of a group id shared across instances, because the dialog, the counter and the keys belong to the set.',
+    'The morph itself is Dialog morph: the same script, the same tokens, the same root cross-fade, measured once.',
+  ],
+  related: ['dialog', 'video-dialog', 'image-compare', 'carousel'],
+  intents: ['lightbox', 'image gallery lightbox', 'image zoom on click', 'photo grows from thumbnail', 'gallery modal astro', 'shared element transition image'],
+  replaces: ['Lightbox (PhotoSwipe / yet-another-react-lightbox)', 'LayoutGrid (Aceternity)', 'Image zoom (Medium Zoom)', 'layoutId image (Framer Motion)'],
+  fixture: { props: { id: 'ma-fixture-lightbox', items: [{ src: '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', alt: 'Fixture content for Lightbox' }, { src: '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', alt: 'Two' }] }, expect: 'Fixture content for Lightbox' },
+} satisfies ComponentMeta;

package/src/components/LinkPreview.astro

@@ -0,0 +1,234 @@
+---
+/**
+ * LinkPreview — a link that shows a small card (image, title, domain) after
+ * a moment on hover or focus. The card is a manual popover anchored to the
+ * link, so it sits in the top layer above everything and flips when there is
+ * no room; the script only shows and hides it. The hover intent is CSS: the
+ * card's entrance carries a transition-delay on a duration token, so a
+ * pointer crossing the link never flashes a card, and no timer runs in the
+ * script. The card can be hovered (the gap to the link is part of it) and
+ * Escape hides it wherever the pointer is: WCAG 1.4.13. Everything on the
+ * card comes from props at build — there is no fetch, no scraping. Touch and
+ * coarse pointers get the link alone.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'a'> {
+  href: string;
+  /** Card title. */
+  title: string;
+  /** Card image (URL); 16:9, covers. */
+  image?: string;
+  /** One line under the title. */
+  description?: string;
+  /** Shown as the source; default the host of href. */
+  domain?: string;
+  /** The wait before the card shows, as a duration token. */
+  delay?: 'fast' | 'base' | 'slow';
+  /** position-area of the card. */
+  placement?: string;
+  /** Popover id; default generated. */
+  id?: string;
+}
+
+const { href, title, image, description, domain, delay = 'base', placement = 'bottom', id = `ma-lp-${Math.random().toString(36).slice(2, 7)}`, class: className, style, ...rest } = Astro.props;
+const host = (() => {
+  if (domain) return domain;
+  try {
+    const h = new URL(href, 'https://x.invalid').host.replace(/^www\./, '');
+    return h === 'x.invalid' ? undefined : h;
+  } catch {
+    return undefined;
+  }
+})();
+const anchor = `--ma-lp-${id}`;
+const cardStyle = `position-anchor:${anchor};--ma-lpreview-area:${placement}`;
+---
+
+<span class:list={['ma-lpreview', className]} data-ma-lpreview data-delay={delay} style={typeof style === 'string' ? style : undefined}>
+  <a href={href} class="ma-lpreview__link" aria-describedby={id} style={`anchor-name:${anchor}`} {...rest}><slot /></a>
+  <span id={id} class="ma-lpreview__card" popover="manual" role="tooltip" style={cardStyle}>
+    {image && <img class="ma-lpreview__img" src={image} alt="" loading="lazy" decoding="async" />}
+    <span class="ma-lpreview__body">
+      <strong class="ma-lpreview__title">{title}</strong>
+      {description && <span class="ma-lpreview__desc">{description}</span>}
+      {host && <span class="ma-lpreview__domain">{host}</span>}
+    </span>
+  </span>
+</span>
+
+<style is:global>
+  @layer components {
+    :where(.ma-lpreview) {
+      --ma-lpreview-delay: var(--ma-duration);
+    }
+    :where(.ma-lpreview[data-delay='fast']) {
+      --ma-lpreview-delay: var(--ma-duration-fast);
+    }
+    :where(.ma-lpreview[data-delay='slow']) {
+      --ma-lpreview-delay: var(--ma-duration-slow);
+    }
+    :where(.ma-lpreview__link) {
+      color: inherit;
+      text-decoration: underline;
+      text-decoration-color: color-mix(in srgb, currentColor 35%, transparent);
+      text-decoration-thickness: 1px;
+      text-underline-offset: 0.2em;
+      transition: text-decoration-color var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-lpreview__link:is(:hover, :focus-visible)) {
+      text-decoration-color: currentColor;
+    }
+    :where(.ma-lpreview__link:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+      border-radius: 2px;
+    }
+    /* the card: top layer, anchored, and its entrance waits on the delay token — the hover intent is CSS */
+    :where(.ma-lpreview__card) {
+      position: fixed;
+      inset: auto;
+      position-area: var(--ma-lpreview-area, bottom);
+      position-try-fallbacks: flip-block, flip-inline;
+      margin: 0.5rem 0;
+      width: 16rem;
+      padding: 0;
+      border: 1px solid var(--ma-edge);
+      border-radius: 0.75rem;
+      background: var(--ma-panel);
+      color: var(--ma-ink);
+      box-shadow: 0 16px 40px -20px rgb(0 0 0 / 0.45);
+      /* not the popover's own overflow: auto, which would clip the bridge below; the image rounds its own corners */
+      overflow: visible;
+      pointer-events: none;
+      opacity: 0;
+      scale: 0.96;
+      translate: 0 calc(var(--ma-travel-hover, 4px) * -1);
+      transition:
+        opacity var(--ma-duration-fast) var(--ma-ease-out),
+        scale var(--ma-duration-fast) var(--ma-ease-out),
+        translate var(--ma-duration-fast) var(--ma-ease-out),
+        display var(--ma-duration-fast) allow-discrete,
+        overlay var(--ma-duration-fast) allow-discrete,
+        visibility var(--ma-duration-fast);
+    }
+    /* open, the card takes the pointer, but only once the delay is over: until then it is visibility: hidden, so a pointer
+       that crosses the link and moves on reaches what is under the card and never raises it */
+    :where(.ma-lpreview__card:popover-open) {
+      pointer-events: auto;
+      opacity: 1;
+      scale: 1;
+      translate: 0 0;
+      transition-duration: var(--ma-duration), var(--ma-duration), var(--ma-duration), 0s, 0s, 0s;
+      transition-timing-function: var(--ma-ease), var(--ma-ease), var(--ma-ease), linear, linear, linear;
+      transition-delay: var(--ma-lpreview-delay), var(--ma-lpreview-delay), var(--ma-lpreview-delay), 0s, 0s, var(--ma-lpreview-delay);
+    }
+    @starting-style {
+      :where(.ma-lpreview__card:popover-open) {
+        opacity: 0;
+        scale: 0.96;
+        translate: 0 calc(var(--ma-travel-hover, 4px) * -1);
+        visibility: hidden;
+      }
+    }
+    :where(.ma-lpreview__card)::backdrop {
+      background: transparent;
+    }
+    /* the gap between the link and the card belongs to the card, so the pointer can cross onto it and read it (WCAG
+       1.4.13: hoverable): the margin, the 1 px border (the inset starts inside it) and 1 px of rounding. Under the
+       content, so the card's own text stays the target. */
+    :where(.ma-lpreview__card)::before {
+      content: '';
+      position: absolute;
+      z-index: -1;
+      inset: calc(-0.5rem - 2px) 0;
+    }
+    :where(.ma-lpreview__img) {
+      display: block;
+      width: 100%;
+      border-radius: calc(0.75rem - 1px) calc(0.75rem - 1px) 0 0;
+      aspect-ratio: 16 / 9;
+      object-fit: cover;
+      background: var(--ma-edge);
+    }
+    :where(.ma-lpreview__body) {
+      display: grid;
+      gap: 0.15rem;
+      padding: 0.625rem 0.75rem 0.75rem;
+      font-size: 0.8125rem;
+      line-height: 1.35;
+      text-align: start;
+    }
+    :where(.ma-lpreview__title) {
+      font-weight: 600;
+    }
+    :where(.ma-lpreview__desc) {
+      display: -webkit-box;
+      -webkit-box-orient: vertical;
+      -webkit-line-clamp: 2;
+      overflow: hidden;
+      opacity: 0.7;
+    }
+    :where(.ma-lpreview__domain) {
+      margin-top: 0.2rem;
+      font-family: ui-monospace, monospace;
+      font-size: 0.6875rem;
+      letter-spacing: 0.03em;
+      opacity: var(--ma-dim, 0.7);
+    }
+    /* no anchor positioning: the script hands the link's box over as two lengths */
+    @supports not (position-area: bottom) {
+      :where(.ma-lpreview__card) {
+        inset: auto;
+        left: var(--ma-lpreview-x, 0px);
+        top: var(--ma-lpreview-y, 0px);
+      }
+    }
+    /* touch and coarse pointers: the link alone (the script does not bind either) */
+    @media (hover: none), (pointer: coarse) {
+      :where(.ma-lpreview__card) {
+        display: none;
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-lpreview__card),
+      :where(.ma-lpreview__card:popover-open) {
+        scale: 1;
+        translate: 0 0;
+        transition-duration: var(--ma-duration-fast);
+        transition-timing-function: linear;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+
+  onMount<HTMLElement>('[data-ma-lpreview]', (el, { signal }) => {
+    if (!matchMedia('(hover: hover) and (pointer: fine)').matches) return;
+    const link = el.querySelector('a')!;
+    const card = el.querySelector<HTMLElement>('[popover]')!;
+    const place = !CSS.supports('position-area: bottom');
+    const show = () => {
+      if (place) {
+        // no anchor positioning: under the link, from its box
+        const r = link.getBoundingClientRect();
+        card.style.setProperty('--ma-lpreview-x', `${r.left}px`);
+        card.style.setProperty('--ma-lpreview-y', `${r.bottom}px`);
+      }
+      card.togglePopover(true);
+    };
+    const hide = () => card.togglePopover(false);
+    const on = (t: string, f: () => void, target: HTMLElement = link) => target.addEventListener(t, f, { signal });
+    // the pointer on the wrapper, not the link: the card is the wrapper's child, so moving from the link onto the card
+    // leaves neither, and the card stays while it is read
+    on('pointerenter', show, el);
+    on('pointerleave', hide, el);
+    on('focus', show);
+    on('blur', hide);
+    // Escape hides it wherever the focus is: a pointer resting on the link has no focus on it
+    document.addEventListener('keydown', (e) => e.key === 'Escape' && hide(), { signal });
+    signal.addEventListener('abort', hide);
+  });
+</script>

package/src/components/LinkPreview.meta.ts

@@ -0,0 +1,39 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'LinkPreview',
+  slug: 'link-preview',
+  title: 'Link Preview',
+  description: 'A link that shows a small card (image, title, one line, domain) after a moment on hover or focus, above everything, flipping when there is no room. The card is a manual popover anchored to the link; the script only shows and hides it, the wait is a CSS transition-delay on a duration token, and everything on the card is a prop at build time, so nothing is fetched. Touch gets the link alone.',
+  summary: 'A link that shows a preview card with an image, a title and the domain after a moment on hover or focus.',
+  category: 'ui',
+  tier: 'B',
+  trigger: ['hover'],
+  support: { baseline: 'newly', needs: ['popover', 'anchor', 'starting-style', 'allow-discrete'], fallback: 'without anchor positioning the script places the card under the link; without the popover attribute the link is a link' },
+  readout: '<LinkPreview delay="base">',
+  usage: `<p>\n  Built on\n  <LinkPreview href="https://astro.build" title="Astro" description="The web framework for content-driven websites." image="/previews/astro.png">Astro</LinkPreview>\n  and measured on every commit.\n</p>`,
+  props: [
+    { name: 'href', type: 'string', description: 'The link.' },
+    { name: 'title', type: 'string', description: 'Card title.' },
+    { name: 'image', type: 'string', description: 'Card image, 16:9, covers.' },
+    { name: 'description', type: 'string', description: 'One or two lines under the title.' },
+    { name: 'domain', type: 'string', description: 'Source line; default the host of href.' },
+    { name: 'delay', type: "'fast' | 'base' | 'slow'", default: "'base'", description: 'The wait before the card shows: the fast, active-preset or slow duration token.' },
+    { name: 'placement', type: 'string', default: "'bottom'", description: 'A position-area value.' },
+    { name: 'id', type: 'string', description: 'Popover id; generated when unset.' },
+  ],
+  reducedMotion: 'The card cross-fades in without the scale, after the same wait.',
+  clientRouter: 'Bound through the shared runtime; the card is hidden before the swap so nothing stays in the top layer, and the document Escape listener goes with the binding.',
+  craft: [
+    'The hover intent is a transition-delay, not a setTimeout: the card enters the top layer at once but its opacity waits on the delay token, and a pointer that leaves early cancels a transition that never showed anything. No timer to clear, nothing to read from a token in JavaScript.',
+    'A manual popover: the top layer puts the card above sticky headers and overflow: clip, and anchor positioning flips it below or above the link by itself.',
+    'The card can be hovered: the gap between it and the link is the card\'s own ::before, and the pointer is watched on the wrapper that holds both, so moving onto the card to read it keeps it open. Escape hides it wherever the focus is. Together that is WCAG 1.4.13 (hoverable, dismissible, persistent).',
+    'The card takes the pointer only once it shows. Through the wait it is visibility: hidden on the same delay token, so a pointer that crosses the link on its way elsewhere never lands on it, and a click there reaches the page.',
+    'role="tooltip" with aria-describedby from the link: a screen reader hears the title and description as the link\'s description without any hover.',
+    'interestfor (Chrome 142) would make this 0 B: a hover-intent popover with no script. It is one engine today, listed in the audit as the C route.',
+  ],
+  related: ['popover', 'hover-image-links', 'cursor'],
+  intents: ['link preview on hover', 'hover card link', 'link hover card with image', 'link preview astro', 'hovercard', 'preview tooltip for links'],
+  replaces: ['LinkPreview (Aceternity)', 'HoverCard (shadcn / Radix)', 'LinkPreview (Motion Primitives)'],
+  fixture: { props: { href: 'https://example.com/', title: 'Example', description: 'Fixture content for LinkPreview' }, slot: 'a link', expect: 'Fixture content for LinkPreview' },
+} satisfies ComponentMeta;