@moonarc/core 0.1.0

package/src/components/Parallax.meta.ts

@@ -0,0 +1,32 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Parallax',
+  slug: 'parallax',
+  title: 'Parallax',
+  description: 'An element drifts at its own speed as it crosses the viewport, exactly in step with the scroll. Zero JavaScript: a translate bound to the element\'s own view timeline. Stack a few with different speeds for depth.',
+  summary: 'A parallax effect: an element drifts at its own speed as it crosses the viewport, in step with the scroll.',
+  category: 'scroll',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'limited', needs: ['scroll-timeline'], fallback: 'the element stays in place (Firefox)' },
+  readout: '<Parallax speed={0.3}>',
+  usage: `<div class="relative">\n  <Parallax speed={-0.2} class="absolute inset-0"><img src="/bg.jpg" alt="" /></Parallax>\n  <Parallax speed={0.4}><h2 class="relative">Foreground moves faster</h2></Parallax>\n</div>\n\n<!-- sideways: clip the row, or the drift widens the page and it scrolls horizontally -->\n<div class="overflow-x-clip">\n  <Parallax axis="x" speed={0.2}><p class="text-6xl">Moving type</p></Parallax>\n</div>`,
+  props: [
+    { name: 'as', type: 'HTMLTag', default: "'div'", description: 'Element to render.' },
+    { name: 'speed', type: 'number', default: '0.3', description: 'Drift over the element\'s full passage, as a fraction of the viewport: 0.3 travels 30 vh. Negative moves against the scroll. Keep |speed| under 0.5 or the element visits places it should not.' },
+    { name: 'axis', type: "'y' | 'x'", default: "'y'", description: 'Axis of travel. For x, give the parent overflow-x: clip: a translated element still counts toward the page\'s scrollable width, so the drift would add a horizontal scrollbar.' },
+  ],
+  reducedMotion: 'No drift; the element scrolls with the page.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'view() with range cover 0% → 100%: the drift starts the moment the element enters and ends the moment it leaves, so it is never mid-motion while static.',
+    'Linear timing: scroll-linked motion must map 1:1 to the scroll or it feels detached.',
+    'translate, not top: the compositor moves it; layout is untouched.',
+    'The parent must reserve the space the element drifts through, or it will overlap neighbours. Sideways, it must also clip (overflow-x: clip, which unlike hidden makes no scroll container and so keeps the view timeline on the page), or the drift widens the page.',
+  ],
+  related: ['reveal', 'scroll-scrub', 'card-stack'],
+  intents: ['parallax', 'parallax scroll effect', 'background moves slower than foreground', 'scroll-driven parallax astro', 'parallax without javascript'],
+  replaces: ['react-scroll-parallax', 'Rellax', 'GSAP ScrollTrigger for simple parallax'],
+  fixture: { expect: 'class="ma-parallax"' },
+} satisfies ComponentMeta;

package/src/components/Particles.astro

