@moonarc/core 0.1.0

package/src/lib/form.ts

@@ -0,0 +1,231 @@
+/**
+ * @moonarc/core/form — a form that really sends, with JavaScript and
+ * without it.
+ *
+ *   bindForms()   bind every form[data-ma-form] now and after every
+ *                 ClientRouter navigation (the runtime's onMount). Call it
+ *                 from a section or layout script; a second call is a no-op.
+ *                 Returns the unregister function.
+ *
+ * Without JS the form posts natively (method="post" + action); nothing is
+ * hidden behind a script. With it, one submit listener on the form itself
+ * (target phase, so it runs before VanishInput's and the router's listeners
+ * on document, which read defaultPrevented) calls preventDefault() and reads
+ * the FormData before any await, then posts to data-endpoint (else the
+ * action) with Accept: application/json. Only method="post" is taken over,
+ * except a demo form.
+ *
+ *   data-ma-form-status   id of a role="status" node present at load (required)
+ *   data-endpoint         the fetch URL; the action otherwise
+ *   data-encode           multipart (default, the FormData) | urlencoded | json
+ *   data-success          navigate here after success
+ *   data-carry            response keys copied into the record, space-separated
+ *   data-ref-param        URL parameter copied into the field of that name, or appended
+ *   data-ma-form-demo     no request: success after the animations, this JSON as the response
+ *   data-msg-pending · -done · -exists · -error · -429 · -offline   the status texts
+ *                         (429 and offline fall back to error, exists to done)
+ *
+ * State on the form: data-pending while waiting, then data-state done |
+ * exists | error. While pending, and while done or exists without
+ * navigation, the submit buttons carry aria-disabled (not disabled: the
+ * focus stays on them) and the form novalidate, and a second submit is
+ * ignored — prevented and stopped before anything on document sees it —
+ * until a field changes; the author's novalidate comes back after. Events
+ * on the form, bubbling: ma:form-done (detail: the response object, or {})
+ * and ma:form-error (detail: { status }, 0 when offline); exists sends
+ * neither.
+ *
+ * Success is a 2xx whose JSON body, if any, is not ok: false; 409 or
+ * status: 'exists' is exists. On success with a same-origin data-success,
+ * sessionStorage['ma:form'] = { path, at, ...carried } is written just
+ * before navigating: path is the destination's pathname, and a carried value
+ * passes only as a number or [A-Za-z0-9_-]{1,32}, so an email never does.
+ * Navigation, and the restore after a failure, wait for the finite
+ * animations inside the form (a vanish; never the infinite shimmer), with a
+ * fallback from --ma-duration and --ma-stagger-tight because animations do
+ * not run in a hidden tab. A failure puts each text value back only into a
+ * field that is still empty and focuses the first rendered one that held
+ * text (a hidden honeypot before it is skipped). Texts from the service
+ * are never shown: they cannot be translated. Back from the bfcache the form
+ * starts over: no state, no lock, no status text; a form that was submitted
+ * is also reset() — every control back to its markup, so the field the
+ * vanish emptied is no longer :user-invalid (?ref is filled in again) — while
+ * one never submitted, or refilled after a failure, keeps what the visitor
+ * typed. Zero dependencies.
+ */
+import { onMount, type Cleanup } from './runtime';
+
+type Field = HTMLInputElement | HTMLTextAreaElement;
+
+/** A value that may leave the form: a number, or a short token — never an email, never free text. */
+const safe = (v: unknown): v is string | number => typeof v == 'number' || (typeof v == 'string' && /^[\w-]{1,32}$/.test(v));
+
+const sleep = (ms?: number) => new Promise((r) => setTimeout(r, ms));
+
+/** The next task (the vanish starts in a listener on document, after ours), then the form's finite animations or the token fallback. */
+async function settle(form: HTMLFormElement, chars: number): Promise<void> {
+  await sleep();
+  const style = getComputedStyle(form);
+  // a time token in ms; 0 when the base tokens are not on the page
+  const ms = (name: string) => {
+    const v = style.getPropertyValue(name);
+    return (parseFloat(v) || 0) * (v.includes('ms') ? 1 : 1000);
+  };
+  await Promise.race([
+    Promise.allSettled(
+      form
+        .getAnimations({ subtree: true })
+        .filter((a) => a.effect?.getComputedTiming().endTime != Infinity)
+        .map((a) => a.finished),
+    ),
+    sleep(2 * ms('--ma-duration') + chars * ms('--ma-stagger-tight')),
+  ]);
+}
+
+const FALLBACK: Record<string, string> = { 429: 'error', offline: 'error', exists: 'done' };
+const JSON_TYPE = 'application/json';
+
+let off: Cleanup | undefined;
+
+export function bindForms(): Cleanup {
+  off ??= onMount<HTMLFormElement>('form[data-ma-form]', (form, { signal }) => {
+    const attr = (name: string) => form.getAttribute(name);
+    const data = form.dataset;
+    const status = document.getElementById(attr('data-ma-form-status')!);
+    const novalidate = form.noValidate;
+    // 0 ready · 1 pending · 2 done or exists (submits ignored until a field changes) · 3 leaving
+    let state = 0;
+
+    // the last text asked for: shown, or about to be
+    let text = '';
+    const say = (key: string) => {
+      const was = text;
+      text = attr('data-msg-' + key) ?? attr('data-msg-' + FALLBACK[key]) ?? '';
+      if (!status) return;
+      // the same text again is emptied for two frames first (as CopyButton does), so it is announced again; a newer text wins
+      if (text == was) {
+        status.textContent = '';
+        requestAnimationFrame(() => requestAnimationFrame(() => (status.textContent ||= text)));
+      } else status.textContent = text;
+    };
+    const lock = (on: boolean) => {
+      for (const b of form.elements) if ((b as HTMLButtonElement).type == 'submit') on ? b.setAttribute('aria-disabled', 'true') : b.removeAttribute('aria-disabled');
+      form.noValidate = on || novalidate;
+    };
+    const ready = () => {
+      state = 0;
+      lock(false);
+      delete data['state'];
+      delete data['pending'];
+    };
+    const fire = (type: string, detail: unknown) => form.dispatchEvent(new CustomEvent(type, { bubbles: true, detail }));
+
+    // ?ref=… into the field of that name (netlify renders one), else appended at submit
+    const refName = attr('data-ref-param');
+    const ref = refName && new URLSearchParams(location.search).get(refName);
+    const refField = refName ? (form.elements.namedItem(refName) as HTMLInputElement | null) : null;
+    const fillRef = () => {
+      if (refField && safe(ref)) refField.value = ref;
+    };
+    fillRef();
+
+    form.addEventListener(
+      'submit',
+      async (e) => {
+        const demo = attr('data-ma-form-demo');
+        if (demo == null && !/^post$/i.test(attr('method')!)) return;
+        e.preventDefault();
+        if (state) return e.stopPropagation();
+        const body = new FormData(form, e.submitter);
+        if (!refField && safe(ref)) body.append(refName!, ref);
+        const saved = [...form.elements].filter((f): f is Field => /^(text|email|search|url|tel|textarea)$/.test((f as Field).type)).map((f) => [f, f.value] as const);
+        state = 1;
+        delete data['state'];
+        data['pending'] = '';
+        lock(true);
+        say('pending');
+
+        let reply: Record<string, unknown> = {};
+        let code = 200;
+        let key: string;
+        try {
+          if (demo != null) reply = JSON.parse(demo || '{}');
+          else {
+            const encode = attr('data-encode');
+            const r = await fetch(attr('data-endpoint') || attr('action') || '', {
+              method: 'POST',
+              headers: encode == 'json' ? { Accept: JSON_TYPE, 'Content-Type': JSON_TYPE } : { Accept: JSON_TYPE },
+              body: encode == 'json' ? JSON.stringify(Object.fromEntries(body)) : encode == 'urlencoded' ? new URLSearchParams(body as unknown as string[][]) : body,
+              signal,
+            });
+            code = r.status;
+            const json = await r.json().catch(() => 0);
+            if (json && typeof json == 'object') reply = json;
+          }
+          key = code == 409 || reply['status'] == 'exists' ? 'exists' : code > 199 && code < 300 && reply['ok'] !== false ? 'done' : code == 429 ? '429' : 'error';
+        } catch {
+          key = 'offline';
+          code = 0;
+        }
+
+        await settle(form, saved.reduce((n, [, v]) => n + v.length, 0));
+        if (signal.aborted) return;
+        delete data['pending'];
+        say(key);
+
+        if (key == 'done' || key == 'exists') {
+          state = 2;
+          data['state'] = key;
+          if (key == 'exists') return;
+          fire('ma:form-done', reply);
+          const success = attr('data-success');
+          if (!success) return;
+          state = 3;
+          await settle(form, 0);
+          if (signal.aborted) return;
+          const url = new URL(success, location.href);
+          if (url.origin == location.origin) {
+            const record: Record<string, unknown> = { path: url.pathname, at: Date.now() };
+            for (const k of attr('data-carry')?.split(' ') ?? []) if (!(k in record) && safe(reply[k])) record[k] = reply[k];
+            try {
+              sessionStorage.setItem('ma:form', JSON.stringify(record));
+            } catch {}
+          }
+          lock(false);
+          state = 2;
+          return location.assign(url);
+        }
+
+        ready();
+        data['state'] = 'error';
+        for (const [f, v] of saved) f.value ||= v;
+        // the first field that held text and is rendered: never a honeypot (empty, display: none) before it
+        saved.find(([f, v]) => v && f.getClientRects().length)?.[0].focus();
+        fire('ma:form-error', { status: code });
+      },
+      { signal },
+    );
+
+    form.addEventListener('input', () => state == 2 && ready(), { signal });
+    addEventListener(
+      'pageshow',
+      (e) => {
+        if (!e.persisted) return;
+        // a submitted form starts over: reset() also clears the user validity of the field the vanish emptied, which
+        // :user-invalid would otherwise paint as an error once data-state is gone. A form never submitted (or refilled
+        // after a failure) is state 0 and keeps what the visitor typed.
+        if (state) {
+          form.reset();
+          fillRef();
+        }
+        ready();
+        if (status) status.textContent = '';
+      },
+      { signal },
+    );
+  });
+  return () => {
+    off?.();
+    off = undefined;
+  };
+}

