@moonarc/core 0.1.0

package/src/components/CountdownFlip.meta.ts

@@ -0,0 +1,39 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'CountdownFlip',
+  slug: 'countdown-flip',
+  title: 'Countdown Flip',
+  description:
+    'A flip clock counting down to a date: days, hours, minutes, seconds, each a card whose top half folds down over the hinge when the number changes. The only script is one timer a second, set to the moment the next second begins, that writes the digits and stops while the tab is hidden; the flip is CSS. The server renders the time left at build for readers without JavaScript, or the done state when the target has already passed.',
+  summary: 'A flip clock that counts down to a date in days, hours, minutes and seconds, each card folding over its hinge.',
+  category: 'data',
+  tier: 'C',
+  trigger: ['load'],
+  support: { baseline: 'widely', needs: ['clip-path'] },
+  readout: '<CountdownFlip to={launch} done="Launched.">',
+  usage: `---\n// next 1 January, 00:00 UTC: relative to the build, so the example never runs out. A real launch is an ISO date with an\n// offset (or a timestamp) from your config or CMS: the build prints the time left and the browser keeps it current\nconst launch = Date.UTC(new Date().getUTCFullYear() + 1, 0, 1);\n---\n<CountdownFlip to={launch} class="text-4xl" done="Launched." />\n<CountdownFlip to={launch} labels={{ days: ['Tag', 'Tage'], hours: ['Stunde', 'Stunden'], minutes: ['Minute', 'Minuten'], seconds: ['Sekunde', 'Sekunden'] }} done="Gestartet." />\n\n<!-- a short timer: without a days card, hours wrap at 24 -->\n<CountdownFlip to={Date.now() + 90 * 60 * 1000} units={['hours', 'minutes', 'seconds']} labels={{ hours: 'h', minutes: 'm', seconds: 's' }} />`,
+  props: [
+    { name: 'to', type: 'string | number', description: 'Target: an ISO date string or a timestamp in ms.' },
+    { name: 'as', type: 'HTMLTag', default: "'div'", description: 'Element to render.' },
+    { name: 'units', type: "('days' | 'hours' | 'minutes' | 'seconds')[]", default: 'all four', description: 'Units to show, in order.' },
+    { name: 'labels', type: 'Partial<Record<Unit, string | [one: string, other: string]>>', description: 'Labels under the cards; default the unit names. A [one, other] pair gives the spoken name its singular ("1 day", "2 days"); the card always shows `other`, and `one` is used when the number is exactly 1. A plain string is used for both.' },
+    { name: 'done', type: 'string', description: 'Text shown once the countdown reaches zero, and the timer\'s accessible name from then on. When the target has passed before the build, the server renders it (no script needed).' },
+  ],
+  reducedMotion: 'Digits change in place; no card folds. Read live, so the site\'s motion switch applies on the next tick.',
+  clientRouter: 'Binds through the shared runtime: the timer is cleared before the swap and started on the new page.',
+  craft: [
+    'Time is the one thing CSS cannot know, so the script is exactly that: read the clock, write four numbers, once a second. Everything visible is a CSS animation on a data attribute.',
+    'A flip clock is two half-turns, not one: the old top folds down on an ease-in (gravity), then the new bottom unfolds on an ease-out (landing). Each takes half the preset duration.',
+    'Four layers per card and no cloning: the falling flap and the bottom half carry the old number, the top half and the rising flap carry the new one. The card is a translucent tint (--ma-edge), so a covered layer would show through. Each half shows one layer at a time: the new top waits under the falling flap until it is edge-on, the old bottom goes as the new one unfolds, and the unfolded flap stays the bottom half. Before the first flip the flaps are hidden.',
+    'The timer stops when the tab is hidden and catches up when it returns, because nobody sees a countdown in a background tab.',
+    'Each tick is a timeout to the next whole second left, with a 20 ms margin. A flat 1000 ms interval keeps the phase of the moment it started, so the card turns up to a second late, and a phase that sits on a boundary lets timer jitter skip a second or show one twice.',
+    'role="timer" with a spoken label the script keeps current ("1 day, 2 hours", singular from the `one` form at one extra comparison a second); the cards and the done text are aria-hidden, and at zero the label becomes the done text.',
+    'When the countdown finishes, the cards step back to `--ma-dim`, the level secondary text uses, and the labels stay where they were. Decoration may go fainter than that; digits may not.',
+    'Cards are 1.75em wide for two digits and grow with their padded digits past 99 days, so a third digit widens the card instead of spilling over its edges.',
+  ],
+  related: ['split-flap', 'number-flow', 'count-up'],
+  intents: ['countdown flip clock', 'flip clock countdown', 'launch countdown timer', 'countdown to date animation', 'flip counter css'],
+  replaces: ['CountdownTimer (Hover.dev)', 'flip clock libraries (FlipClock.js, flipdown)'],
+  fixture: { props: { to: '2099-01-01T00:00:00Z' }, expect: 'class="ma-cd"' },
+} satisfies ComponentMeta;