@@ -0,0 +1,210 @@
+---
+/**
+ * Particles — a field of drifting dots that part around the cursor, on a
+ * canvas that only draws while it is on screen and the tab is visible. The
+ * count follows the box's area (capped, so a phone never lifts two hundred
+ * points), every constant — speed, reach, push, friction, link distance —
+ * is a custom property this stylesheet declares, and the colours are the
+ * theme's, re-read when it changes. Without JavaScript the host shows a
+ * still dot pattern in CSS; under reduced motion the canvas draws one
+ * frame and stops. The lifecycle (DPR cap, ResizeObserver, visibility
+ * gate, theme observer) is the shared canvas helper. Fills its positioned
+ * parent.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Dots; default from the area, at most 160. */
+  count?: number;
+  /** Dot colour. */
+  color?: string;
+  /** Drift in px per second. */
+  speed?: number;
+  /** Radius around the cursor that pushes dots away, px; 0 turns it off. */
+  reach?: number;
+  /** Largest dot radius in px. */
+  size?: number;
+  /** Draw lines between dots closer than this, px; 0 for none. */
+  links?: number;
+}
+
+const { count, color = 'color-mix(in srgb, var(--ma-ink) 55%, transparent)', speed = 18, reach = 120, size = 1.8, links = 0, class: className, style, ...rest } = Astro.props;
+const inline = [count ? `--ma-particles-count:${count}` : '', `--ma-particles-color:${color}`, `--ma-particles-speed:${speed}`, `--ma-particles-reach:${reach}`, `--ma-particles-size:${size}`, `--ma-particles-links:${links}`, typeof style === 'string' ? style : '']
+  .filter(Boolean)
+  .join(';');
+---
+
+<div class:list={['ma-particles', className]} data-ma-particles aria-hidden="true" style={inline} {...rest}>
+  <canvas></canvas>
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-particles) {
+      position: absolute;
+      inset: 0;
+      overflow: hidden;
+      pointer-events: none;
+      contain: strict;
+      /* physics: --ma-particles-speed px/s · reach px · push (impulse per px inside the reach) · friction (impulse kept per frame) */
+      --ma-particles-push: 0.12;
+      --ma-particles-friction: 0.9;
+      --ma-particles-density: 5000;
+    }
+    :where([data-ma-preset='snap'] .ma-particles) {
+      --ma-particles-push: 0.2;
+      --ma-particles-friction: 0.85;
+    }
+    :where([data-ma-preset='ambient'] .ma-particles),
+    :where([data-ma-preset='gentle'] .ma-particles) {
+      --ma-particles-push: 0.08;
+      --ma-particles-friction: 0.94;
+    }
+    /* without a script the same dots, still, in CSS; the canvas replaces them once it has drawn */
+    :where(.ma-particles)::before {
+      content: '';
+      position: absolute;
+      inset: 0;
+      /* --ma-particles-size is a number (the script reads it); the gradient wants a length */
+      background-image: radial-gradient(circle, var(--ma-particles-color) calc(var(--ma-particles-size, 1.8) * 1px), transparent calc(var(--ma-particles-size, 1.8) * 1px + 0.6px));
+      background-size: 56px 56px;
+      background-position: 11px 19px;
+      mask-image: radial-gradient(ellipse at center, #000 40%, transparent 80%);
+      transition: opacity var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-particles[data-live])::before {
+      opacity: 0;
+    }
+    :where(.ma-particles canvas) {
+      position: absolute;
+      inset: 0;
+      width: 100%;
+      height: 100%;
+      pointer-events: auto;
+      /* the theme-resolved colours the script reads: dots, links */
+      color: var(--ma-particles-color);
+      border: 0 solid;
+      border-top-color: var(--ma-particles-color);
+    }
+    /* the pointer is read on the host; the canvas takes events so the field answers the cursor while nothing above it is covered */
+    @media (pointer: coarse) {
+      :where(.ma-particles canvas) {
+        pointer-events: none;
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-particles)::before {
+        transition: none;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount, prefersReducedMotion } from '../lib/runtime';
+  import { colors, fit, loop, num, onTheme, visible } from '../lib/canvas';
+
+  onMount<HTMLElement>('[data-ma-particles]', (el, { signal, reducedMotion }) => {
+    const canvas = el.querySelector('canvas')!;
+    let ctx: CanvasRenderingContext2D;
+    let w = 0;
+    let h = 0;
+    // x, y, drift x, drift y, impulse x, impulse y, radius
+    let ps: number[][] = [];
+    let dot = '';
+    let line = '';
+    let px = -1e4;
+    let py = -1e4;
+    const v = (n: string, f: number) => num(el, '--ma-particles-' + n, f);
+    const seed = () => {
+      const n = Math.min(160, Math.round(v('count', (w * h) / v('density', 5000))));
+      const s = v('speed', 18) / 1000;
+      const r = v('size', 1.8);
+      ps = Array.from({ length: n }, () => {
+        const a = Math.random() * Math.PI * 2;
+        const k = s * (0.4 + Math.random() * 0.8);
+        return [Math.random() * w, Math.random() * h, Math.cos(a) * k, Math.sin(a) * k, 0, 0, r * (0.4 + Math.random() * 0.6)];
+      });
+    };
+    const theme = () => ([dot, line] = colors(canvas));
+    const frame = (_t: number, dt: number) => {
+      const reach = v('reach', 120);
+      const push = v('push', 0.12);
+      const fr = v('friction', 0.9);
+      const link = v('links', 0);
+      ctx.clearRect(0, 0, w, h);
+      ctx.fillStyle = dot;
+      ctx.strokeStyle = line;
+      ctx.lineWidth = 0.5;
+      for (const p of ps) {
+        if (reach > 0) {
+          const dx = p[0]! - px;
+          const dy = p[1]! - py;
+          const d = Math.hypot(dx, dy);
+          if (d < reach && d > 0) {
+            const f = ((reach - d) / reach) * push;
+            p[4]! += (dx / d) * f;
+            p[5]! += (dy / d) * f;
+          }
+        }
+        p[4]! *= fr;
+        p[5]! *= fr;
+        p[0]! += p[2]! * dt + p[4]!;
+        p[1]! += p[3]! * dt + p[5]!;
+        // wrap around the edges
+        if (p[0]! < -4) p[0] = w + 4;
+        else if (p[0]! > w + 4) p[0] = -4;
+        if (p[1]! < -4) p[1] = h + 4;
+        else if (p[1]! > h + 4) p[1] = -4;
+        ctx.beginPath();
+        ctx.arc(p[0]!, p[1]!, p[6]!, 0, 7);
+        ctx.fill();
+      }
+      if (link > 0) {
+        ctx.beginPath();
+        for (let i = 0; i < ps.length; i++)
+          for (let j = i + 1; j < ps.length; j++) {
+            const a = ps[i]!;
+            const b = ps[j]!;
+            const dx = a[0]! - b[0]!;
+            const dy = a[1]! - b[1]!;
+            if (dx * dx + dy * dy < link * link) {
+              ctx.moveTo(a[0]!, a[1]!);
+              ctx.lineTo(b[0]!, b[1]!);
+            }
+          }
+        ctx.stroke();
+      }
+    };
+    const run = loop(frame, signal);
+    let on = false;
+    // on screen and motion allowed → run; otherwise one still frame (reduced motion is read live: the page's switch stops a running field)
+    const sync = () => (on && !prefersReducedMotion() ? run.wake() : (run.sleep(), run.once()));
+    fit(canvas, el, signal, (W, H, c) => {
+      w = W;
+      h = H;
+      ctx = c;
+      seed();
+      run.once();
+    });
+    theme();
+    onTheme(signal, () => {
+      theme();
+      sync();
+    });
+    el.setAttribute('data-live', '');
+    visible(el, signal, (o) => ((on = o), sync()));
+    if (!reducedMotion && matchMedia('(pointer: fine)').matches) {
+      canvas.addEventListener(
+        'pointermove',
+        (e) => {
+          const r = canvas.getBoundingClientRect();
+          px = e.clientX - r.left;
+          py = e.clientY - r.top;
+        },
+        { signal, passive: true },
+      );
+      canvas.addEventListener('pointerleave', () => (px = py = -1e4), { signal });
+    }
+  });
+</script>

package/src/components/Particles.meta.ts

@@ -0,0 +1,37 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Particles',
+  slug: 'particles',
+  title: 'Particles',
+  description: 'A field of drifting dots that part around the cursor, on a canvas that draws only while on screen in a visible tab. The count follows the area (capped), every constant is a custom property declared per preset, the colours are the theme\'s and are re-read when it changes. Without JavaScript a still dot pattern in CSS stands in; under reduced motion one frame is drawn.',
+  summary: 'A particle background of drifting dots that part around the cursor, drawn on a canvas only while it is on screen.',
+  category: 'background',
+  tier: 'C',
+  trigger: ['always', 'pointer'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<Particles reach={120} links={0}>',
+  usage: `<section class="relative min-h-[28rem]">\n  <Particles reach={140} links={90} color="var(--action)" />\n  <h1 class="relative">Content above the field</h1>\n</section>`,
+  props: [
+    { name: 'count', type: 'number', default: 'from the area', description: 'Dots; the default is one per 5 000 px², at most 160.' },
+    { name: 'color', type: 'string', default: 'ink at 55 %', description: 'Dot (and link) colour.' },
+    { name: 'speed', type: 'number', default: '18', description: 'Drift in px per second.' },
+    { name: 'reach', type: 'number', default: '120', description: 'Radius around the cursor that pushes dots away, in px; 0 turns it off. Never on coarse pointers.' },
+    { name: 'size', type: 'number', default: '1.8', description: 'Largest dot radius in px.' },
+    { name: 'links', type: 'number', default: '0', description: 'Draw lines between dots closer than this many px; 0 for none.' },
+  ],
+  reducedMotion: 'One frame is drawn and the loop never starts; the cursor does not push.',
+  clientRouter: 'Bound through the shared runtime: the frame loop, both observers and the listeners are released before the swap; five round trips leave one loop per instance.',
+  craft: [
+    'The loop runs only while the host intersects the viewport and the tab is visible: content-visibility on a card does not stop a requestAnimationFrame, so the component stops it.',
+    'Device pixel ratio is capped at 2 and the size is read once from a ResizeObserver; nothing listens to the resize event.',
+    'Push, friction, density and speed are custom properties this stylesheet declares (snap pushes harder and settles faster, ambient drifts), so the field has the page\'s character and the script carries no constant.',
+    'The cursor writes an impulse, not a position: dots are pushed and glide back on friction, which reads as water rather than a hole following the mouse.',
+    'Colours are read from the canvas element\'s computed style (its color and a border colour the stylesheet maps to the tokens), so oklch, color-mix and the theme all arrive as rgb the context can paint; a MutationObserver on data-theme re-reads them.',
+    'Without a script the host paints the same dots as a tiled gradient; the canvas fades it out after its first frame.',
+  ],
+  related: ['dot-pattern', 'meteors', 'globe'],
+  intents: ['particles background', 'floating dots interactive', 'particles.js alternative', 'dots avoid cursor', 'constellation background canvas'],
+  replaces: ['Particles (Magic UI)', 'Particles (React Bits)', 'SparklesCore (Aceternity)', 'tsparticles'],
+  fixture: { props: { count: 20 }, expect: 'class="ma-particles"' },
+} satisfies ComponentMeta;

package/src/components/PersistPlayer.astro

@@ -0,0 +1,126 @@
+---
+/**
+ * PersistPlayer — an audio player that keeps playing across page
+ * navigations. The native <audio controls> sits in a wrapper marked
+ * transition:persist, so Astro's router moves the very same element into
+ * the next page instead of replacing it: playback, position and volume
+ * continue. Zero JS of its own; the controls are the browser's. Where
+ * :playing exists (Safari 15.4, Firefox 150; not Chrome) the bars move
+ * while the track plays.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Audio file. */
+  src: string;
+  /** Track title. */
+  title?: string;
+  /** Artist or source line. */
+  artist?: string;
+  /** Loop the track. */
+  loop?: boolean;
+  /** Persist key; the same key on two pages pairs the players. */
+  name?: string;
+}
+
+const { src, title, artist, loop = false, name = 'ma-player', class: className, ...rest } = Astro.props;
+---
+
+<div class:list={['ma-player', className]} transition:persist={name} {...rest}>
+  <span class="ma-player__bars" aria-hidden="true"><i></i><i></i><i></i><i></i></span>
+  {(title || artist) && (
+    <span class="ma-player__meta">
+      {title && <b class="ma-player__title">{title}</b>}
+      {artist && <span class="ma-player__artist">{artist}</span>}
+    </span>
+  )}
+  <audio class="ma-player__audio" controls preload="metadata" src={src} loop={loop}></audio>
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-player) {
+      display: grid;
+      grid-template-columns: auto 1fr;
+      align-items: center;
+      gap: 0.6em 0.9em;
+      padding: 0.85em 1em;
+      border: 1px solid var(--ma-edge);
+      border-radius: 0.75em;
+      background: var(--ma-panel);
+      color: var(--ma-ink);
+    }
+    :where(.ma-player__bars) {
+      display: flex;
+      align-items: flex-end;
+      gap: 2px;
+      width: 1.1em;
+      height: 1.1em;
+    }
+    :where(.ma-player__bars > i) {
+      flex: 1;
+      height: 100%;
+      border-radius: 1px;
+      background: currentColor;
+      transform-origin: 50% 100%;
+      scale: 1 0.35;
+      /* the bar's index, named for the player and set on every bar (0 here): a page's own --ma-i must not delay the first */
+      --ma-player-i: 0;
+      animation: ma-player-bar var(--ma-dur-ambient) var(--ma-ease-in-out) calc(var(--ma-player-i) * var(--ma-stagger-relaxed)) infinite alternate;
+      animation-play-state: paused;
+    }
+    :where(.ma-player__bars > i:nth-child(2)) {
+      --ma-player-i: 1;
+      scale: 1 0.7;
+    }
+    :where(.ma-player__bars > i:nth-child(3)) {
+      --ma-player-i: 2;
+      scale: 1 0.5;
+    }
+    :where(.ma-player__bars > i:nth-child(4)) {
+      --ma-player-i: 3;
+      scale: 1 0.85;
+    }
+    /* :playing exists in WebKit and Firefox (150), not in Chrome; :where() forgives the selector there and the bars stay still */
+    :where(.ma-player:has(.ma-player__audio:playing) .ma-player__bars > i) {
+      animation-play-state: running;
+    }
+    :where(.ma-player__meta) {
+      display: grid;
+      min-width: 0;
+      line-height: 1.3;
+    }
+    :where(.ma-player__title) {
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    :where(.ma-player__artist) {
+      font-size: 0.8125em;
+      opacity: var(--ma-dim, 0.7);
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    :where(.ma-player__audio) {
+      grid-column: 1 / -1;
+      width: 100%;
+      min-width: 0;
+      height: 2.25em;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-player__bars > i) {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-player-bar {
+    from {
+      scale: 1 0.25;
+    }
+    to {
+      scale: 1 1;
+    }
+  }
+</style>

package/src/components/PersistPlayer.meta.ts

@@ -0,0 +1,35 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'PersistPlayer',
+  slug: 'persist-player',
+  title: 'Persist Player',
+  description:
+    'An audio player that keeps playing while you navigate: the same <audio> element is carried into the next page by Astro\'s router, so position, volume and playback never restart. Native controls, zero JavaScript of its own. Put it in the layout; every page gets the one that is already playing.',
+  summary: "An audio player that keeps playing across page navigations, carried into the next page by Astro's router.",
+  category: 'transition',
+  tier: 'A',
+  trigger: ['click'],
+  support: { baseline: 'widely', needs: [], fallback: 'without the router the player is a normal audio element that restarts with the page' },
+  readout: '<PersistPlayer src="/audio/loop.mp3">',
+  usage: `---\n// in the layout, so every page has it\n---\n<PersistPlayer src="/audio/loop.mp3" title="Ambient loop" artist="synthesised, CC0" loop />`,
+  props: [
+    { name: 'src', type: 'string', description: 'Audio file. MP3 plays everywhere; keep it small (this site\'s 20-second loop is a 98 kB MP3).' },
+    { name: 'title', type: 'string', description: 'Track title.' },
+    { name: 'artist', type: 'string', description: 'Artist or source line.' },
+    { name: 'loop', type: 'boolean', default: 'false', description: 'Loop the track.' },
+    { name: 'name', type: 'string', default: "'ma-player'", description: 'Persist key. The same key on two pages pairs the players; a page without it drops the player and stops the audio.' },
+  ],
+  reducedMotion: 'The bars beside the title stay still; the player is unaffected.',
+  clientRouter: 'PersistPlayer is built on the router: transition:persist moves the existing element into the new document during the swap, so the media element, its buffer and its play state are the same object before and after.',
+  craft: [
+    'The element persists, not the state: no script serialises the position and none restores it. The browser keeps decoding because nothing told it to stop.',
+    'Native controls. Play, seek, volume, the media session and the OS media keys are the browser\'s; a custom UI would need script for every one of them.',
+    'The equalizer bars run only where :playing exists (Safari 15.4, Firefox 150; Chrome has none yet) and stay still elsewhere. :where() forgives the selector, so the rule is harmless in engines without it. Nothing is faked.',
+    'The persist key is a prop, so two players on one site can coexist and a page that should stop the music simply leaves the player out.',
+  ],
+  related: ['curtain', 'page-transition', 'marquee'],
+  intents: ['persistent audio player astro', 'music keeps playing between pages', 'transition:persist audio', 'site-wide player view transitions', 'audio survives navigation'],
+  replaces: ['SPA global players (React context + Howler)', 'iframes kept alive for audio'],
+  fixture: { props: { src: '/fixture.mp3', title: 'Fixture content for PersistPlayer' }, expect: 'Fixture content for PersistPlayer' },
+} satisfies ComponentMeta;

package/src/components/PhoneFrame.astro

@@ -0,0 +1,161 @@
+---
+/**
+ * PhoneFrame — a generic phone around a screenshot or any content, zero
+ * JS. No brand: three cut-outs (`island`, `notch`, `punch`), a home bar,
+ * no logo and no buttons. The chrome scales with the frame's width through
+ * container query units, like BrowserFrame, and uses the same tokens for
+ * the bezel, the screen and the shadow. `scroll` drifts content taller
+ * than the screen up and back on a translate keyframe — one ambient
+ * duration times six, paused under the pointer and while anything inside
+ * has focus. Pass `src` for a screenshot or fill the slot.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import type { ImageMetadata } from 'astro';
+import { Image } from 'astro:assets';
+
+interface Props extends HTMLAttributes<'div'> {
+  model?: 'island' | 'notch' | 'punch';
+  /** A screenshot: an imported image (optimised by Astro) or a plain URL. */
+  src?: ImageMetadata | string;
+  alt?: string;
+  /** Drift content taller than the screen up and back. */
+  scroll?: boolean;
+  theme?: 'light' | 'dark' | 'auto';
+  /** Frame width, any CSS length; the height follows the model's ratio. */
+  width?: string;
+}
+
+const { model = 'island', src, alt = '', scroll = false, theme = 'auto', width = '18rem', class: className, style, ...rest } = Astro.props;
+const vars = [`--ma-phone-w:${width}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-phone', className]} data-model={model} data-scroll={scroll ? '' : undefined} data-theme={theme === 'auto' ? undefined : theme} style={vars} {...rest}>
+  <div class="ma-phone__body">
+  <div class="ma-phone__screen">
+    <div class="ma-phone__content">
+      {src && typeof src === 'string' && <img src={src} alt={alt} loading="lazy" decoding="async" />}
+      {src && typeof src !== 'string' && <Image src={src} alt={alt} />}
+      <slot />
+    </div>
+    <span class="ma-phone__cutout" aria-hidden="true"></span>
+    <span class="ma-phone__home" aria-hidden="true"></span>
+  </div>
+  </div>
+</div>
+
+<style is:global>
+  @keyframes ma-phone-drift {
+    to {
+      translate: 0 min(0px, calc(100cqh - 100%));
+    }
+  }
+  @layer components {
+    :where(.ma-phone) {
+      /* the container: its own cqw units belong to its descendants, so the bezel is a child (the body), not this box */
+      container-type: inline-size;
+      display: grid;
+      inline-size: var(--ma-phone-w, 18rem);
+      max-inline-size: 100%;
+      aspect-ratio: 9 / 19.5;
+      /* an aspect-ratio box has a content-based automatic minimum height: WebKit let the screen's content stretch the phone past its ratio */
+      min-block-size: 0;
+    }
+    :where(.ma-phone__body) {
+      /* the same tokens BrowserFrame uses for its chrome: edge, panel, glow; every length in cqw of the phone */
+      box-sizing: border-box;
+      display: grid;
+      min-block-size: 0;
+      padding: 3cqw;
+      border: 1px solid var(--ma-edge);
+      border-radius: 15cqw;
+      background: color-mix(in srgb, var(--ma-ink) 92%, var(--ma-panel));
+      box-shadow:
+        inset 0 0 0 1px color-mix(in srgb, var(--ma-panel) 25%, transparent),
+        0 1px 2px var(--ma-glow),
+        0 24px 48px -24px rgb(0 0 0 / 0.5);
+    }
+    :where(.ma-phone[data-model='punch']) {
+      aspect-ratio: 9 / 20;
+    }
+    :where(.ma-phone[data-theme='dark']) {
+      color-scheme: dark;
+      --ma-shine: rgb(255 255 255 / 0.32);
+      --ma-scrim: rgb(10 10 12 / 0.72);
+      --ma-edge: rgb(255 255 255 / 0.1);
+      --ma-ink: rgb(255 255 255 / 0.92);
+      --ma-panel: rgb(24 24 27 / 0.94);
+      --ma-glow: rgb(255 255 255 / 0.14);
+      --ma-dark: 1;
+    }
+    :where(.ma-phone[data-theme='light']) {
+      color-scheme: light;
+      --ma-shine: rgb(255 255 255 / 0.85);
+      --ma-scrim: rgb(255 255 255 / 0.72);
+      --ma-edge: rgb(0 0 0 / 0.08);
+      --ma-ink: rgb(0 0 0 / 0.9);
+      --ma-panel: rgb(255 255 255 / 0.92);
+      --ma-glow: rgb(0 0 0 / 0.1);
+      --ma-dark: 0;
+    }
+    :where(.ma-phone__screen) {
+      position: relative;
+      container-type: size;
+      min-block-size: 0;
+      border-radius: 12cqw;
+      background: var(--ma-panel);
+      color: var(--ma-ink);
+      overflow: clip;
+    }
+    :where(.ma-phone__content) {
+      min-block-size: 100%;
+    }
+    :where(.ma-phone__content > img) {
+      display: block;
+      inline-size: 100%;
+      block-size: auto;
+    }
+    :where(.ma-phone__cutout) {
+      position: absolute;
+      inset-block-start: 4cqw;
+      inset-inline-start: 50%;
+      inline-size: 30cqw;
+      block-size: 8cqw;
+      translate: -50% 0;
+      border-radius: 999px;
+      background: #000;
+    }
+    :where(.ma-phone[data-model='notch'] .ma-phone__cutout) {
+      inset-block-start: 0;
+      inline-size: 52cqw;
+      block-size: 8.5cqw;
+      border-radius: 0 0 6cqw 6cqw;
+    }
+    :where(.ma-phone[data-model='punch'] .ma-phone__cutout) {
+      inline-size: 5.5cqw;
+      block-size: 5.5cqw;
+      border-radius: 50%;
+    }
+    :where(.ma-phone__home) {
+      position: absolute;
+      inset-block-end: 2.5cqw;
+      inset-inline-start: 50%;
+      inline-size: 36cqw;
+      block-size: 1.3cqw;
+      translate: -50% 0;
+      border-radius: 999px;
+      background: color-mix(in srgb, var(--ma-ink) 65%, transparent);
+    }
+    /* scroll: content taller than the screen drifts up and back; the pointer, or focus inside, holds it */
+    :where(.ma-phone[data-scroll] .ma-phone__content) {
+      animation: ma-phone-drift calc(var(--ma-dur-ambient) * 6) var(--ma-ease-in-out) infinite alternate;
+    }
+    :where(.ma-phone[data-scroll]:is(:hover, :focus-within) .ma-phone__content) {
+      animation-play-state: paused;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-phone[data-scroll] .ma-phone__content) {
+        animation: none;
+      }
+    }
+  }
+</style>

package/src/components/PhoneFrame.meta.ts

@@ -0,0 +1,35 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'PhoneFrame',
+  slug: 'phone-frame',
+  title: 'Phone Frame',
+  description: 'A generic phone frame around a screenshot or any content, with three cut-outs (island, notch, punch), a home bar, and no logo, buttons or brand. The chrome scales with the frame\'s width through container query units and shares BrowserFrame\'s tokens; scroll drifts content taller than the screen up and back on a translate keyframe, paused under the pointer. Zero JavaScript.',
+  summary: 'A generic phone mockup around a screenshot, with an island, a notch or a punch hole, and content that scrolls.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'widely', needs: ['container-units'] },
+  readout: '<PhoneFrame model="island" src={shot} scroll>',
+  usage: `---\nimport shot from '../assets/app.png';\n---\n<PhoneFrame model="island" src={shot} alt="The app's home screen" scroll />\n\n<!-- any content, pinned dark -->\n<PhoneFrame model="punch" theme="dark" width="14rem">\n  <div class="p-6">…</div>\n</PhoneFrame>`,
+  props: [
+    { name: 'model', type: "'island' | 'notch' | 'punch'", default: "'island'", description: 'The cut-out: a pill, a notch at the top edge, or a dot. Generic shapes, no brand.' },
+    { name: 'src', type: 'ImageMetadata | string', description: 'A screenshot: an imported image (optimised by Astro) or a URL. Or fill the slot.' },
+    { name: 'alt', type: 'string', default: "''", description: 'Alt text for the screenshot.' },
+    { name: 'scroll', type: 'boolean', default: 'false', description: 'Drift content taller than the screen up and back (six ambient durations per leg), paused on hover and focus.' },
+    { name: 'theme', type: "'light' | 'dark' | 'auto'", default: "'auto'", description: 'Pin the base tokens to one theme, or follow the page. The theme.css tokens follow the page; add data-ma-theme="dark" as well to re-derive them inside the frame.' },
+    { name: 'width', type: 'string', default: "'18rem'", description: 'Frame width; the height follows the model\'s ratio (9:19.5, punch 9:20).' },
+  ],
+  reducedMotion: 'The content stands at the top; nothing drifts.',
+  clientRouter: 'Static; nothing to bind.',
+  craft: [
+    'Every length is in cqw of the frame (bezel, radius, cut-out, home bar), so a 14 rem phone and a 24 rem phone are the same drawing, the BrowserFrame technique.',
+    'The drift is one translate keyframe to min(0, 100cqh − 100%): 100cqh is the screen (a size container), 100% the content\'s own height, so content shorter than the screen never moves and longer content ends exactly at its bottom. Nothing is measured.',
+    'The frame is generic on purpose: three neutral cut-out shapes, no logo, no button silhouettes. It draws a phone, not an imitation of one product.',
+    'The drift pauses under the pointer and while anything inside has focus, so a reader can look at a screen, or tab through real content in the slot, without chasing it.',
+  ],
+  related: ['browser-frame', 'dynamic-island', 'image-compare'],
+  intents: ['phone mockup', 'iphone frame css', 'device frame screenshot', 'mobile mockup scrolling', 'app screenshot frame', 'phone frame no brand'],
+  replaces: ['Iphone15Pro (Magic UI)', 'DeviceFrame (Cult UI)', 'Mockup (Tailwind Plus)'],
+  fixture: { props: { model: 'island', width: '16rem' }, slot: '<p>Fixture content for PhoneFrame</p>', expect: 'Fixture content for PhoneFrame' },
+} satisfies ComponentMeta;