package/src/lib/geo.ts

@@ -0,0 +1,77 @@
+/**
+ * Geography shared by DottedMap (server) and Globe (server + client):
+ * the land-mask lookup, the unit-sphere and equirectangular projections, and
+ * the row sampling that turns a lat/lng mask into evenly spread dots. No
+ * data here — `land.ts` holds the mask and is imported on the server only;
+ * Globe ships a downsampled copy of it as data in its HTML and decodes it
+ * with `maskAt` below, so the client bundle carries these few lines and
+ * never the mask.
+ */
+
+export interface Marker {
+  lat: number;
+  lng: number;
+  label?: string;
+}
+
+/** One bit per cell in a base64 string, row-major from the north-west corner; `w × h` cells over the whole globe. */
+export interface Mask {
+  w: number;
+  h: number;
+  bits: Uint8Array;
+}
+
+export const decode = (b64: string, w: number, h: number): Mask => ({ w, h, bits: Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)) });
+
+/** True when the cell containing lat/lng is land. */
+export function maskAt(m: Mask, lat: number, lng: number): boolean {
+  const col = ((Math.floor(((lng + 180) / 360) * m.w) % m.w) + m.w) % m.w;
+  const row = Math.min(m.h - 1, Math.max(0, Math.floor(((90 - lat) / 180) * m.h)));
+  const k = row * m.w + col;
+  return (m.bits[k >> 3]! >> (k & 7)) & 1 ? true : false;
+}
+
+/** lat/lng in degrees → a point on the unit sphere, y up, z toward the viewer at lng 0. */
+export function toSphere(lat: number, lng: number): [number, number, number] {
+  const la = (lat * Math.PI) / 180;
+  const lo = (lng * Math.PI) / 180;
+  const c = Math.cos(la);
+  return [c * Math.sin(lo), Math.sin(la), c * Math.cos(lo)];
+}
+
+/** lat/lng → percent of an equirectangular map (0…100 across, 0…100 down). */
+export const toMap = (lat: number, lng: number): [number, number] => [((lng + 180) / 360) * 100, ((90 - lat) / 180) * 100];
+
+/**
+ * Rows of dots `step` degrees apart in latitude, with the columns per row
+ * scaled by cos(lat) so the dots stay evenly spaced on the sphere instead of
+ * crowding at the poles. Yields the land cells only; a step of 0 or less
+ * yields none (it would never leave the loop, and the page would hang).
+ */
+export function landRows(m: Mask, step: number, south = -90, north = 90): Array<[number, number]> {
+  const out: Array<[number, number]> = [];
+  for (let lat = north - step / 2; step > 0 && lat > south; lat -= step) {
+    const cols = Math.max(1, Math.round((360 / step) * Math.cos((lat * Math.PI) / 180)));
+    for (let i = 0; i < cols; i++) {
+      const lng = -180 + ((i + 0.5) * 360) / cols;
+      if (maskAt(m, lat, lng)) out.push([lat, lng]);
+    }
+  }
+  return out;
+}
+
+/** The 1° mask reduced to `step`-degree cells (a cell is land when its centre is). */
+export function downsample(m: Mask, step: number): { w: number; h: number; b64: string } {
+  const w = Math.round(360 / step);
+  const h = Math.round(180 / step);
+  const bits = new Uint8Array(Math.ceil((w * h) / 8));
+  for (let row = 0; row < h; row++) {
+    for (let col = 0; col < w; col++) {
+      if (maskAt(m, 90 - (row + 0.5) * step, -180 + (col + 0.5) * step)) {
+        const k = row * w + col;
+        bits[k >> 3]! |= 1 << (k & 7);
+      }
+    }
+  }
+  return { w, h, b64: btoa(String.fromCharCode(...bits)) };
+}

