@moonarc/core 0.1.0

package/src/lib/support.ts

@@ -0,0 +1,102 @@
+/**
+ * Browser support table for every platform feature a component leans on.
+ * Versions are the first stable release per engine, read from
+ * @mdn/browser-compat-data 8.1.1 on 2026-09-12, three rows on 2026-09-14 and
+ * four more for phase 7B, one for 7C (backdrop-filter), four for 7D (match-element, vertical range, grid-row animation, interestfor) the same day and seven for 7E on 2026-09-16 (user-invalid, base-select, picker, sibling-index, field-sizing, the switch attribute, SVG backdrop filters — the last measured, not in BCD), two for 7F the same day (relative colour, contrast-color), and on 2026-09-28 two corrected (css-math split from abs(), display in keyframes) and three added (the exponential functions, view-transition-class, dialog closedby) (`docs/browser-support.md` records the audits). `false` means not shipped; the component's meta then
+ * states what that browser shows instead.
+ *
+ * Kept in the package so the site, llms.txt and the MCP server print the same
+ * numbers, and so "0 B" is never claimed for something that runs in one engine.
+ */
+
+export interface Feature {
+  /** Short label for a chip. */
+  label: string;
+  chrome: number | false;
+  firefox: number | false;
+  safari: number | false;
+}
+
+export const features = {
+  'scroll-timeline': { label: 'animation-timeline: scroll() / view()', chrome: 115, firefox: false, safari: 26 },
+  'starting-style': { label: '@starting-style', chrome: 117, firefox: 129, safari: 17.5 },
+  'allow-discrete': { label: 'transition-behavior: allow-discrete', chrome: 117, firefox: 129, safari: 17.4 },
+  'details-content': { label: '::details-content', chrome: 131, firefox: 143, safari: 18.4 },
+  'scroll-marker': { label: '::scroll-marker / ::scroll-button()', chrome: 135, firefox: false, safari: false },
+  property: { label: '@property', chrome: 85, firefox: 128, safari: 16.4 },
+  has: { label: ':has()', chrome: 105, firefox: 121, safari: 15.4 },
+  popover: { label: 'popover attribute', chrome: 114, firefox: 125, safari: 17 },
+  anchor: { label: 'anchor positioning', chrome: 125, firefox: 147, safari: 26 },
+  command: { label: 'command / commandfor', chrome: 135, firefox: 144, safari: 26.2 },
+  'details-name': { label: 'details name=', chrome: 120, firefox: 130, safari: 17.2 },
+  'counter-style': { label: '@counter-style pad', chrome: 91, firefox: 33, safari: 17 },
+  'view-transitions': { label: 'same-document view transitions', chrome: 111, firefox: 144, safari: 18 },
+  'scroll-snap': { label: 'scroll-snap', chrome: 69, firefox: 99, safari: 11 },
+  'bg-clip-text': { label: 'background-clip: text', chrome: 120, firefox: 49, safari: 14 },
+  /* BCD css.properties.display.keyframe_animatable; measured 2026-09-28: Firefox 155 ignores display in keyframes (the box stays) */
+  'display-animation': { label: 'display in @keyframes', chrome: 116, firefox: false, safari: 18 },
+  'font-variation': { label: 'variable font axes', chrome: 62, firefox: 62, safari: 11 },
+  'mask-image': { label: 'mask-image', chrome: 120, firefox: 53, safari: 15.4 },
+  dialog: { label: '<dialog>', chrome: 37, firefox: 98, safari: 15.4 },
+  /* BCD html.elements.dialog.closedby (2026-09-28; Safari has it in Technology Preview only). Listed, not needed: in Safari
+     Dialog, StaggerMenu and Lightbox still close on Escape and their close button, Drawer on Escape and its drag, and
+     CommandPalette closes on a backdrop click by script, so no component puts it in `needs`. */
+  closedby: { label: 'dialog closedby', chrome: 134, firefox: 141, safari: false },
+  'css-math': { label: 'mod() / round() in calc()', chrome: 125, firefox: 118, safari: 15.4 },
+  /* abs() and sign() reached Chrome thirteen releases after mod() and round() (BCD css.types.abs, css.types.sign);
+     listed, not used: the components that need an absolute value square it or take max(x, -x) */
+  'css-abs': { label: 'abs() / sign() in calc()', chrome: 138, firefox: 118, safari: 15.4 },
+  /* the exponential family (BCD css.types.hypot, pow, sqrt, exp, log: one release each), for AnimatedBeam's hypot() */
+  'css-exp': { label: 'hypot() / pow() / sqrt() in calc()', chrome: 120, firefox: 118, safari: 15.4 },
+  'clip-path': { label: 'clip-path basic shapes', chrome: 55, firefox: 54, safari: 13.1 },
+  'mask-composite': { label: 'mask-composite', chrome: 120, firefox: 53, safari: 15.4 },
+  'container-units': { label: 'container query units (cqw / cqh)', chrome: 105, firefox: 110, safari: 16 },
+  'counter-set': { label: 'counter-set', chrome: 85, firefox: 68, safari: 17.2 },
+  'timeline-scope': { label: 'timeline-scope', chrome: 116, firefox: false, safari: 26 },
+  'd-path': { label: 'd: path() as a CSS property', chrome: 52, firefox: 97, safari: false },
+  clipboard: { label: 'navigator.clipboard.writeText', chrome: 66, firefox: 63, safari: 13.1 },
+  'backdrop-filter': { label: 'backdrop-filter', chrome: 76, firefox: 103, safari: 18 },
+  /* Chrome-only; listed so the audit prints it, not needed by any component (StatefulButton bounds its width from the label length instead). */
+  'interpolate-size': { label: 'interpolate-size: allow-keywords', chrome: 129, firefox: false, safari: false },
+  /* phase 7D */
+  'match-element': { label: 'view-transition-name: match-element', chrome: 137, firefox: 144, safari: 18.4 },
+  /* BCD css.properties.view-transition-class, for PillNav (2026-09-28) */
+  'vt-class': { label: 'view-transition-class', chrome: 125, firefox: 144, safari: 18.2 },
+  'range-vertical': { label: 'vertical <input type=range> (writing-mode)', chrome: 124, firefox: 120, safari: 16.5 },
+  'grid-rows-animation': { label: 'animatable grid-template-rows', chrome: 107, firefox: 66, safari: 16 },
+  /* Chrome-only; listed as the proposed C route for LinkPreview (a hover-intent popover with no script), not used. */
+  interestfor: { label: 'interestfor (interest invokers)', chrome: 142, firefox: false, safari: false },
+  /* phase 7F (BCD 8.1.1, 2026-09-16): the theme contract. Neither is needed by a section — the static scale and the tested
+     foreground colours are what a browser without them gets — so they are listed for the audit and the theming docs. */
+  'relative-color': { label: 'oklch(from …) relative colour', chrome: 122, firefox: 128, safari: 18 },
+  'contrast-color': { label: 'contrast-color()', chrome: 147, firefox: 146, safari: 26 },
+  /* phase 7E (BCD 8.1.1, 2026-09-16) */
+  'user-invalid': { label: ':user-valid / :user-invalid', chrome: 119, firefox: 88, safari: 16.5 },
+  'base-select': { label: 'appearance: base-select (customizable select)', chrome: 135, firefox: false, safari: 27 },
+  picker: { label: '::picker(select) / ::checkmark', chrome: 135, firefox: false, safari: 27 },
+  'sibling-index': { label: 'sibling-index()', chrome: 138, firefox: 154, safari: 26.2 },
+  'field-sizing': { label: 'field-sizing: content', chrome: 123, firefox: 152, safari: 26.2 },
+  /* Safari-only; Switch sets the attribute but never depends on it (appearance: none draws the control everywhere). */
+  'switch-attr': { label: '<input type=checkbox switch>', chrome: false, firefox: false, safari: 17.4 },
+  /* not in BCD; measured on the LiquidGlass fixture in three engines (docs/phase-7e.md): Chromium only. */
+  'backdrop-svg': { label: 'backdrop-filter: url(#svg-filter)', chrome: 76, firefox: false, safari: false },
+  /* FluidField: WebGL2 contexts; float render targets (EXT_color_buffer_float) are checked at runtime */
+  webgl2: { label: 'WebGL2', chrome: 56, firefox: 51, safari: 15 },
+} as const satisfies Record<string, Feature>;
+
+export type FeatureKey = keyof typeof features;
+
+/** `Chrome 115 · Safari 26 · not Firefox` — one line for chips and llms.txt. */
+export function supportLine(keys: readonly FeatureKey[]): string {
+  if (keys.length === 0) return 'every browser';
+  const need = keys.map((k) => features[k]);
+  const min = (b: 'chrome' | 'firefox' | 'safari') => need.reduce<number | false>((acc, f) => (acc === false || f[b] === false ? false : Math.max(acc, f[b])), 0);
+  const parts: string[] = [];
+  const c = min('chrome');
+  const f = min('firefox');
+  const s = min('safari');
+  parts.push(c === false ? 'not Chrome' : `Chrome ${c}`);
+  parts.push(f === false ? 'not Firefox' : `Firefox ${f}`);
+  parts.push(s === false ? 'not Safari' : `Safari ${s}`);
+  return parts.join(' · ');
+}

