@moonarc/core 0.1.0

package/src/components/Meteors.astro

@@ -0,0 +1,156 @@
+---
+/**
+ * Meteors — streaks falling diagonally across a twinkling sky. Each meteor
+ * is one element: a line with a bright head, rotated to `angle`, that
+ * travels along its own axis and fades; its start, delay, length and pace
+ * come from a seeded generator on the server, so the same seed always
+ * draws the same sky (the visual test relies on it) and nothing is random
+ * at runtime. The stars are two tiled gradient layers that blink in
+ * alternation by opacity. Travel is measured in the box's own size
+ * (container units), so it crosses any parent. Zero script.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Meteors in flight. */
+  count?: number;
+  /** Direction of travel in CSS degrees: 0 right, 90 down, 135 down-left, 45 down-right. */
+  angle?: number;
+  /** Draw the star field. */
+  stars?: boolean;
+  /** Seconds per crossing (each meteor varies ±40 %). */
+  duration?: number;
+  /** Meteor colour. */
+  color?: string;
+  /** Seed for the generator; the same seed is the same sky. */
+  seed?: number;
+}
+
+const { count = 12, angle = 135, stars = true, duration = 4, color = 'var(--ma-ink)', seed = 3, class: className, style, ...rest } = Astro.props;
+const n = Math.max(1, Math.min(40, Math.round(count)));
+// mulberry32, the generator GlyphField uses
+function mulberry32(a: number) {
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+const rand = mulberry32(Math.floor(seed) || 1);
+const r2 = (v: number) => Math.round(v * 100) / 100;
+const meteors = Array.from({ length: n }, () => ({
+  x: r2(rand() * 130 - 15),
+  y: r2(rand() * 80 - 40),
+  delay: r2(rand()),
+  pace: r2(0.6 + rand() * 0.8),
+  len: r2(0.5 + rand()),
+}));
+const inline = [`--ma-meteor-angle:${angle}deg`, `--ma-meteor-dur:${duration}s`, `--ma-meteor-color:${color}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-meteors', className]} aria-hidden="true" data-stars={stars ? '' : undefined} style={inline} {...rest}>
+  {meteors.map((m) => <i style={`--ma-meteor-x:${m.x}%;--ma-meteor-y:${m.y}%;--ma-meteor-d:${m.delay};--ma-meteor-p:${m.pace};--ma-meteor-l:${m.len}`}></i>)}
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-meteors) {
+      position: absolute;
+      inset: 0;
+      overflow: hidden;
+      pointer-events: none;
+      contain: strict;
+      container-type: size;
+      color: var(--ma-meteor-color, var(--ma-ink));
+    }
+    /* the sky: two layers of tiled star gradients that blink in alternation */
+    :where(.ma-meteors[data-stars])::before,
+    :where(.ma-meteors[data-stars])::after {
+      content: '';
+      position: absolute;
+      inset: 0;
+      background-image:
+        radial-gradient(circle, currentColor 0.6px, transparent 1.1px),
+        radial-gradient(circle, currentColor 0.5px, transparent 1px);
+      background-size:
+        173px 131px,
+        97px 211px;
+      background-position:
+        23px 41px,
+        61px 7px;
+      opacity: 0.45;
+      animation: ma-meteors-twinkle calc(var(--ma-meteor-dur) * 1.5) var(--ma-ease-in-out) infinite alternate;
+    }
+    :where(.ma-meteors[data-stars])::after {
+      background-size:
+        149px 167px,
+        113px 89px;
+      background-position:
+        7px 83px,
+        91px 29px;
+      animation-delay: calc(var(--ma-meteor-dur) * -0.75);
+    }
+    /* a meteor: a fading line with a bright head at its front, laid along its direction (local x) and sent along its own axis */
+    :where(.ma-meteors > i) {
+      position: absolute;
+      left: var(--ma-meteor-x, 50%);
+      top: var(--ma-meteor-y, 0%);
+      width: calc(var(--ma-meteor-l, 1) * 20cqmax);
+      height: 1px;
+      transform-origin: 100% 50%;
+      background: linear-gradient(to right, transparent, currentColor);
+      opacity: 0;
+      will-change: transform, opacity;
+      animation: ma-meteor calc(var(--ma-meteor-dur) * var(--ma-meteor-p, 1)) linear infinite;
+      animation-delay: calc(var(--ma-meteor-dur) * var(--ma-meteor-d, 0) * -2);
+    }
+    :where(.ma-meteors > i)::before {
+      content: '';
+      position: absolute;
+      left: 100%;
+      top: 50%;
+      width: 3px;
+      height: 3px;
+      translate: -50% -50%;
+      border-radius: 50%;
+      background: currentColor;
+      box-shadow: 0 0 6px 1px currentColor;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-meteors[data-stars])::before,
+      :where(.ma-meteors[data-stars])::after {
+        animation: none;
+      }
+      :where(.ma-meteors > i) {
+        display: none;
+      }
+    }
+  }
+
+  @keyframes ma-meteor {
+    0% {
+      transform: rotate(var(--ma-meteor-angle, 135deg)) translateX(0);
+      opacity: 0;
+    }
+    8% {
+      opacity: 1;
+    }
+    70% {
+      opacity: 1;
+    }
+    100% {
+      transform: rotate(var(--ma-meteor-angle, 135deg)) translateX(140cqmax);
+      opacity: 0;
+    }
+  }
+  @keyframes ma-meteors-twinkle {
+    from {
+      opacity: 0.2;
+    }
+    to {
+      opacity: 0.6;
+    }
+  }
+</style>

package/src/components/Meteors.meta.ts

@@ -0,0 +1,36 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Meteors',
+  slug: 'meteors',
+  title: 'Meteors',
+  description: 'Streaks falling diagonally across a twinkling sky. Each meteor is one element with a bright head, rotated to its angle and sent along its own axis; start, delay, length and pace come from a seeded generator on the server, so the same seed always draws the same sky. Stars are two tiled gradient layers blinking in alternation. Zero JS; fills its positioned parent.',
+  summary: 'Meteors streaking diagonally across a twinkling star field, drawn the same way every time from a seed.',
+  category: 'background',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'widely', needs: ['container-units'] },
+  readout: '<Meteors count={12} angle={135}>',
+  usage: `<section class="relative overflow-hidden bg-black text-white">\n  <Meteors count={16} />\n  <h1 class="relative">Ship tonight</h1>\n</section>`,
+  props: [
+    { name: 'count', type: 'number', default: '12', description: 'Meteors in flight, up to 40.' },
+    { name: 'angle', type: 'number', default: '135', description: 'Direction of travel in CSS degrees: 0 right, 90 down, 135 down-left, 45 down-right.' },
+    { name: 'stars', type: 'boolean', default: 'true', description: 'Draw the star field.' },
+    { name: 'duration', type: 'number', default: '4', description: 'Seconds per crossing; each meteor varies ±40 % around it.' },
+    { name: 'color', type: 'string', default: 'var(--ma-ink)', description: 'Meteor and star colour.' },
+    { name: 'seed', type: 'number', default: '3', description: 'Seed for the generator; the same seed is the same sky.' },
+  ],
+  reducedMotion: 'The stars stand still; the meteors are not shown.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'Everything random is decided on the server with a seeded generator (mulberry32, the one GlyphField uses): the HTML is stable across builds, the visual test is reproducible, and the browser computes nothing.',
+    'A meteor travels along its own rotated axis (rotate(angle) translateX(d) in one transform keyframe), so one property moves it and the head stays in front.',
+    'Travel is measured in container units (cqmax): the meteor crosses the box whatever its size, with no px distance in the stylesheet.',
+    'The stars are two layers of tiled radial gradients at coprime tile sizes so the pattern never visibly repeats; they blink in alternation by opacity, on the in-out curve, half a period apart.',
+    'Linear timing on the streaks: a meteor does not ease.',
+  ],
+  related: ['particles', 'retro-grid', 'aurora'],
+  intents: ['meteor shower background', 'falling stars animation', 'shooting stars css', 'meteors effect hero', 'starry night background'],
+  replaces: ['Meteors (Magic UI)', 'Meteors (Aceternity)', 'MeteorShower (Eldora)'],
+  fixture: { props: { count: 6, seed: 3 }, expect: 'class="ma-meteors"' },
+} satisfies ComponentMeta;

package/src/components/Noise.astro

@@ -0,0 +1,61 @@
+---
+/**
+ * Noise — film grain over whatever is beneath. Zero JS: one SVG turbulence
+ * tile as a background, blended, with its translate stepped at 12 fps so
+ * the grain lives without repainting. Fills its positioned parent and clips
+ * the moving grain to it, so it never widens the page.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Strength, 0–1. */
+  opacity?: number;
+  /** Flicker the grain. */
+  animate?: boolean;
+  /** Blend mode against the layers beneath. */
+  blend?: 'overlay' | 'soft-light' | 'multiply' | 'screen' | 'normal';
+  /** Grain size: tile size in px. Smaller is finer. */
+  size?: number;
+}
+
+const { opacity = 0.08, animate = true, blend = 'overlay', size = 200, class: className, style, ...rest } = Astro.props;
+const vars = [`--ma-noise-o:${opacity}`, `--ma-noise-blend:${blend}`, `--ma-noise-size:${size}px`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-noise', className]} aria-hidden="true" data-animate={animate ? '' : undefined} style={vars} {...rest}></div>
+
+<style is:global>
+  @layer components {
+    /* the box is the parent's size and clips; the grain is a pseudo-element 10% larger on every side, so its translate
+       never shows an edge. The oversized box itself used to be the grain, and it widened any page it touched the edge of */
+    :where(.ma-noise) {
+      position: absolute;
+      inset: 0;
+      overflow: hidden;
+      pointer-events: none;
+      mix-blend-mode: var(--ma-noise-blend, overlay);
+      opacity: var(--ma-noise-o, 0.08);
+    }
+    :where(.ma-noise)::before {
+      content: '';
+      position: absolute;
+      inset: -10%;
+      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='200' height='200'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0.5 0 0 0 0 0.5 0 0 0 0 0.5 0 0 0 1 0'/%3E%3C/filter%3E%3Crect width='200' height='200' filter='url(%23n)'/%3E%3C/svg%3E");
+      background-size: var(--ma-noise-size, 200px) var(--ma-noise-size, 200px);
+    }
+    :where(.ma-noise[data-animate])::before {
+      animation: ma-noise 0.5s steps(6) infinite;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-noise)::before {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-noise {
+    to {
+      translate: 5% 3%;
+    }
+  }
+</style>

package/src/components/Noise.meta.ts

@@ -0,0 +1,33 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Noise',
+  slug: 'noise',
+  title: 'Noise',
+  description: 'Film grain over a gradient or image, blended and flickering at 12 fps. One SVG turbulence tile as a background whose translate steps; pure CSS, no canvas. Fills its positioned parent.',
+  summary: 'A film grain overlay that flickers at 12 fps over a gradient or an image.',
+  category: 'background',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<Noise opacity={0.08}>',
+  usage: `<section class="relative">\n  <Aurora />\n  <Noise opacity={0.1} />\n  <h2 class="relative">Grain over aurora</h2>\n</section>`,
+  props: [
+    { name: 'opacity', type: 'number', default: '0.08', description: 'Strength, 0–1. 0.04–0.12 reads as texture; more reads as static.' },
+    { name: 'animate', type: 'boolean', default: 'true', description: 'Flicker the grain by stepping its position at 12 fps.' },
+    { name: 'blend', type: "'overlay' | 'soft-light' | 'multiply' | 'screen' | 'normal'", default: "'overlay'", description: 'Blend mode against the layers beneath.' },
+    { name: 'size', type: 'number', default: '200', description: 'Tile size in px; smaller is finer grain.' },
+  ],
+  reducedMotion: 'The grain holds still.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'steps(6) over 500 ms: twelve grain frames a second, the cadence of film, and every frame is a translate, with no feTurbulence re-render.',
+    'The tile is stitched, so the seam never shows at any translate.',
+    'The grain is a layer 10% larger than the box on every side, clipped by the box: the translate never shows an edge, and the grain never reaches past the parent to widen the page.',
+    'overlay blend adds texture without shifting the colours beneath; soft-light is gentler, multiply darkens.',
+  ],
+  related: ['aurora', 'grid-pattern', 'dot-pattern'],
+  intents: ['noise overlay', 'film grain effect', 'grain texture css', 'noisy background'],
+  replaces: ['Noise (React Bits)', 'grainy gradient canvases'],
+  fixture: { expect: 'class="ma-noise"' },
+} satisfies ComponentMeta;

package/src/components/NumberFlow.astro

@@ -0,0 +1,143 @@
+---
+/**
+ * NumberFlow — digits roll to a new value. Every digit is a column of 0–9
+ * translated to the right row; the value lives in one custom property
+ * (--ma-nf-value) and each column derives its own digit from it with round()
+ * and mod(), so writing that property from your code rolls every column to
+ * its new digit on the preset spring, and leading columns collapse when the
+ * number gets shorter. No script of its own. The server also renders the
+ * value as text, which is what browsers without CSS math show.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'span'> {
+  /** Initial value, ≥ 0. Later values come from `--ma-nf-value` on the element or any ancestor. */
+  value: number;
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Integer columns to keep room for; leading zeros collapse, so this is headroom, not padding. */
+  digits?: number;
+  /** Decimal places, 0–4. */
+  decimals?: number;
+  /** Thousands separator. */
+  separator?: string;
+  /** Decimal mark. */
+  decimal?: string;
+  /** Text before the number. */
+  prefix?: string;
+  /** Text after the number. */
+  suffix?: string;
+  /** Roll duration in ms. Unset: the preset's --ma-duration. */
+  duration?: number;
+}
+
+const { value, as: Tag = 'span', digits = 1, decimals = 0, separator = ',', decimal = '.', prefix = '', suffix = '', duration, class: className, style, ...rest } = Astro.props;
+const places = Math.max(0, Math.min(decimals, 4));
+const abs = Math.max(0, value);
+const fixed = abs.toFixed(places);
+const [intPart, fracPart] = fixed.split('.');
+const intCols = Math.max(1, digits, intPart!.length);
+const label = `${prefix}${intPart!.replace(/\B(?=(\d{3})+(?!\d))/g, separator)}${fracPart ? decimal + fracPart : ''}${suffix}`;
+// column k shows the digit at 10^k of the value scaled to an integer (value × 10^decimals); highest first
+const cols = Array.from({ length: intCols + places }, (_, i) => intCols + places - 1 - i);
+const DIGITS = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+const vars = [`--ma-nf-init:${abs}`, `--ma-nf-scale:${10 ** places}`, duration !== undefined && `--ma-nf-dur:${duration}ms`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-nf', className]} data-value={abs} style={vars} {...rest}>
+  <span class="ma-nf__static">{label}</span>
+  <span class="ma-nf__digits" aria-hidden="true">
+    {prefix}
+    {cols.map((k) => {
+      const p = k - places;
+      return (
+        <>
+          {p === -1 && <span class="ma-nf__mark">{decimal}</span>}
+          <span class="ma-nf__col" data-lead={p > 0 ? '' : undefined} style={`--ma-nf-k:${10 ** k}`}>
+            <b class="ma-nf__strip">{DIGITS.map((d) => <i>{d}</i>)}</b>
+          </span>
+          {p > 0 && p % 3 === 0 && <span class="ma-nf__mark" data-lead style={`--ma-nf-k:${10 ** k}`}>{separator}</span>}
+        </>
+      );
+    })}
+    {suffix}
+  </span>
+</Tag>
+
+<style is:global>
+  @layer components {
+    :where(.ma-nf) {
+      display: inline-block;
+      font-variant-numeric: tabular-nums;
+      /* the live value: --ma-nf-value from your code or an ancestor, else the server's */
+      --ma-nf-v: var(--ma-nf-value, var(--ma-nf-init, 0));
+      --ma-nf-int: round(nearest, var(--ma-nf-v) * var(--ma-nf-scale, 1), 1);
+    }
+    /* the columns are presentation: not selectable, so a copy takes the value text instead of ten digits per column;
+       and a number reads left to right on a right-to-left page too, where the flex row put its columns back to front */
+    :where(.ma-nf__digits) {
+      display: none;
+      direction: ltr;
+      -webkit-user-select: none;
+      user-select: none;
+    }
+    /* the columns need round() and mod(); elsewhere the static text stays */
+    @supports (translate: calc(mod(round(down, 7, 1), 10) * 1em)) {
+      /* still the text a screen reader reads (and a copy copies): hidden from the eye only */
+      :where(.ma-nf__static) {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip-path: inset(50%);
+        white-space: nowrap;
+      }
+      :where(.ma-nf__digits) {
+        display: inline-flex;
+        align-items: baseline;
+      }
+    }
+    :where(.ma-nf__col),
+    :where(.ma-nf__mark) {
+      --ma-nf-hi: round(down, var(--ma-nf-int) / var(--ma-nf-k, 1), 1);
+    }
+    :where(.ma-nf__col) {
+      display: inline-block;
+      height: 1em;
+      line-height: 1;
+      clip-path: inset(0);
+      --ma-nf-d: mod(var(--ma-nf-hi), 10);
+    }
+    :where(.ma-nf__strip) {
+      display: grid;
+      font-weight: inherit;
+      translate: 0 calc(var(--ma-nf-d) * -1em);
+      transition: translate var(--ma-nf-dur, var(--ma-duration)) var(--ma-ease);
+    }
+    :where(.ma-nf__strip > i) {
+      display: block;
+      height: 1em;
+      line-height: 1;
+      font-style: normal;
+    }
+    /* leading columns (and the separator after them) collapse while the number is shorter */
+    :where(.ma-nf__col[data-lead]),
+    :where(.ma-nf__mark[data-lead]) {
+      max-width: calc(min(1, var(--ma-nf-hi)) * 2ch);
+      overflow: clip;
+      transition: max-width var(--ma-nf-dur, var(--ma-duration)) var(--ma-ease);
+    }
+    :where(.ma-nf__col[data-lead]) {
+      transition:
+        max-width var(--ma-nf-dur, var(--ma-duration)) var(--ma-ease),
+        translate var(--ma-nf-dur, var(--ma-duration)) var(--ma-ease);
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-nf__strip),
+      :where(.ma-nf__col[data-lead]),
+      :where(.ma-nf__mark[data-lead]) {
+        transition: none;
+      }
+    }
+  }
+</style>

package/src/components/NumberFlow.meta.ts

@@ -0,0 +1,42 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'NumberFlow',
+  slug: 'number-flow',
+  title: 'Number Flow',
+  description:
+    'A number whose digits roll to the new value when it changes. Each column slides to its digit on the preset spring, thousands separators stay put, and leading columns collapse when the number gets shorter. The value is one custom property your code writes; every column derives its digit from it with round() and mod(). No script of its own.',
+  summary: 'A number whose digits roll to the new value when it changes, keeping the thousands separators in place.',
+  category: 'data',
+  tier: 'A',
+  trigger: ['click'],
+  support: { baseline: 'newly', needs: ['css-math'], fallback: 'the value as plain text, updated only by a re-render' },
+  readout: '<NumberFlow value={1284}>',
+  usage: `<NumberFlow value={1284} id="stars" />\n<NumberFlow value={99.5} decimals={1} suffix="%" />\n\n<script>\n  // roll to a new value: write the property, keep the text honest (a screen reader reads it; an older browser shows it)\n  const n = document.getElementById('stars');\n  n.style.setProperty('--ma-nf-value', '1321');\n  n.querySelector('.ma-nf__static').textContent = '1,321';\n</script>`,
+  props: [
+    { name: 'value', type: 'number', description: 'Initial value, 0 or more. Later values are written to --ma-nf-value on the element (or an ancestor, which is how PriceSwitch drives it).' },
+    { name: 'as', type: 'HTMLTag', default: "'span'", description: 'Element to render.' },
+    { name: 'digits', type: 'number', default: '1', description: 'Integer columns to keep room for; leading zeros collapse, so a number that grows past the initial width still fits.' },
+    { name: 'decimals', type: 'number', default: '0', description: 'Decimal places, 0–4.' },
+    { name: 'separator', type: 'string', default: "','", description: 'Thousands separator.' },
+    { name: 'decimal', type: 'string', default: "'.'", description: 'Decimal mark.' },
+    { name: 'prefix', type: 'string', description: 'Text before the number, e.g. $.' },
+    { name: 'suffix', type: 'string', description: 'Text after the number, e.g. %.' },
+    { name: 'duration', type: 'number', default: 'preset (ui: 450)', description: 'Roll duration in ms; unset, the active preset\'s.' },
+  ],
+  reducedMotion: 'Digits change in place; nothing rolls.',
+  clientRouter: 'CSS-only; nothing to rebind. A value written before a navigation is not carried over unless the element is persisted.',
+  craft: [
+    'One custom property is the whole API. The column for 10^k shows mod(round(down, value / 10^k), 10): no script parses the number into digits, so the component can be driven by a radio and :has() as easily as by JavaScript.',
+    'Columns roll on the preset spring; with lively, the strip overshoots by a sliver of the next digit and settles, which is the detail number-flow libraries spend a spring on.',
+    'Leading columns collapse through max-width, and the separator after them collapses with them, so 1,284 rolling to 96 shrinks to two digits instead of showing 0,096.',
+    'Tabular figures and a fixed 1 em row: the number never jitters sideways while rolling and every column is exactly one digit tall.',
+    'The server renders the value as text as well; browsers without CSS math show that text and never a column of zeros. Everywhere else the same text is visually hidden, not removed: it is what a screen reader reads, so the columns stay aria-hidden and there is no aria-label on a span.',
+    'The columns take no selection (user-select: none), so selecting and copying the number copies the visually hidden text and never ten digits per column. They stay left to right on a right-to-left page, where a number still reads that way.',
+    'Rolls to the shorter path are not chosen: 9 → 0 rolls back through 8. Direction-aware rolling needs script, and the plain roll reads fine at one spring length.',
+  ],
+  related: ['count-up', 'price-switch', 'countdown-flip'],
+  intents: ['number flow', 'rolling digits', 'odometer number animation', 'animated counter on change', 'slot machine digits css', 'number transition'],
+  replaces: ['NumberFlow (number-flow, Motion Primitives)', 'AnimatedNumber (Skiper, motion.dev)'],
+  fixture: { props: { value: 1284 }, expect: 'ma-nf__static">1,284</span>' },
+} satisfies ComponentMeta;

package/src/components/Orb.astro

@@ -0,0 +1,130 @@
+---
+/**
+ * Orb — a sphere of light that breathes and slowly turns its colour. Three
+ * radial gradients on one element, already soft at their edges so no blur
+ * filter is ever painted; the breath is a `scale` on the compositor and
+ * the colour shift is one registered <number> (0 → 1) scaled to a drift
+ * angle the gradients add to their hue — animate the number, every stop follows. A conic highlight turns
+ * around the rim. Centred in its positioned parent.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Diameter, any CSS length. */
+  size?: string;
+  /** Base hue in degrees (oklch). */
+  hue?: number;
+  /** Degrees between the three stops; negative runs the other way around the wheel. */
+  spread?: number;
+  /** Chroma 0–0.3; low reads as haze, high as neon. */
+  chroma?: number;
+  /** Three colours that replace the hue-derived stops (then the hue does not drift). */
+  colors?: [string, string, string];
+  /** Breath amplitude as a fraction of the size, 0 keeps it still. */
+  pulse?: number;
+  /** Seconds per breath. */
+  duration?: number;
+  /** Degrees the hue drifts over a cycle; 0 pins it. */
+  drift?: number;
+  /** Opacity, 0–1. */
+  opacity?: number;
+}
+
+const { size = '18rem', hue = 250, spread = 40, chroma = 0.16, colors, pulse = 0.06, duration = 6, drift = 60, opacity = 1, class: className, style, ...rest } = Astro.props;
+const inline = [
+  `--ma-orb-size:${size}`,
+  `--ma-orb-hue:${hue}deg`,
+  `--ma-orb-spread:${spread}deg`,
+  `--ma-orb-chroma:${chroma}`,
+  `--ma-orb-pulse:${pulse}`,
+  `--ma-orb-dur:${duration}s`,
+  `--ma-orb-drift:${drift}deg`,
+  `--ma-orb-opacity:${opacity}`,
+  colors && `--ma-orb-c1:${colors[0]};--ma-orb-c2:${colors[1]};--ma-orb-c3:${colors[2]}`,
+  typeof style === 'string' ? style : '',
+]
+  .filter(Boolean)
+  .join(';');
+---
+
+<div class:list={['ma-orb', className]} aria-hidden="true" data-fixed={colors ? '' : undefined} style={inline} {...rest}></div>
+
+<style is:global>
+  /* the drift, 0 → 1, animated with literal keyframes: Firefox does not interpolate a registered property whose keyframe value is a var() (7C) */
+  @property --ma-orb-t {
+    syntax: '<number>';
+    inherits: false;
+    initial-value: 0;
+  }
+
+  @layer components {
+    :where(.ma-orb) {
+      position: absolute;
+      left: 50%;
+      top: 50%;
+      width: var(--ma-orb-size, 18rem);
+      height: var(--ma-orb-size, 18rem);
+      translate: -50% -50%;
+      border-radius: 50%;
+      pointer-events: none;
+      opacity: var(--ma-orb-opacity, 1);
+      /* the live hue offset: the drift scaled by the animated number */
+      --ma-orb-h: calc(var(--ma-orb-t) * var(--ma-orb-drift, 60deg));
+      --ma-orb-l: calc(72% - 14% * var(--ma-dark, 0));
+      --ma-orb-s1: var(--ma-orb-c1, oklch(var(--ma-orb-l) var(--ma-orb-chroma, 0.16) calc(var(--ma-orb-hue, 250deg) + var(--ma-orb-h))));
+      --ma-orb-s2: var(--ma-orb-c2, oklch(calc(var(--ma-orb-l) - 10%) var(--ma-orb-chroma, 0.16) calc(var(--ma-orb-hue, 250deg) + var(--ma-orb-spread, 40deg) + var(--ma-orb-h))));
+      --ma-orb-s3: var(--ma-orb-c3, oklch(calc(var(--ma-orb-l) - 22%) var(--ma-orb-chroma, 0.16) calc(var(--ma-orb-hue, 250deg) + var(--ma-orb-spread, 40deg) * 2 + var(--ma-orb-h))));
+      background:
+        radial-gradient(circle at 32% 30%, color-mix(in oklch, var(--ma-orb-s1) 90%, white) 0%, transparent 46%),
+        radial-gradient(circle at 70% 68%, var(--ma-orb-s3) 0%, transparent 55%),
+        radial-gradient(circle at 50% 50%, var(--ma-orb-s2) 0%, color-mix(in oklch, var(--ma-orb-s2) 50%, transparent) 55%, transparent 72%);
+      will-change: scale;
+      animation:
+        ma-orb-breathe var(--ma-orb-dur) var(--ma-ease-in-out) infinite alternate,
+        ma-orb-hue calc(var(--ma-orb-dur) * 4) var(--ma-ease-in-out) infinite alternate;
+    }
+    :where(.ma-orb[data-fixed]) {
+      animation-name: ma-orb-breathe;
+    }
+    /* the rim: a soft conic highlight turning around the sphere */
+    :where(.ma-orb)::after {
+      content: '';
+      position: absolute;
+      inset: 6%;
+      border-radius: inherit;
+      background: conic-gradient(from 0deg, transparent 0 55%, color-mix(in oklch, var(--ma-orb-s1) 55%, white) 72%, transparent 88%);
+      mask-image: radial-gradient(circle, transparent 60%, #000 74%, transparent 84%);
+      opacity: 0.7;
+      will-change: rotate;
+      animation: ma-orb-rim calc(var(--ma-orb-dur) * 3) linear infinite;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-orb),
+      :where(.ma-orb)::after {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-orb-breathe {
+    from {
+      scale: 1;
+    }
+    to {
+      scale: calc(1 + var(--ma-orb-pulse, 0.06));
+    }
+  }
+  @keyframes ma-orb-hue {
+    from {
+      --ma-orb-t: 0;
+    }
+    to {
+      --ma-orb-t: 1;
+    }
+  }
+  @keyframes ma-orb-rim {
+    to {
+      rotate: 360deg;
+    }
+  }
+</style>

package/src/components/Orb.meta.ts

@@ -0,0 +1,39 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Orb',
+  slug: 'orb',
+  title: 'Orb',
+  description: 'A sphere of light that breathes and slowly turns its colour. Three radial gradients on one element, soft at their edges so no blur filter is ever painted; the breath is a scale on the compositor and the colour shift is one registered number scaled to a drift angle every gradient adds to its hue. A conic highlight turns around the rim. Zero JS; centred in its positioned parent.',
+  summary: 'A glowing orb that breathes and slowly shifts its colour, drawn with gradients and no blur filter.',
+  category: 'background',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'newly', needs: ['property'], fallback: 'the sphere breathes; the hue does not drift' },
+  readout: '<Orb hue={250} pulse={0.06}>',
+  usage: `<section class="relative grid min-h-[32rem] place-items-center">\n  <Orb hue={250} size="24rem" />\n  <form class="relative">…</form>\n</section>`,
+  props: [
+    { name: 'size', type: 'string', default: "'18rem'", description: 'Diameter, any CSS length.' },
+    { name: 'hue', type: 'number', default: '250', description: 'Base hue in degrees (oklch).' },
+    { name: 'spread', type: 'number', default: '40', description: 'Degrees between the three stops; the second and third sit one and two spreads along the wheel, the other way when negative.' },
+    { name: 'chroma', type: 'number', default: '0.16', description: 'Chroma 0–0.3; low reads as haze, high as neon.' },
+    { name: 'colors', type: '[string, string, string]', description: 'Three colours replacing the hue-derived stops; the hue then does not drift.' },
+    { name: 'pulse', type: 'number', default: '0.06', description: 'Breath amplitude as a fraction of the size; 0 keeps it still.' },
+    { name: 'duration', type: 'number', default: '6', description: 'Seconds per breath; the hue drifts over four breaths, the rim turns in three.' },
+    { name: 'drift', type: 'number', default: '60', description: 'Degrees the hue wanders over a cycle; 0 pins it.' },
+    { name: 'opacity', type: 'number', default: '1', description: 'Strength, 0–1.' },
+  ],
+  reducedMotion: 'A still sphere at its base hue.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'No filter: blur() on a large element is a full-size paint every frame; gradients that are already soft cost nothing to move.',
+    'One registered <number>, 0 → 1 with literal keyframes, is the whole colour animation: scaled by the drift and added to the hue of the three oklch stops, so the sphere turns through the wheel without a second layer and without hue-rotate(). Literal, because Firefox does not interpolate a registered property whose keyframe value is a var().',
+    'Lightness follows the theme through the --ma-dark scalar: a lighter sphere on a light ground, a deeper one on dark.',
+    'The rim is a conic highlight under a ring mask, rotating on the compositor. It is the one detail that makes a flat gradient read as a sphere.',
+    'Breath runs on the in-out curve with alternate direction, so the sphere shrinks as well as grows.',
+  ],
+  related: ['aurora', 'particles', 'ripple'],
+  intents: ['glowing orb background', 'breathing orb', 'ai orb animation', 'gradient sphere hero', 'siri orb css'],
+  replaces: ['Orb (React Bits)', 'Orb (Kokonut UI)'],
+  fixture: { expect: 'class="ma-orb"' },
+} satisfies ComponentMeta;