package/src/lib/gsap.ts

@@ -0,0 +1,58 @@
+/**
+ * @moonarc/core/gsap — GSAP that survives <ClientRouter />.
+ *
+ * The recurring failure: tweens and ScrollTriggers created on page one keep
+ * running against detached nodes after a swap, pin-spacers pile up, and
+ * ScrollTrigger positions are measured against the old layout. GSAP already
+ * has the right primitive — gsap.context() + revert() — this adapter runs it
+ * on the Astro lifecycle and refreshes ScrollTrigger when layout is real.
+ *
+ * `gsap` is passed in, never imported: core stays dependency-free and the
+ * consumer keeps one GSAP instance.
+ */
+import { onPage, type Cleanup } from './runtime';
+
+/** The slice of GSAP this adapter touches — structural, so no type dependency on `gsap`. */
+export interface GsapLike {
+  context(func: (self: unknown) => void, scope?: Element | string): { revert(): void };
+}
+export interface ScrollTriggerLike {
+  refresh(safe?: boolean): void;
+}
+
+export interface GsapPageOptions {
+  /** Scope passed to gsap.context(): selector text inside `setup` resolves within it. */
+  scope?: Element | string;
+  /** Pass ScrollTrigger to recalculate positions after each navigation and once web fonts settle. */
+  scrollTrigger?: ScrollTriggerLike | null;
+  /** Skip the document.fonts.ready refresh. @default false */
+  noFontRefresh?: boolean;
+}
+
+/**
+ * Run `setup` once per page view inside `gsap.context()`, and revert it —
+ * tweens, ScrollTriggers, pin-spacers, inline styles — before the next swap.
+ * Works on pages without the router too. Returns an unregister function.
+ */
+export function gsapPage<G extends GsapLike>(
+  gsap: G,
+  setup: (self: Parameters<Parameters<G['context']>[0]>[0]) => void,
+  options: GsapPageOptions = {},
+): Cleanup {
+  return onPage(({ signal }) => {
+    const ctx = gsap.context(setup as (self: unknown) => void, options.scope);
+    const st = options.scrollTrigger;
+    if (st) {
+      // Positions depend on layout: measure after first paint, and again when web fonts settle.
+      requestAnimationFrame(() => {
+        if (!signal.aborted) st.refresh();
+      });
+      if (!options.noFontRefresh && 'fonts' in document) {
+        document.fonts.ready.then(() => {
+          if (!signal.aborted) st.refresh();
+        });
+      }
+    }
+    return () => ctx.revert();
+  });
+}

