spin — a name, not a cursor

Pure CSS, flat, DevTools-friendly. Every frame of the spinner renders ONCE in the SAME grid cell with white-space: pre — no element churn, no JS clock; JS only fills the animation parameters (one shared keyframes rule per parameter set + a negative per-frame delay phasing it into its slot), so the cycle is compositor-smooth, scrub/pause/replay-able in the DevTools Animations panel, and freezes on frame 0 under prefers-reduced-motion through a static media kill — zero JS in the reduced-motion path. The box never breathes: a slow blank frame (simpleDots' three spaces) holds the widest frame's advance width.

Reduced motion, two named channels. SMIL-animated loaders freeze through root.pauseAnimations() driven by the component's live matchMedia('(prefers-reduced-motion: reduce)') listener — frozen means the first frame (blocks-wave's resting 3×3 grid), and un-reducing restarts the clock. CSS-keyframed loaders ride the second channel: spin.css's static animation: none kill scoped to [data-jx-spin-svg]. The channels are documented, never conflated — a custom loader chooses its engine by how its artwork is written.

Independent instance timelines. SMIL syncbase references resolve by element id ACROSS THE DOCUMENT — duplicate ids across instances used to cross-wire (a freshly switched-to loader resolved its begin chains onto another instance's long-past timeline and froze until a lucky re-insertion). Every instance now namespaces its ids at render (id, .begin/.end refs, gradient url(#…)): each syncbase graph is self-contained, unmount-safe, and independently phased — the deterministic transform rides RAW-gated payload only; artifact bytes stay verbatim.

Native SMIL timelines. The svg lane's clock is the engine's own: SSR'd loaders animate from HTML parse (motion by ~0.6s, before hydration), swapped instances from insertion (~80ms) — the component never touches the clock, so hydration cannot snap a running loader back to its resting pose.

Custom svg spinners come from @jixoai/ui-vite-plugin's spinners feature: opt in with jixoai({ spinners }), name your svg files, and the plugin regenerates the committed artifact — the shipped @jixoai/spin-set stays a plain inline module with zero npm deps, so the DEFAULT artifact installs plugin-free either way.

// vite.config.ts — @jixoai/ui-vite-plugin's spinners feature
import { jixoai, defineSpinnerChannel } from '@jixoai/ui-vite-plugin';
import { magecdn } from '@jixoai/ui-vite-plugin/spinners/magecdn';
import { sam } from '@jixoai/ui-vite-plugin/spinners/svg-loaders';

export default {
  plugins: [
    jixoai({
      // bare {} = the vendored blocks-wave only. Custom loaders ride
      // either lane — a CHANNEL (an id + prefix + its own record, the
      // icon channel contract; entries join as prefix:name keys) or
      // the flat record (kebab or prefix:name keys; explicit beats
      // channels and built-ins, the icons override law)
      spinners: {
        channels: [
          // your own channel — the public factory validates shape +
          // grammar; one channel per prefix is enforced at config time
          defineSpinnerChannel({
            id: 'myco',
            prefix: 'myco',
            spinners: {
              'cadence': '<svg …>…</svg>',        // inline literal
              'wave-loader': { file: './src/loaders/wave.svg' },
            },
          }),
          // a pack as a channel — pick is a filter over the 94
          magecdn({ pick: ['clock', 'bars-scale'] }),
          // SamHerbert's 12 under the sam: prefix
          sam(),
        ],
        spinners: {
          'flat-loader': { file: './src/loaders/flat.svg' },
          'myco:cadence': '<svg …>…</svg>', // same FULL name overrides the channel entry
        },
      },
    }),
  ],
};

// then regenerate the committed artifact (the repo's single writer):
//   npm run gen:spins
// <Spin spinner="myco:cadence" />, <Spin spinner="magecdn:clock" />,
// <Spin spinner="sam:tail-spin" /> — all type-check and render; the
// SpinName union closes with the artifact, so a typo is a compile
// error exactly like the text lane.