package/src/lib/theme.ts

@@ -0,0 +1,18 @@
+/**
+ * The anti-flash theme script, as a string: ThemeScript inlines it in <head>
+ * so the resolved theme is on <html> before the first frame, and the site's
+ * stage prints its byte size. Written compact on purpose — inline scripts
+ * are not minified. The contract ThemeToggle relies on:
+ *
+ *   localStorage[key]          'system' | 'light' | 'dark' (the choice)
+ *   html[data-theme]           the resolved theme, 'light' | 'dark'
+ *   html[data-theme-choice]    the choice
+ *   window.__maTheme           { choice(), apply(), set(choice) }
+ *
+ * The attributes are re-applied after every ClientRouter swap (the router
+ * replaces <html>'s attributes) and when the OS scheme changes.
+ */
+export function themeScript(key = 'ma-theme'): string {
+  const k = key.replace(/[^\w-]/g, '');
+  return `(function(){var K='${k}',r=document.documentElement,m=matchMedia('(prefers-color-scheme: dark)');function g(){try{return localStorage.getItem(K)||'system'}catch(e){return 'system'}}function a(){var c=g();r.dataset.theme=c==='system'?(m.matches?'dark':'light'):c;r.dataset.themeChoice=c}window.__maTheme={choice:g,apply:a,set:function(c){try{localStorage.setItem(K,c)}catch(e){}a()}};a();document.addEventListener('astro:after-swap',a);m.addEventListener('change',a)})()`;
+}