package/src/components/CounterPreloader.astro

@@ -0,0 +1,122 @@
+---
+/**
+ * CounterPreloader — a count from 0 to 100 and a curtain that lifts, zero
+ * JS. A fixed layer that never stands in the way: `pointer-events: none`
+ * from the first frame, `aria-hidden`, and the page under it is rendered
+ * and usable throughout. The number is one registered integer animated
+ * 0 → 100 (literal keyframes) printed through `counter-set`; the bar reads
+ * the same integer; then the layer translates off the top and ends
+ * hidden. The whole thing lasts twice the slow token plus one duration —
+ * about two seconds — and is not configurable longer: a preloader is a
+ * promise, not a stage. `once` inlines 187 B that skip it for the rest of
+ * the session (sessionStorage), before paint, on a full load and after
+ * every ClientRouter swap (`data-astro-rerun`) — `transition:persist` was
+ * tried and does not do it: the router moves the node into the new page
+ * and a moved node restarts its CSS animations (measured, docs/phase-7e.md).
+ * Under reduced motion, and in an engine without @property, it never shows.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Show once per session: an inline script, measured from its source string. */
+  once?: boolean;
+  /** Layer colour; default the ink token. */
+  color?: string;
+  /** Count colour; default the panel token. */
+  textColor?: string;
+  /** Element id and the once key. */
+  id?: string;
+}
+
+const { once = false, color, textColor, id = 'ma-preloader', class: className, style, ...rest } = Astro.props;
+const vars = [color && `--ma-preloader-bg:${color}`, textColor && `--ma-preloader-fg:${textColor}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+/** Runs where it is rendered, before the next paint: a session that has seen the layer removes it; the first sight is recorded. */
+const ONCE = `(function(){var s=document.currentScript,l=s.previousElementSibling,K='ma-preloader:'+l.id;try{if(sessionStorage.getItem(K)){l.remove();return}sessionStorage.setItem(K,'1')}catch(e){}})()`;
+---
+
+<div class:list={['ma-preloader', className]} id={id} aria-hidden="true" style={vars || undefined} {...rest}>
+  <span class="ma-preloader__bar"></span>
+  <span class="ma-preloader__count"><span class="ma-preloader__n"></span><span class="ma-preloader__unit">%</span></span>
+</div>
+{once && <script is:inline data-astro-rerun set:html={ONCE} />}
+
+<style is:global>
+  @property --ma-preloader-n {
+    syntax: '<integer>';
+    inherits: true;
+    initial-value: 0;
+  }
+  /* the support probe: registered, never set — visible where @property exists, the fallback everywhere else */
+  @property --ma-preloader-ok {
+    syntax: 'visible';
+    inherits: false;
+    initial-value: visible;
+  }
+  @keyframes ma-preloader-count {
+    from {
+      --ma-preloader-n: 0;
+    }
+    to {
+      --ma-preloader-n: 100;
+    }
+  }
+  @keyframes ma-preloader-lift {
+    to {
+      translate: 0 -100%;
+      visibility: hidden;
+    }
+  }
+  @layer components {
+    :where(.ma-preloader) {
+      /* the count runs twice the slow token, then the lift takes one duration */
+      --ma-preloader-count: calc(var(--ma-duration-slow) * 2);
+      position: fixed;
+      inset: 0;
+      z-index: 9999;
+      display: grid;
+      align-content: end;
+      padding: clamp(1rem, 4vw, 3rem);
+      background: var(--ma-preloader-bg, var(--ma-ink));
+      color: var(--ma-preloader-fg, var(--ma-panel));
+      pointer-events: none;
+      visibility: var(--ma-preloader-ok, hidden);
+      animation:
+        ma-preloader-count var(--ma-preloader-count) var(--ma-ease-out) forwards,
+        ma-preloader-lift var(--ma-duration) var(--ma-ease-in-out) var(--ma-preloader-count) forwards;
+    }
+    :where(.ma-preloader__bar) {
+      position: absolute;
+      inset: auto 0 0 0;
+      block-size: 3px;
+      background: currentColor;
+      transform-origin: 0 50%;
+      scale: calc(var(--ma-preloader-n) / 100) 1;
+      opacity: 0.6;
+    }
+    :where(.ma-preloader__count) {
+      justify-self: end;
+      font-size: clamp(3rem, 12vw, 9rem);
+      font-weight: 600;
+      line-height: 1;
+      letter-spacing: -0.04em;
+      font-variant-numeric: tabular-nums;
+    }
+    :where(.ma-preloader__n) {
+      counter-set: ma-preloader var(--ma-preloader-n);
+    }
+    :where(.ma-preloader__n)::before {
+      content: counter(ma-preloader);
+    }
+    :where(.ma-preloader__unit) {
+      font-size: 0.4em;
+      vertical-align: 0.9em;
+      opacity: var(--ma-dim, 0.7);
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-preloader) {
+        visibility: hidden;
+        animation: none;
+      }
+    }
+  }
+</style>

package/src/components/CounterPreloader.meta.ts

@@ -0,0 +1,34 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'CounterPreloader',
+  slug: 'counter-preloader',
+  title: 'Counter Preloader',
+  description: 'A preloader that counts from 0 to 100 and then lifts like a curtain, on a fixed layer that never blocks the page: pointer-events none from the first frame, aria-hidden, the page rendered and usable beneath. The number is one registered integer printed through counter-set; the layer then translates off and ends hidden. It runs about two seconds, set by the tokens. once skips it for the rest of the session, on a reload and after every ClientRouter swap. Under reduced motion, or without @property, it never shows. Zero JavaScript.',
+  summary: 'A preloader that counts from 0 to 100 and lifts like a curtain, without ever blocking the page beneath it.',
+  category: 'loading',
+  tier: 'A',
+  trigger: ['load'],
+  support: { baseline: 'newly', needs: ['property', 'counter-set'], fallback: 'without @property the layer is never visible (the registered probe that reveals it does not exist) and the page shows at once' },
+  readout: '<CounterPreloader once>',
+  usage: `---\n// in your layout, first thing in <body>\n---\n<CounterPreloader once />\n\n<!-- a colour of your own, and a key per site -->\n<CounterPreloader id="studio" color="oklch(0.2 0.02 60)" textColor="oklch(0.95 0.02 80)" />`,
+  props: [
+    { name: 'once', type: 'boolean', default: 'false', description: 'Show once per session: an inline script of 187 B raw (measured from its source string) removes the layer before paint when sessionStorage remembers it: on a full load and, with data-astro-rerun, after every ClientRouter swap.' },
+    { name: 'color', type: 'string', description: 'Layer colour; default the ink token.' },
+    { name: 'textColor', type: 'string', description: 'Count colour; default the panel token.' },
+    { name: 'id', type: 'string', default: "'ma-preloader'", description: 'Element id and the once key.' },
+  ],
+  reducedMotion: 'Never shown.',
+  clientRouter: 'Without once every page renders the layer again and it counts again, like any CSS animation. With once the inline script carries data-astro-rerun, runs after every swap and removes the layer before paint. transition:persist was measured and does not help: the router moves the kept node into the new page, and a moved node restarts its CSS animations.',
+  craft: [
+    'A preloader must never gate the page. The layer has pointer-events: none from its first frame and aria-hidden, the content beneath is rendered and focusable, and the whole run is bounded by the tokens: twice the slow duration for the count plus one duration for the lift, about two seconds. There is no duration prop on purpose.',
+    'The number is one registered <integer> animated 0 → 100 with literal keyframes (Firefox does not interpolate a var() in a keyframe) and printed through counter-set, so it steps like a counter and the bar can read the same integer for its scale.',
+    'The lift is a translate keyframe delayed by the count\'s duration, with visibility: hidden at its end and fill-mode forwards, so the layer is truly gone, not an invisible box over the page.',
+    'Support is probed without a script: a registered custom property with initial-value visible that nothing ever sets. Where @property exists, visibility: var(--ma-preloader-ok, hidden) resolves to visible; where it does not, the fallback keeps the layer hidden. No flash of a stuck curtain in an old engine.',
+    'once is inline and measured from its source string, like StickyBanner\'s remember: it has to run before the first paint of the page it is on, and it carries data-astro-rerun so the router runs it again after a swap. transition:persist was the plan; measured, the persisted node restarts its count on the next page, because moving a node restarts its CSS animations.',
+  ],
+  related: ['progress', 'curtain', 'count-up'],
+  intents: ['preloader counter', 'page loader 0 to 100', 'loading screen counter', 'intro curtain', 'site preloader css', 'studio loading number'],
+  replaces: ['Preloader (Osmo)', 'Loader (Aceternity)', 'Studio-style loading count'],
+  fixture: { props: { id: 'ma-fixture-preloader' }, slot: '', expect: 'ma-preloader__count' },
+} satisfies ComponentMeta;