package/src/lib/land.ts

@@ -0,0 +1,11 @@
+/**
+ * Land bitmask, 1° cells, 360 × 180 — generated by scripts/build-land.mjs from
+ * Natural Earth 1:110m land (public domain). Row 0 is latitude 90…89 N, column 0 is
+ * longitude −180…−179; bit k = row × 360 + col, little-endian within each byte.
+ * 21538 land cells (33.2 %). Imported on the server only —
+ * DottedMap draws a path from it, Globe sends a downsampled copy as data in its HTML.
+ * Do not edit; rerun the script.
+ */
+export const LAND_W = 360;
+export const LAND_H = 180;
+export const LAND = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADg/wEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADA/v8/AOD//z8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD+///D/////5//AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPAH/j/+//////8PAAAAgB0AAHgAAAAAAD8AAAAAAAAAAAAAAAAAAAAAAAAAAOD//wP8//////8BAACAfx4AAAAAAAAAAP4AAAAAAAAAAAAAAAAAAAAAAAA4+I73//n///////8AAAAAfwAAAAAAAAAAAAAfAAAAAAAAAAAAAAAAAAAAAOAQACDwP4D///////8BAAAAPAQAAAAAAAAAAAAYAAAAAAAAAAAAAAAAAAAAADzAgPP5H8D//////38AAAAAAAAAAAAA4AEAAAD+DwAAAAAAAAAAAAAAAAAAAIC/g7PfBwAA/v////8AAAAAAAAAAADgBwAAwP//PwAA4B8AAAAAAAAAAAAAAAAMAAD8AgAA+P////8AAAAAAAAAAABwAAAA/P//AwAAAAAAAAAAAAAAAAAAAP8Ahvc5OwAA8P///38AAAAAAAAAAAAcAADg////34cHAAcAAAAAAAAAAAAAgN9/xzf8RwAA4P///z8AAAAAAAAAAAAPAB7g//////8fgB8AAAAAAQAAAAAAAO//B3f8/wsA4P///z8AAAAAAAAAAAAPAG////////8f2f8HAAAAAAD4HwAAAAD8H/D4/38A4P///xMAAAAAAPAHAAAAgN//////////////DwAAAAD+///h/4//H+/Bg/8BwP7//w8AAAAAwP8fAAAAj9///////////////88/AeD///////8DB8TPB/4AAP///wAAAAAA8P//AwDjf77/////////////////DwD////////////vh/kPwP//BwAAAAAA/P//H/P//5//////////////////34H8////////////Afw/gP//AQAAAAAA/v+fH////+///////////////////vD///////////9fAPwYgP8PAOA/AAAA/+N/8P//////////////////////QID4///////////Pw/0DAP8HAMAfAACA//F//v////////////////////8/AAP4///////////BBPAHAP4HAAAAAADg//z///////////////////////9/AID///////////8AQ8ABAPwBAAAAAAD8P/7///////////////////////9fAMD//////////z8AwA8AAPgBAAAAAAD+H/7/////////////////////Of8BAID///z//////z8AwD8AAMABAAAAAAD+P/z///////////////////9/wH8AAAD8MwD//////x8AwH8MAAAAAAAAAAD+P2D///////////////////95cAAAAACAAwD8/////38AwP8eAAAAAAAAgAGcH/D//////////////////wEAOAAAAADADgDA/////38AgP8/AAAAAAAAwANAH/T//////////////////wAAfgAAAAAwAAAA//////8PgP8/AAAAAAAAwAFwD/7/////////////////PwAAfwAAAAAGAAAA//////8/wP//AAAAAAAAwAOwA/7/////////////////DwCAPwAAAIAAAAAA/v//////8///BwAAAAAAOAcgcP//////////////////HwAAHwAAAAAAAACA+P//////4///DwAAAAAAOA74/////////////////////wUADwAAAAAAAAAA8P//////4///DwAAAAAAGD///////////////////////wUAAwAAAAAAAAAA8P//////7///FwAAAAAAAB///////////////////////wUAAgAAAAAAAAAA0P//////////DAAAAAAAgOH//////////////////////w0AAAAAAAAAAAAAYP////////8xLAAAAAAAAPz//////////////////////wwAAAAAAAAAAAAAAP7//////38HfgAAAAAAgP///////////////////////wQAAAAAAAAAAAAAAP3///////8HUAAAAAAAAP7/////////////////////fwQAAAAAAAAAAAAAAP////////+XAAAAAAAAAPz///93/D/+////////////PwwAAAAAAAAAAAAAAP////////9/AAAAAAAAAPj//f9j/g/+////////////HwAAAAAAAAAAAAAAAP////////8MAAAAAAAAAPj/+P8B/Mf/////////////DwQAAAAAAAAAAAAAAP///////z8AAAAAAAAAcPzH8/8A8I//////////////Bx4AAAAAAAAAAAAAAP///////x8AAAAAAAAA+H+Aw/8AwA/+//////////9/AA8AAAAAAAAAAAAAAP///////x8AAAAAAAAA+D8Aj//w4R/8//////////8/AAAAAAAAAAAAAAAAAP///////wMAAAAAAAAA+B8wuE/+/z/+/////////98fAAMAAAAAAAAAAAAAAP///////wMAAAAAAAAA+A8wEMf//x/+/////////0cOAAMAAAAAAAAAAAAAAP7//////wEAAAAAAAAA+A8AAI7//x/8/////////wMOAAEAAAAAAAAAAAAAAP7//////wAAAAAAAAAA+AcABob//z/8/////////zccwAEAAAAAAAAAAAAAAPz//////wAAAAAAAAAAQOB/AAQ2/////////////x8c8AEAAAAAAAAAAAAAAPj//////wAAAAAAAAAAQPx/AAAA/////////////w8Y/gEAAAAAAAAAAAAAAPD/////fwAAAAAAAAAA4P8/AAAA/////////////w+EGwAAAAAAAAAAAAAAAMD/////HwAAAAAAAAAA8P9/AACA/////////////x/AAwAAAAAAAAAAAAAAAID/////DwAAAAAAAAAA+P//BwaA/////////////x/AAAAAAAAAAAAAAAAAAID9////BwAAAAAAAAAA/P//D3+E/////////////z9AAAAAAAAAAAAAAAAAAAD5////BwAAAAAAAAAA/P//f////////////////x8AAAAAAAAAAAAAAAAAAADy/x8GBgAAAAAAAAAA/P/////v/8///////////z8AAAAAAAAAAAAAAAAAAAD0/w8ABgAAAAAAAAAA/v////+//4///////////z8AAAAAAAAAAAAAAAAAAADu/wcADgAAAAAAAACA//////8f/x/+/////////x8AAAAAAAAAAAAAAAAAAACI/wcALAAAAAAAAADA//////8//z/g/////////w8AAAAAAAAAAAAAAAAAAACQ/wcACAAAAAAAAADg//////9//r+A/////////wcAAAAAAAAAAAAAAAAAAAAQ/wMAAAAAAAAAAADg//////9//n8cgP///////ycAAAAAAAAAAAAAAAAAAAAA/gMAAAAAAAAAAADw////////+P9/AP///////xEAAAAAAAAAAAAAAAAAAAAA/AMAHQAAAAAAAADw////////+P//APz/f///fxAAAAAAAAAAAAAAAAAAAAAA+AcAYAAAAAAAAAD4////////+f9/APz/B///BgAAAAAAAAAAAAAAAAAAAAAA/AccgAEAAAAAAADw////////8f9/AOD/B/5/AAAAAAAAAAAAAAAAAQAAAAAA+A8eADgAAAAAAADw////////4f8/AOD/Afw/BgAAAAAAAAAAAAAAAAAAAAAA8J8PAPwCAAAAAADw////////4/8fAOD/APw/AgAAAAAAAAAAAAAAAAAAAAAAgP8PAAAAAAAAAADw////////x/8HAOB/APx/ADAAAAAAAAAAAAAAAAAAAAAAAP4PAAAAAAAAAAD4////////h/8BAOA/APz/ADAAAAAAAAAAAAAAAAAAAAAAAID/AAAAAAAAAAD4////////j/8AAMAPAMD/ATAAAAAAAAAAAAAAAAAAAAAAAAD/AQAAAAAAAAD4////////nx8AAMAPAMD/ATAAAAAAAAAAAAAAAAAAAAAAAAD8AAAAAAAAAAD4////////vwcAAIAPAMD/AcAAAAAAAAAAAAAAAAAAAAAAAADgAQAAAAAAAAD4////////fwAAAIAPAMD8AQABAAAAAAAAAAAAAAAAAAAAAADAAAgAAAAAAADw////////f2AAAAAPAID4AUACAAAAAAAAAAAAAAAAAAAAAADAAe9TAAAAAADg/////////34AAAAPAEBwAAgAAAAAAAAAAAAAAAAAAAAAAAAAE+9/AAAAAADA/////////38AAAAXAEAgAAQCAAAAAAAAAAAAAAAAAAAAAAAAz///AAAAAACA/////////z8AAAASAMAAAIACAAAAAAAAAAAAAAAAAAAAAAAAyP//AQAAAACA/////////z8AAAAwAIAAAEAHAAAAAAAAAAAAAAAAAAAAAAAAgP//AwAAAAAA/v///////x8AAAAwAAADAAMBAAAAAAAAAAAAAAAAAAAAAAAAwP//fwAAAAAA/A/+/////x8AAAAAAAAHAAcAAAAAAAAAAAAAAAAAAAAAAAAAgP///wAAAAAAEAD8/////w8AAAAAADAGwAcAAAAAAAAAAAAAAAAAAAAAAAAAgP///wEAAAAAAADA/////wcAAAAAAGAG4AEAAAAAAAAAAAAAAAAAAAAAAAAA4P///wEAAAAAAADA/////wMAAAAAAMAM+AMAAAAAAAAAAAAAAAAAAAAAAAAA4P///wMAAAAAAADg/////wEAAAAAAIAL/gMQAAAAAAAAAAAAAAAAAAAAAAAA8P///wMAAAAAAADg////fwAAAAAAAIAH/vMQAAAAAAAAAAAAAAAAAAAAAAAA8P///wcAAAAAAADg////PwAAAAAAAAAP/gMAAQAAAAAAAAAAAAAAAAAAAAAA+P///38AAAAAAADg////PwAAAAAAAAAO/DmAAwAAAAAAAAAAAAAAAAAAAAAA+P///38BAAAAAADA////HwAAAAAAAAA+/DkA8gAAAAAAAAAAAAAAAAAAAAAA8P////8fAAAAAACA////DwAAAAAAAAA8wChE/gcAAAAAAAAAAAAAAAAAAAAA+P////8/AAAAAACA////BwAAAAAAAAA4AEAA8B8AAAAAAAAAAAAAAAAAAAAA+P//////AQAAAAAA////BwAAAAAAAAAwAEAAxD8NAAAAAAAAAAAAAAAAAAAA+P//////AQAAAAAA////BwAAAAAAAADAAQAAxP+AAAAAAAAAAAAAAAAAAAAA8P//////AQAAAAAA/v//BwAAAAAAAACAHwAAwH8ABAAAAAAAAAAAAAAAAAAA4P//////AQAAAAAA/v//BwAAAAAAAAAAQFYEAMcAAAAAAAAAAAAAAAAAAAAA4P//////AAAAAAAA/v//DwAAAAAAAAAAAAgBAIABMAAAAAAAAAAAAAAAAAAAwP//////AAAAAAAA/v//DwAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAgP////9/AAAAAAAA/P//DwAAAAAAAAAAAAAAAQQAAAAAAAAAAAAAAAAAAAAAgP////8/AAAAAAAA/v//HyAAAAAAAAAAAACAHwQAAAAAAAAAAAAAAAAAAAAAAP////8fAAAAAAAA/v//HyAAAAAAAAAAAADADwwAAAAAAAAAAAAAAAAAAAAAAP////8fAAAAAAAA////HzAAAAAAAAAAAADsDxwAAAAAAAAAAAAAAAAAAAAAAP7///8fAAAAAAAA////DzgAAAAAAAAAAAD/DxwAAAAAAAAAAAAAAAAAAAAAAPj///8fAAAAAAAA////Dz8AAAAAAAAAAAD/Pz4AAAiAAAAAAAAAAAAAAAAAAOD///8fAAAAAAAA////Ax8AAAAAAAAAAMD//z4AAABAAAAAAAAAAAAAAAAAAMD///8PAAAAAAAA////AB8AAAAAAAAAAMD//z8AAAAAAAAAAAAAAAAAAAAAAMD///8PAAAAAAAA/v9/AB8AAAAAAAAAAOD//38AAAAAAAAAAAAAAAAAAAAAAMD///8PAAAAAAAA/v9/AB8AAAAAAAAAAPz///8BAAEAAAAAAAAAAAAAAAAAAMD///8HAAAAAAAA/P9/gA8AAAAAAAAAgP////8BAAIAAAAAAAAAAAAAAAAAAMD///8DAAAAAAAA/P//gA8AAAAAAAAAwP////8DAAAAAAAAAAAAAAAAAAAAAMD//38AAAAAAAAA/P9/AA8AAAAAAAAAwP////8HAAAAAAAAAAAAAAAAAAAAAOD//x8AAAAAAAAA+P9/AAcAAAAAAAAA4P////8PAAAAAAAAAAAAAAAAAAAAAOD//w8AAAAAAAAA+P8fAAIAAAAAAAAAwP////8fAAAAAAAAAAAAAAAAAAAAAOD//wcAAAAAAAAA+P8fAAAAAAAAAAAA4P////8fAAAAAAAAAAAAAAAAAAAAAOD//wcAAAAAAAAA+P8fAAAAAAAAAAAAwP////8fAAAAAAAAAAAAAAAAAAAAAOD//wcAAAAAAAAA8P8PAAAAAAAAAAAAgP////8/AAAAAAAAAAAAAAAAAAAAAOD//wMAAAAAAAAA4P8HAAAAAAAAAAAAgP////8fAAAAAAAAAAAAAAAAAAAAAPD//wMAAAAAAAAA4P8HAAAAAAAAAAAAgP////8fAAAAAAAAAAAAAAAAAAAAAPD//wEAAAAAAAAAwP8DAAAAAAAAAAAAAP////8fAAAAAAAAAAAAAAAAAAAAAOD//wAAAAAAAAAAwP8BAAAAAAAAAAAAAP8D/P8PAAAAAAAAAAAAAAAAAAAAAPD/fwAAAAAAAAAAwH8AAAAAAAAAAAAAgP8A2P8HAAAAAAAAAAAAAAAAAAAAAPD/OwAAAAAAAAAAgAEAAAAAAAAAAAAAAAcA6P8HAAAAAAAAAAAAAAAAAAAAAPj/BwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAwP8DAAACAAAAAAAAAAAAAAAAAPj/BwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP8DAAAEAAAAAAAAAAAAAAAAAPz/BwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP8DAAAIAAAAAAAAAAAAAAAAAPj/AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGgAAAA4AAAAAAAAAAAAAAAAAPg/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAcAAAAAAAAAAAAAAAAAPw/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAYAAAAAAAAAAAAAAAAAPwHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAOAAAAALAAAAAAAAAAAAAAAAAPwfAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAOAAAIADAAAAAAAAAAAAAAAAAPgHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAMABAAAAAAAAAAAAAAAAAPwHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAHAAAAAAAAAAAAAAAAAAAP4BAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAHgAAAAAAAAAAAAAAAAAAP4BAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAAAAAAAAAAAAAAAAAAAP4DAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP8BAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP8AAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAH4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAH6AAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPADAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAAAAAAAAAAAAAAAAAAAAAAAAAOAAAAAAAAAAAAAAAAAIAfAAAAAAAeeADADwAAAAAAAAAAAAAAAAAAAAAAAAAHAAAAAAAAAAAAAAAAAPD/AADA/////////z8AAAAAAAAAAAAAAAAAAAAAAAAHAAAAAAAAAAAAAAAAgP///wH4//////////8DAAAAAAAAAAAAAAAAAAAAADAfAAAAAAAAAAAAAADw8////wP+////////////AwAAAAAAAAAAAAAAAAAAAHA/AAAAAAAAAAA8//P//////+D/////////////HwAAAAAAAAAAAAAAAAAAAP5+AAAAAAAA5v////////////D//////////////38AAAAAAAAAAAAAAAAAAAB+AAAAAACA/////////////////////////////38AAAAAAAAAYAYA4ON/OPh/AAAAAADw/////////////////////////////x8AAAAAAADwv/MXgP////8fAAAAAADw/////////////////////////////wMAAAAAAPz///////////8HAAAAAAD+/////////////////////////////wAAAAAAAPz//////////z8AAAAAAP///////////////////////////////wAAAADA/////////////wEAAAAA8P///////////////////////////////wAAAACH////////////PwAAAPgA/////////////////////////////////wcAAAAcgP//////////fwAAAP4BwP//////////////////////////////HwAAAAAAAP7//////////wf8wD8AwP//////////////////////////////DwAAAAAA/v////////////8HAAD4////////////////////////////////HwAAAAAA+P//////////////4f///////////////////////////////////wAAAAAA/P///////////////////////////////////////////////////x8A3x8AAP7///////////////////////////////////////////////////8/////f///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////';