package/src/lib/toast.ts

@@ -0,0 +1,17 @@
+/**
+ * toast() — raise a notification in the page's <Toast /> region.
+ * Dispatches `ma:toast` on document; the region listens through the runtime,
+ * so this works after every navigation and costs nothing on pages without a
+ * region.
+ */
+export interface ToastOptions {
+  title: string;
+  description?: string;
+  /** Lifetime in ms; defaults to the region's duration. */
+  duration?: number;
+}
+
+export function toast(options: ToastOptions | string): void {
+  const detail: ToastOptions = typeof options === 'string' ? { title: options } : options;
+  document.dispatchEvent(new CustomEvent('ma:toast', { detail }));
+}

package/src/styles/base.css

@@ -0,0 +1,218 @@
+/*
+ * @moonarc/core — base tokens (motion.theme).
+ *
+ * Injected on every page by the integration (or imported manually). Every rule
+ * is wrapped in :where() so it has zero specificity: a consumer overrides any
+ * token with a plain `:root { --ma-foo: … }` and never needs !important.
+ *
+ * Cascade layers. Tailwind v4 puts utilities in @layer utilities, and any
+ * unlayered stylesheet beats a layered one regardless of specificity — so a
+ * library that ships unlayered CSS can never be overridden by `class="p-0"`.
+ * Declaring Tailwind's own order here (harmless without Tailwind) and putting
+ * tokens in `theme` and component rules in `components` means: consumer
+ * utilities, consumer classes, and consumer scoped styles always win; the
+ * library only beats resets (`base`).
+ *
+ * Presets. No component hard-codes a curve, a duration, a travel distance or
+ * a stagger; everything resolves from the six tokens under "active preset".
+ * Five presets ship — snap · ui · gentle · lively · ambient — each a
+ * mass-spring-damper sampled into linear() (stiffness/damping in the comment)
+ * with its settle time as the duration. Switching the whole page is one
+ * attribute: <html data-ma-preset="lively">. Any subtree can carry its own.
+ *
+ * Colour tokens follow the three-state rule:
+ *   1. light is the base definition — never define a colour only in a media query
+ *   2. system-dark applies unless the page has explicitly chosen light
+ *   3. explicit dark wins in both directions, via [data-theme] or .dark
+ */
+
+@layer theme, base, components, utilities;
+
+@layer theme {
+  :where(:root) {
+    /* springs, sampled — stiffness / damping, mass 1 */
+    --ma-ease-snap: linear(0, 0.013 1.7%, 0.046 3.3%, 0.092 5%, 0.447 15%, 0.599 20%, 0.718 25%, 0.805 30%, 0.884 36.7%, 0.961 50%, 1); /* 1218 / 70 */
+    --ma-ease-ui: linear(0, 0.008 1.7%, 0.029 3.3%, 0.099 6.7%, 0.525 21.7%, 0.675 28.3%, 0.786 35%, 0.879 43.3%, 0.971 61.7%, 1); /* 305 / 33 */
+    --ma-ease-gentle: linear(0, 0.008 1.7%, 0.03 3.3%, 0.101 6.7%, 0.486 20%, 0.645 26.7%, 0.764 33.3%, 0.865 41.7%, 0.956 56.7%, 1); /* 110 / 20 */
+    --ma-ease-lively: linear(0, 0.056 1.7%, 0.201 3.3%, 0.402 5%, 0.839 8.3%, 1.027 10%, 1.171 11.7%, 1.267 13.3%, 1.314 15%, 1.317 16.7%, 1.285 18.3%, 1.23 20%, 1.024 25%, 0.97 26.7%, 0.93 28.3%, 0.906 30%, 0.898 31.7%, 0.902 33.3%, 1.016 43.3%, 1.032 46.7%, 0.99 63.3%, 1); /* 622 / 17 */
+    --ma-ease-ambient: linear(0, 0.01 1.7%, 0.038 3.3%, 0.077 5%, 0.5 18.3%, 0.631 23.3%, 0.733 28.3%, 0.831 35%, 0.919 45%, 1); /* 43 / 13 */
+    --ma-dur-snap: 290ms;
+    --ma-dur-ui: 450ms;
+    --ma-dur-gentle: 760ms;
+    --ma-dur-lively: 840ms;
+    --ma-dur-ambient: 1390ms;
+
+    /* fixed curves — exits and continuous motion never use a spring */
+    --ma-ease-out: cubic-bezier(0.23, 1, 0.32, 1);
+    --ma-ease-in: cubic-bezier(0.5, 0, 0.75, 0);
+    --ma-ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
+    --ma-ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
+    --ma-ease-spring: var(--ma-ease-lively);
+
+    /* scale */
+    --ma-stagger-tight: 40ms;
+    --ma-stagger-base: 60ms;
+    --ma-stagger-relaxed: 120ms;
+    --ma-travel-hover: 4px;
+    --ma-travel-enter: 24px;
+    --ma-travel-section: 48px;
+    --ma-duration-fast: 150ms;
+    --ma-duration-slow: 700ms;
+
+    /* active preset: ui */
+    --ma-preset: ui;
+    --ma-ease: var(--ma-ease-ui);
+    --ma-duration: var(--ma-dur-ui);
+    --ma-stagger: var(--ma-stagger-base);
+
+    /* colour — light base */
+    --ma-shine: rgb(255 255 255 / 0.85);
+    --ma-glow: rgb(0 0 0 / 0.1);
+    --ma-scrim: rgb(255 255 255 / 0.72);
+    --ma-edge: rgb(0 0 0 / 0.08);
+    --ma-ink: rgb(0 0 0 / 0.9);
+    --ma-panel: rgb(255 255 255 / 0.92);
+    /* secondary text (a hint, a time, an inactive tab) is --ma-ink at this opacity: the lowest that keeps 4.5 : 1 on the
+       panel and on a tinted surface in the light theme (0.55 read 4.0). Decoration may go fainter; text may not. */
+    --ma-dim: 0.7;
+    /* 0 on a light ground, 1 on a dark one — a scalar for calc(), so a component can lean lighter or darker with the theme */
+    --ma-dark: 0;
+  }
+
+  /* presets — on <html> or any subtree */
+  :where([data-ma-preset='snap']) {
+    --ma-preset: snap;
+    --ma-ease: var(--ma-ease-snap);
+    --ma-duration: var(--ma-dur-snap);
+    --ma-stagger: var(--ma-stagger-tight);
+    --ma-travel-enter: 16px;
+    --ma-travel-hover: 2px;
+  }
+  :where([data-ma-preset='ui']) {
+    --ma-preset: ui;
+    --ma-ease: var(--ma-ease-ui);
+    --ma-duration: var(--ma-dur-ui);
+    --ma-stagger: var(--ma-stagger-base);
+    --ma-travel-enter: 24px;
+    --ma-travel-hover: 4px;
+  }
+  :where([data-ma-preset='gentle']) {
+    --ma-preset: gentle;
+    --ma-ease: var(--ma-ease-gentle);
+    --ma-duration: var(--ma-dur-gentle);
+    --ma-stagger: var(--ma-stagger-base);
+    --ma-travel-enter: 24px;
+    --ma-travel-hover: 3px;
+  }
+  :where([data-ma-preset='lively']) {
+    --ma-preset: lively;
+    --ma-ease: var(--ma-ease-lively);
+    --ma-duration: var(--ma-dur-lively);
+    --ma-stagger: var(--ma-stagger-tight);
+    --ma-travel-enter: 32px;
+    --ma-travel-hover: 6px;
+  }
+  :where([data-ma-preset='ambient']) {
+    --ma-preset: ambient;
+    --ma-ease: var(--ma-ease-ambient);
+    --ma-duration: var(--ma-dur-ambient);
+    --ma-stagger: var(--ma-stagger-relaxed);
+    --ma-travel-enter: 48px;
+    --ma-travel-hover: 4px;
+  }
+
+  /* system dark, unless the page has explicitly chosen light */
+  @media (prefers-color-scheme: dark) {
+    :where(:root:not([data-theme='light']):not(.light)) {
+      --ma-shine: rgb(255 255 255 / 0.32);
+      --ma-glow: rgb(255 255 255 / 0.14);
+      --ma-scrim: rgb(10 10 12 / 0.72);
+      --ma-edge: rgb(255 255 255 / 0.1);
+      --ma-ink: rgb(255 255 255 / 0.92);
+      --ma-panel: rgb(24 24 27 / 0.94);
+      --ma-dark: 1;
+    }
+  }
+
+  /* explicit dark wins in both directions, and supports both conventions */
+  :where(:root[data-theme='dark'], :root.dark) {
+    --ma-shine: rgb(255 255 255 / 0.32);
+    --ma-glow: rgb(255 255 255 / 0.14);
+    --ma-scrim: rgb(10 10 12 / 0.72);
+    --ma-edge: rgb(255 255 255 / 0.1);
+    --ma-ink: rgb(255 255 255 / 0.92);
+    --ma-panel: rgb(24 24 27 / 0.94);
+    --ma-dark: 1;
+  }
+}
+
+/*
+ * Same-document view transitions the library starts itself (Dialog morph,
+ * Lightbox, FilterGrid — lib/morph.ts). For their duration <html> carries
+ * data-ma-vt, and these rules give the root snapshots a plain cross-fade on
+ * the tokens. The attribute specificity outranks Curtain's zero-specificity
+ * root rules, so a morph on a page with a Curtain never opens an iris; the
+ * mask and clip Curtain's blinds and pixels set are cleared as well.
+ */
+@layer components {
+  /* The text a split, rolled or counted component is made of, for assistive tech: the animated parts are aria-hidden,
+     this is the string once. Not aria-label on the wrapper — a span, div or p may not be named that way (ARIA 1.2),
+     and screen readers skip it. user-select: none keeps a copied heading from carrying the text twice. */
+  :where(.ma-sr) {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    user-select: none;
+  }
+  :where(:root)[data-ma-vt]::view-transition-old(root),
+  :where(:root)[data-ma-vt]::view-transition-new(root) {
+    animation-duration: var(--ma-duration);
+    animation-timing-function: var(--ma-ease-out);
+    animation-fill-mode: both;
+    animation-direction: normal;
+    mix-blend-mode: plus-lighter;
+    mask-image: none;
+    clip-path: none;
+  }
+  :where(:root)[data-ma-vt]::view-transition-old(root) {
+    animation-name: ma-vt-out;
+  }
+  :where(:root)[data-ma-vt]::view-transition-new(root) {
+    animation-name: ma-vt-in;
+  }
+  :where(:root)[data-ma-vt]::view-transition-group(*) {
+    animation-duration: var(--ma-duration);
+    animation-timing-function: var(--ma-ease);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    :where(:root)[data-ma-vt]::view-transition-old(root),
+    :where(:root)[data-ma-vt]::view-transition-new(root),
+    :where(:root)[data-ma-vt]::view-transition-group(*) {
+      animation-duration: var(--ma-duration-fast);
+      animation-timing-function: linear;
+    }
+  }
+}
+
+/* While the library runs a transition of its own, elements named through Astro's transition:name step out of it: a
+   catalogue of a hundred named stages is not captured for one morphing dialog. Unlayered on purpose: Astro writes its
+   [data-astro-transition-scope="…"] rules into the page unlayered, and an unlayered rule beats a layered one whatever
+   the specificity, so inside @layer components this lost and one FilterGrid click captured 141 stages. Out here the
+   attribute specificity decides, and Astro's single attribute loses. */
+:root[data-ma-vt] [data-astro-transition-scope] {
+  view-transition-name: none;
+}
+
+@keyframes ma-vt-out {
+  to {
+    opacity: 0;
+  }
+}
+@keyframes ma-vt-in {
+  from {
+    opacity: 0;
+  }
+}