package/src/components/Cursor.astro

@@ -0,0 +1,177 @@
+---
+/**
+ * Cursor — a custom pointer that trails the real one and reacts to what it
+ * is over: a dot, a ring that grows on links and buttons, or a label
+ * ("View") that any element can ask for with data-cursor-label.
+ *
+ * One fixed element. The script writes the pointer position as two custom
+ * properties and one state attribute; the lag, the growth and the label
+ * morph are CSS transitions on the preset's curve, so the follow has the
+ * same character as everything else on the page and no lerp runs in JS.
+ * Targets are delegated: one pointerover listener on the document reads
+ * `a, button, [data-cursor]`, never a listener per element. Not installed on
+ * touch, coarse pointers or reduced motion; hidden over text fields so the
+ * native I-beam does its job; gone when the pointer leaves the window.
+ * `within` confines it to the parent element (a section, a card, a demo);
+ * hideNative is a :has() rule on the state, so the script never touches <html>.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** dot: a small disc · ring: a disc that grows over targets · label: a disc that becomes a pill with text over labelled targets (and grows over the rest). */
+  mode?: 'dot' | 'ring' | 'label';
+  /** Disc diameter in px. */
+  size?: number;
+  /** Growth over targets, as a multiple of size. */
+  grow?: number;
+  /** mix-blend-mode: difference — inverts what it covers. Reads badly on a light theme unless the disc is dark. */
+  blend?: boolean;
+  /** Hide the native cursor everywhere except over text fields. */
+  hideNative?: boolean;
+  /** Confine to the parent element: positioned absolutely inside it, pointer read from it only. */
+  within?: boolean;
+  /** Default label text for mode="label" when a target has data-cursor-label without a value. */
+  label?: string;
+}
+
+const { mode = 'ring', size = 12, grow = 3, blend = false, hideNative = false, within = false, label = 'View', class: className, style, ...rest } = Astro.props;
+const inline = [`--ma-cursor-size:${size}px`, `--ma-cursor-grow:${grow}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div
+  class:list={['ma-cursor', className]}
+  data-ma-cursor
+  data-mode={mode}
+  data-state="hidden"
+  data-blend={blend ? '' : undefined}
+  data-hide-native={hideNative ? '' : undefined}
+  data-within={within ? '' : undefined}
+  data-label={label}
+  aria-hidden="true"
+  style={inline}
+  {...rest}
+><span class="ma-cursor__label"></span></div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-cursor) {
+      position: fixed;
+      left: 0;
+      top: 0;
+      z-index: 2147483000;
+      display: grid;
+      place-items: center;
+      box-sizing: border-box;
+      width: var(--ma-cursor-size, 12px);
+      height: var(--ma-cursor-size, 12px);
+      border-radius: 999px;
+      background: var(--ma-ink);
+      color: var(--ma-panel);
+      pointer-events: none;
+      /* --ma-cursor-x / --ma-cursor-y: the pointer, written by the script; the disc is centred on it */
+      translate: calc(var(--ma-cursor-x, -100px) - 50%) calc(var(--ma-cursor-y, -100px) - 50%);
+      scale: 1;
+      opacity: 1;
+      /* the lag is the fast token on the exit curve: close enough to feel attached, late enough to read as a trail */
+      transition:
+        translate var(--ma-duration-fast) var(--ma-ease-out),
+        scale var(--ma-duration) var(--ma-ease),
+        width var(--ma-duration) var(--ma-ease),
+        height var(--ma-duration) var(--ma-ease),
+        opacity var(--ma-duration-fast) var(--ma-ease-out),
+        border-radius var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-cursor[data-within]) {
+      position: absolute;
+      z-index: 10;
+    }
+    :where(.ma-cursor[data-state='hidden']) {
+      opacity: 0;
+      scale: 0.5;
+    }
+    /* ring and label grow over links, buttons and anything with data-cursor */
+    :where(.ma-cursor[data-mode='ring'][data-state='hover']),
+    :where(.ma-cursor[data-mode='label'][data-state='hover']) {
+      scale: var(--ma-cursor-grow, 3);
+      opacity: 0.35;
+    }
+    :where(.ma-cursor[data-mode='dot'][data-state='hover']) {
+      scale: 1.6;
+    }
+    /* the label: the disc widens into a pill; the text fades in after the pill has room */
+    :where(.ma-cursor__label) {
+      display: block;
+      padding: 0 0.9em;
+      font: 500 0.75rem/1 var(--font-sans, system-ui, sans-serif);
+      letter-spacing: 0.02em;
+      white-space: nowrap;
+      opacity: 0;
+      transition: opacity var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-cursor[data-state='label']) {
+      width: auto;
+      height: calc(var(--ma-cursor-size, 12px) * 2.4);
+      min-width: calc(var(--ma-cursor-size, 12px) * 2.4);
+      opacity: 1;
+      scale: 1;
+    }
+    :where(.ma-cursor[data-state='label'] .ma-cursor__label) {
+      opacity: 1;
+      transition-delay: var(--ma-duration-fast);
+    }
+    :where(.ma-cursor[data-blend]) {
+      mix-blend-mode: difference;
+      background: #fff;
+      color: #000;
+    }
+    :where(.ma-cursor[data-state='down']) {
+      scale: 0.7;
+    }
+    /* hideNative: while the custom cursor is live, the native one is off everywhere but text fields — CSS reads the state, no script.
+       Only where the disc can show: reduced motion switched on after the script bound (or the page's own switch) hides the disc
+       below and gives the native pointer back here, instead of leaving no pointer at all */
+    @media (hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference) {
+      :where(html:not([data-ma-motion='reduce']):has(.ma-cursor[data-hide-native]:not([data-state='hidden']))) :where(*:not(input, textarea, select, [contenteditable=''], [contenteditable='true'])) {
+        cursor: none;
+      }
+    }
+    /* touch, coarse pointers and reduced motion: never shown — the script does not bind either */
+    @media (hover: none), (pointer: coarse), (prefers-reduced-motion: reduce) {
+      :where(.ma-cursor) {
+        display: none;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+
+  onMount<HTMLElement>('[data-ma-cursor]', (el, { signal, reducedMotion }) => {
+    if (reducedMotion || !matchMedia('(hover:hover) and (pointer:fine)').matches) return;
+    const within = el.hasAttribute('data-within');
+    const host = within ? el.parentElement! : document;
+    let over = 'idle';
+    const state = (v: string) => (el.dataset.state = v);
+    const on = (type: string, fn: (e: PointerEvent) => void) => host.addEventListener(type, fn as EventListener, { signal, passive: true });
+    on('pointermove', (e) => {
+      const r = within ? (host as HTMLElement).getBoundingClientRect() : { left: 0, top: 0 };
+      el.style.setProperty('--ma-cursor-x', `${e.clientX - r.left}px`);
+      el.style.setProperty('--ma-cursor-y', `${e.clientY - r.top}px`);
+      if (el.dataset.state !== 'down') state(over);
+    });
+    // one delegated listener: links, buttons and data-cursor targets grow the ring; text fields hide it; data-cursor-label names it
+    on('pointerover', (e) => {
+      const g = e.target as HTMLElement;
+      const t = g.closest('a,button,[data-cursor]');
+      const text = t?.getAttribute('data-cursor-label');
+      over = g.matches('input,select,textarea,option') || g.isContentEditable ? 'hidden' : !t ? 'idle' : el.dataset.mode === 'label' && text != null ? ((el.firstChild!.textContent = text || el.dataset.label!), 'label') : 'hover';
+      state(over);
+    });
+    on('pointerdown', () => state('down'));
+    on('pointerup', () => state(over));
+    // out of the window (or the host): nothing under the pointer is ours
+    on('pointerout', (e) => (within ? !(host as Node).contains(e.relatedTarget as Node) : !e.relatedTarget) && state('hidden'));
+    signal.addEventListener('abort', () => state('hidden'));
+  });
+</script>

package/src/components/Cursor.meta.ts

@@ -0,0 +1,37 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Cursor',
+  slug: 'cursor',
+  title: 'Cursor',
+  description: 'A custom pointer that trails the real one: a dot, a ring that grows over links and buttons, or a label ("View") any element can ask for with data-cursor-label. One fixed element; the script writes the position and a state, CSS transitions the lag, the growth and the pill on the preset curve. Not installed on touch or under reduced motion.',
+  summary: 'A custom cursor that trails the pointer: a dot, a ring that grows over links, or a label such as View.',
+  category: 'pointer',
+  tier: 'B',
+  trigger: ['pointer'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<Cursor mode="label">',
+  usage: `<Cursor mode="label" />\n<a href="/work/one" data-cursor-label="View">\n  <img src="/one.jpg" alt="" />\n</a>\n\n<!-- inside one section only -->\n<section class="relative">\n  <Cursor mode="ring" within />\n  …\n</section>`,
+  props: [
+    { name: 'mode', type: "'dot' | 'ring' | 'label'", default: "'ring'", description: 'dot: a small disc · ring: grows over targets · label: becomes a pill with text over targets that carry data-cursor-label, grows over the rest.' },
+    { name: 'size', type: 'number', default: '12', description: 'Disc diameter in px.' },
+    { name: 'grow', type: 'number', default: '3', description: 'Growth over targets, as a multiple of size.' },
+    { name: 'blend', type: 'boolean', default: 'false', description: 'mix-blend-mode: difference, so the disc inverts what it covers. Off by default: on a light theme a light disc disappears.' },
+    { name: 'hideNative', type: 'boolean', default: 'false', description: 'Hide the native cursor while the custom one is live, everywhere except over text fields.' },
+    { name: 'within', type: 'boolean', default: 'false', description: 'Confine to the parent element: positioned inside it, pointer read from it only, hidden when the pointer leaves it.' },
+    { name: 'label', type: 'string', default: "'View'", description: 'Text for targets that carry data-cursor-label with no value.' },
+  ],
+  reducedMotion: 'Not installed: the element is hidden and the script never binds, so the native cursor is the only one. Switched on while the page is open (or through the page\'s own motion switch), the disc hides and hideNative gives the native cursor back.',
+  clientRouter: 'Bound through the shared runtime: the listeners are aborted before the swap and the cursor returns to its hidden state, which ends hideNative (a :has() rule on that state, nothing written to <html>); the next page binds its own.',
+  craft: [
+    'The lag is a CSS transition on translate, on the fast token and the exit curve: close enough to feel attached, late enough to read as a trail. No lerp runs in JavaScript, so the follow costs one style write per move.',
+    'Targets are found by one pointerover listener on the document (or the host) through closest(), never a listener per element, so a page with three hundred links pays nothing per link.',
+    'Over input, textarea, select and contenteditable the custom cursor hides: the I-beam is information the ring would cover.',
+    'Never installed where (hover: hover) and (pointer: fine) do not both hold, and never under reduced motion. On a phone, a custom cursor would be a stuck dot.',
+    'pointerout with no relatedTarget means the pointer left the window; the cursor hides rather than freezing at the edge.',
+  ],
+  related: ['magnetic', 'image-trail', 'spotlight'],
+  intents: ['custom cursor', 'cursor follower', 'cursor that says view over images', 'mouse follower ring', 'blend mode cursor', 'custom mouse pointer astro'],
+  replaces: ['SplashCursor / BlobCursor (React Bits)', 'FollowerPointerCard (Aceternity)', 'Cursor (Motion Primitives)', 'SmoothCursor (Magic UI)'],
+  fixture: { props: { mode: 'label' }, expect: 'class="ma-cursor"' },
+} satisfies ComponentMeta;

package/src/components/CursorGrid.astro

@@ -0,0 +1,113 @@
+---
+/**
+ * CursorGrid — a field of cells that light where the cursor is and fade where
+ * it was. Zero JS: every cell is an element with its own :hover, lit
+ * instantly and released on a slow transition, so the trail is the browser's
+ * own hover state decaying. An idle sweep keeps the field alive when nothing
+ * touches it. Fills its positioned parent; put content above it.
+ *
+ * The cost is in the HTML, not the script: cols × rows empty elements
+ * (32 × 16 = 512 by default, ~5 kB of markup, ~120 B gzipped).
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Columns. */
+  cols?: number;
+  /** Rows. */
+  rows?: number;
+  /** Colour of a lit cell; any CSS colour. */
+  color?: string;
+  /** How long a cell takes to go dark after the cursor leaves it, ms. */
+  fade?: number;
+  /** Slow idle sweep across the field when nothing is hovered. */
+  idle?: boolean;
+  /** Show the hairline grid between cells. */
+  lines?: boolean;
+}
+
+const { cols = 32, rows = 16, color = 'currentColor', fade = 900, idle = true, lines = true, class: className, style, ...rest } = Astro.props;
+const count = Math.max(1, Math.min(cols, 96)) * Math.max(1, Math.min(rows, 64));
+const vars = [`--ma-cg-cols:${cols}`, `--ma-cg-rows:${rows}`, `--ma-cg-color:${color}`, `--ma-cg-fade:${fade}ms`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div
+  class:list={['ma-cursor-grid', className]}
+  aria-hidden="true"
+  data-idle={idle ? '' : undefined}
+  data-lines={lines ? '' : undefined}
+  style={vars}
+  {...rest}
+>
+  {Array.from({ length: count }, () => <i></i>)}
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-cursor-grid) {
+      position: absolute;
+      inset: 0;
+      display: grid;
+      grid-template-columns: repeat(var(--ma-cg-cols, 32), 1fr);
+      grid-template-rows: repeat(var(--ma-cg-rows, 16), 1fr);
+      overflow: hidden;
+      contain: strict;
+    }
+    :where(.ma-cursor-grid[data-lines]) {
+      background-image:
+        linear-gradient(to right, var(--ma-edge) 1px, transparent 1px),
+        linear-gradient(to bottom, var(--ma-edge) 1px, transparent 1px);
+      background-size: calc(100% / var(--ma-cg-cols, 32)) calc(100% / var(--ma-cg-rows, 16));
+    }
+    :where(.ma-cursor-grid > i) {
+      display: block;
+      background: var(--ma-cg-color, currentColor);
+      opacity: 0;
+      transition: opacity var(--ma-cg-fade, 900ms) var(--ma-ease-out);
+    }
+    /* lit at once, released slowly — the trail is the hover state decaying */
+    :where(.ma-cursor-grid > i:hover) {
+      opacity: 0.9;
+      transition-duration: 0ms;
+    }
+    :where(.ma-cursor-grid > i:hover + i),
+    :where(.ma-cursor-grid > i:has(+ i:hover)) {
+      opacity: 0.35;
+      transition-duration: 60ms;
+    }
+    /* idle sweep: a soft band drifting across the field, paused while the cursor is in it */
+    :where(.ma-cursor-grid[data-idle])::after {
+      content: '';
+      position: absolute;
+      inset: -20% -60%;
+      background: linear-gradient(100deg, transparent 40%, var(--ma-cg-color, currentColor) 50%, transparent 60%);
+      opacity: 0.12;
+      will-change: translate;
+      animation: ma-cursor-grid-sweep 9s var(--ma-ease-in-out) infinite alternate;
+      pointer-events: none;
+    }
+    :where(.ma-cursor-grid[data-idle]:hover)::after {
+      animation-play-state: paused;
+      opacity: 0;
+      transition: opacity 600ms;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-cursor-grid[data-idle])::after {
+        animation: none;
+        opacity: 0;
+      }
+      :where(.ma-cursor-grid > i) {
+        transition-duration: 200ms;
+      }
+    }
+  }
+
+  @keyframes ma-cursor-grid-sweep {
+    from {
+      translate: -35% 0;
+    }
+    to {
+      translate: 35% 0;
+    }
+  }
+</style>

package/src/components/CursorGrid.meta.ts

@@ -0,0 +1,37 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'CursorGrid',
+  slug: 'cursor-grid',
+  title: 'Cursor Grid',
+  description:
+    'A field of cells that light up under the cursor and fade where it has been, with a slow idle sweep when nothing is touched. Zero JavaScript: every cell is an element whose own hover state decays on a transition, so the trail is the browser doing the work. Fills its positioned parent.',
+  summary: 'A grid of cells that light up under the cursor and fade behind it, with a slow sweep when nothing moves.',
+  category: 'pointer',
+  tier: 'A',
+  trigger: ['pointer', 'always'],
+  support: { baseline: 'widely', needs: ['has'] },
+  readout: '<CursorGrid cols={32} rows={16}>',
+  usage: `<section class="relative min-h-[60vh]">\n  <CursorGrid color="oklch(78% 0.16 60)" />\n  <h1 class="relative">Move your cursor. Zero bytes of JavaScript.</h1>\n</section>`,
+  props: [
+    { name: 'cols', type: 'number', default: '32', description: 'Columns, max 96. Cells are cols × rows empty elements: the cost is HTML, about 10 B raw a cell.' },
+    { name: 'rows', type: 'number', default: '16', description: 'Rows, max 64.' },
+    { name: 'color', type: 'string', default: "'currentColor'", description: 'Colour of a lit cell.' },
+    { name: 'fade', type: 'number', default: '900', description: 'Milliseconds a cell takes to go dark after the cursor leaves. Longer means a longer trail.' },
+    { name: 'idle', type: 'boolean', default: 'true', description: 'A soft band drifts across the field when nothing is hovered; pauses on hover.' },
+    { name: 'lines', type: 'boolean', default: 'true', description: 'Draw the hairline grid between cells.' },
+  ],
+  reducedMotion: 'The idle sweep stops; cells still light under the cursor but release in 200 ms instead of trailing.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'Lit in 0 ms, released over 900 ms: the asymmetry is what reads as a trail. A symmetric fade reads as lag.',
+    'Direct neighbours (previous and next sibling) light to 35% so a fast cursor never leaves single isolated squares.',
+    'The idle sweep is a translate on one pseudo-element (compositor only) and pauses the moment the field is hovered so it never fights the cursor.',
+    'contain: strict and aria-hidden: 512 elements the layout engine and assistive tech can both ignore.',
+    'Content sits above the grid with position: relative; cells under content do not receive hover, which is correct because the cursor is on the text.',
+  ],
+  related: ['glyph-field', 'spotlight', 'grid-pattern', 'aurora'],
+  intents: ['cursor grid', 'interactive grid background', 'hover grid cells', 'pointer reactive background', 'hero background reacts to mouse'],
+  replaces: ['InteractiveGridPattern (Magic UI)', 'DotGrid (React Bits)'],
+  fixture: { props: { cols: 8, rows: 4 }, expect: 'class="ma-cursor-grid"' },
+} satisfies ComponentMeta;