package/src/lib/lenis.ts

@@ -0,0 +1,112 @@
+/**
+ * @moonarc/core/lenis — Lenis that survives <ClientRouter />.
+ *
+ * Three parties touch scroll on a routed Astro site: Lenis, the router's
+ * scroll restoration, and (often) ScrollTrigger. Nobody coordinates them.
+ * Measured on Astro 7.3.2 with Lenis 1.3.26 (2026-09-25, docs/claims-evidence.md):
+ * a navigation while Lenis is still easing leaves the next page at the old
+ * page's target, and a Lenis created on every astro:page-load adds an
+ * instance per navigation. This adapter creates Lenis once, keeps it for the
+ * life of the document, drives it from gsap.ticker when asked, and after
+ * every swap stops a running animation and resyncs Lenis to the position the
+ * router set.
+ *
+ * Call it once, from a layout script.
+ */
+
+export interface LenisLike {
+  raf(time: number): void;
+  resize(): void;
+  scrollTo(target: number, options?: { immediate?: boolean; force?: boolean }): void;
+  on(event: 'scroll', handler: (lenis: unknown) => void): void;
+  destroy(): void;
+}
+
+export interface LenisPageOptions {
+  /** Drive Lenis from gsap.ticker (seconds → ms) and disable lag smoothing, per GSAP's guidance. */
+  gsap?: {
+    ticker: {
+      add(cb: (time: number) => void): void;
+      remove(cb: (time: number) => void): void;
+      lagSmoothing(threshold: number): void;
+    };
+  };
+  /** Keep ScrollTrigger in step with Lenis' scroll position. */
+  scrollTrigger?: { update(): void };
+}
+
+export interface LenisHandle<L> {
+  /** The live instance (created on first call if needed). */
+  get(): L;
+  /** Tear everything down — tests and HMR; not needed on navigation. */
+  destroy(): void;
+}
+
+/** The two router events a resync runs on. */
+const EVENTS = ['astro:after-swap', 'astro:page-load'];
+
+export function lenisPage<L extends LenisLike>(create: () => L, options: LenisPageOptions = {}): LenisHandle<L> {
+  let lenis: L | null = null;
+  let tick: ((time: number) => void) | null = null;
+  let rafId = 0;
+
+  // After a swap the router has already scrolled the window (top, or the
+  // restored position), but a wheel animation from the previous page may still
+  // be running and would carry the new page to its old target. An immediate
+  // scrollTo stops it. It runs before resize(), because Lenis 1.3's resize()
+  // already moves the target to the window's position, and a scrollTo to the
+  // target Lenis already has returns early. A restored position past the
+  // previous page's limit gets clamped, so it is set again after resize().
+  // The swap also replaced <html>'s classes with the next page's, and Lenis
+  // writes its own (`lenis`, `lenis-smooth`, `lenis-stopped`) only when its
+  // state changes, at the next scroll, so they are written again here.
+  // updateClassName() is Lenis' own (1.3.26, private in its types); a Lenis
+  // without it keeps the classes it had before, missing until that scroll.
+  const resync = () => {
+    if (!lenis) return;
+    const y = scrollY;
+    const now = { immediate: true, force: true };
+    lenis.scrollTo(y, now);
+    lenis.resize();
+    if (scrollY !== y) lenis.scrollTo(y, now);
+    (lenis as unknown as { updateClassName?(): void }).updateClassName?.();
+  };
+
+  const init = () => {
+    if (lenis) return;
+    lenis = create();
+    const st = options.scrollTrigger;
+    if (st) lenis.on('scroll', () => st.update());
+    const g = options.gsap;
+    if (g) {
+      tick = (time) => lenis?.raf(time * 1000);
+      g.ticker.add(tick);
+      g.ticker.lagSmoothing(0);
+    } else {
+      const loop = (time: number) => {
+        lenis?.raf(time);
+        rafId = requestAnimationFrame(loop);
+      };
+      rafId = requestAnimationFrame(loop);
+    }
+    for (const e of EVENTS) document.addEventListener(e, resync);
+  };
+
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', init, { once: true });
+  else init();
+
+  return {
+    get() {
+      init();
+      return lenis as L;
+    },
+    destroy() {
+      if (!lenis) return;
+      for (const e of EVENTS) document.removeEventListener(e, resync);
+      if (tick) options.gsap?.ticker.remove(tick);
+      cancelAnimationFrame(rafId);
+      lenis.destroy();
+      lenis = null;
+    },
+  };
+}