package/src/styles/motion.css

@@ -0,0 +1,43 @@
+/*
+ * @moonarc/core/styles — opt-in Tailwind v4 token layer.
+ *
+ * Maps @theme tokens onto the same custom properties base.css defines, so
+ * `ease-out-quint`, `duration-ma`, `ease-snap`, etc. become real utilities
+ * that share the library's curves. Requires Tailwind v4; consumers without
+ * Tailwind simply never import this file and lose nothing.
+ *
+ * Usage:  @import "tailwindcss";
+ *         @import "@moonarc/core/styles";
+ */
+
+/* inline: a utility writes var(--ma-ease) itself, so it resolves on the element and follows a data-ma-preset subtree;
+   a plain @theme resolves var(--ease-ma) on :root, where only the page's preset exists. Durations are
+   --transition-duration-*, the namespace the duration-* utilities read (--duration-* makes no utility). */
+@theme inline {
+  /* the active preset */
+  --ease-ma: var(--ma-ease);
+  --transition-duration-ma: var(--ma-duration);
+
+  /* the five presets by name */
+  --ease-snap: var(--ma-ease-snap);
+  --ease-ui: var(--ma-ease-ui);
+  --ease-gentle: var(--ma-ease-gentle);
+  --ease-lively: var(--ma-ease-lively);
+  --ease-ambient: var(--ma-ease-ambient);
+  --transition-duration-snap: var(--ma-dur-snap);
+  --transition-duration-ui: var(--ma-dur-ui);
+  --transition-duration-gentle: var(--ma-dur-gentle);
+  --transition-duration-lively: var(--ma-dur-lively);
+  --transition-duration-ambient: var(--ma-dur-ambient);
+
+  /* fixed curves */
+  --ease-out-quint: var(--ma-ease-out);
+  --ease-in-quint: var(--ma-ease-in);
+  --ease-in-out-quint: var(--ma-ease-in-out);
+  --ease-drawer: var(--ma-ease-drawer);
+  --ease-spring: var(--ma-ease-spring);
+
+  --transition-duration-fast: var(--ma-duration-fast);
+  --transition-duration-base: var(--ma-duration);
+  --transition-duration-slow: var(--ma-duration-slow);
+}