package/src/lib/meta.ts

@@ -0,0 +1,79 @@
+/**
+ * Component metadata — one typed record per component, next to its .astro
+ * file. Drives the docs pages, the registry, llms.txt, the MCP catalogue and
+ * the site's filter facets, so the same facts are never written twice.
+ */
+
+import type { FeatureKey } from './support';
+
+export type Tier = 'A' | 'B' | 'C';
+
+/** Ten categories: five were too coarse once the catalogue passed a dozen entries; `data` arrived with the number and chart primitives. */
+export type Category = 'scroll' | 'text' | 'data' | 'loop' | 'pointer' | 'background' | 'ui' | 'loading' | 'transition' | 'section';
+
+/** What sets the motion off. A component can have several. */
+export type Trigger = 'scroll' | 'hover' | 'pointer' | 'load' | 'click' | 'always';
+
+/**
+ * Browser support, stated instead of assumed. `widely` = every engine for
+ * more than a release cycle; `newly` = every engine, recently; `limited` =
+ * not every engine, and `fallback` says what those browsers get.
+ */
+export interface Support {
+  baseline: 'widely' | 'newly' | 'limited';
+  /** Platform features the motion depends on; versions come from lib/support.ts. */
+  needs: FeatureKey[];
+  /** What a browser without `needs` shows. Required when baseline is not `widely`. */
+  fallback?: string;
+}
+
+export interface PropMeta {
+  name: string;
+  type: string;
+  default?: string;
+  description: string;
+}
+
+export interface ComponentMeta {
+  /** File and export name, e.g. `Reveal`. */
+  name: string;
+  /** URL slug, e.g. `reveal`. */
+  slug: string;
+  /** Human title, e.g. `Scroll Reveal`. */
+  title: string;
+  /** One paragraph, plain, for cards and search. */
+  description: string;
+  /** One sentence of 120 characters at most: what it is, in the words someone searching for it would use. The site's
+   * meta description and share card print it, followed by the measured cost; no cost or support claim goes in it
+   * (docs/seo.md). */
+  summary: string;
+  category: Category;
+  tier: Tier;
+  trigger: Trigger[];
+  support: Support;
+  /** The one line that makes it, printed under the live tile: `<Reveal stagger={60}>`. */
+  readout: string;
+  /** Usage snippet for the docs page (the body under the import). */
+  usage: string;
+  props: PropMeta[];
+  /** What the component does under prefers-reduced-motion. */
+  reducedMotion: string;
+  /** How it behaves across <ClientRouter /> navigation. */
+  clientRouter: string;
+  /** Craft notes: the easing/duration reasoning an agent should repeat. */
+  craft: string[];
+  /** Slugs of related components. */
+  related: string[];
+  /** Search intents this component answers, for search_motion. */
+  intents: string[];
+  /** Which React-world components this replaces, for the migration table. */
+  replaces: string[];
+  /** How the budget harness renders it: props, default-slot text, and the string the server HTML must contain. */
+  fixture?: {
+    props?: Record<string, unknown>;
+    slot?: string;
+    expect?: string;
+    /** Optional-prop variants measured on their own fixture page (phase 7D): `morph` → `c/Dialog--morph`, budget key `Dialog.morph`. Props are merged over the default fixture's. */
+    variants?: Record<string, { props?: Record<string, unknown>; slot?: string; expect?: string }>;
+  };
+}