@moonarc/core 0.1.0

package/src/components/PromptInput.astro

@@ -0,0 +1,273 @@
+---
+/**
+ * PromptInput — the AI prompt box, zero JS by default. A small <form>: a
+ * <textarea> that grows with its content (`field-sizing: content`, capped at
+ * `maxRows`, scrolling past it; without field-sizing it keeps `rows` and a
+ * vertical resize handle), a tool row with a model select (AnimatedSelect,
+ * `name="model"`), an attachment button that is a <label> around a real
+ * `<input type="file" multiple>` — visually hidden, still focusable — and
+ * a send button that dims through `:has(textarea:placeholder-shown)` and
+ * shows a spinner while the form carries `data-pending` (the
+ * NewsletterSection contract). `submitOnEnter` renders one internal
+ * component with a measured script: Enter sends, Shift+Enter breaks the
+ * line, an IME composition is never interrupted.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import AnimatedSelect from './AnimatedSelect.astro';
+import Spinner from './Spinner.astro';
+import PromptInputSubmitOnEnter from './internal/PromptInputSubmitOnEnter.astro';
+
+interface Model {
+  value: string;
+  label: string;
+  disabled?: boolean;
+  group?: string;
+}
+
+interface Props extends HTMLAttributes<'form'> {
+  /** The textarea's name. */
+  name?: string;
+  placeholder?: string;
+  /** Initial text. */
+  value?: string;
+  /** Rows shown when empty; the minimum height. */
+  rows?: number;
+  /** Rows the box grows to before it scrolls. */
+  maxRows?: number;
+  /** Models for the select (name="model"); none hides the select. */
+  models?: Model[];
+  /** The selected model. */
+  model?: string;
+  /** Show the attachment button (a real file input, name="files", multiple). */
+  attachments?: boolean;
+  /** Accept list for the file input. */
+  accept?: string;
+  /** Enter submits, Shift+Enter breaks the line; adds the measured script. */
+  submitOnEnter?: boolean;
+  /** Accessible name of the textarea. */
+  label?: string;
+  required?: boolean;
+  disabled?: boolean;
+  /** Send button label (visually hidden). */
+  sendLabel?: string;
+  /** Attachment button label (visually hidden). */
+  attachLabel?: string;
+  /** Accessible name of the model select. */
+  modelLabel?: string;
+}
+
+const {
+  name = 'prompt',
+  placeholder = 'Ask anything',
+  value,
+  rows = 1,
+  maxRows = 8,
+  models,
+  model,
+  attachments = false,
+  accept,
+  submitOnEnter = false,
+  label = 'Message',
+  required = true,
+  disabled = false,
+  sendLabel = 'Send',
+  attachLabel = 'Attach files',
+  modelLabel = 'Model',
+  class: className,
+  style,
+  ...rest
+} = Astro.props;
+const vars = [`--ma-prompt-rows:${Math.max(1, rows)}`, `--ma-prompt-max:${Math.max(rows, maxRows)}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<form class:list={['ma-prompt', className]} style={vars} {...rest}>
+  <textarea class="ma-prompt__area" name={name} rows={Math.max(1, rows)} placeholder={placeholder} aria-label={label} required={required} disabled={disabled} set:text={value ?? ''} />
+  <div class="ma-prompt__bar">
+    {models && models.length > 0 && <AnimatedSelect class="ma-prompt__model" name="model" options={models} value={model} size="sm" aria-label={modelLabel} disabled={disabled} />}
+    {attachments && (
+      <label class="ma-prompt__attach">
+        <input type="file" name="files" class="ma-prompt__file" multiple accept={accept} disabled={disabled} />
+        <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M21 12.5 12.2 21.3a5.5 5.5 0 0 1-7.8-7.8L13 4.9a3.7 3.7 0 0 1 5.2 5.2l-8.6 8.6a1.8 1.8 0 0 1-2.6-2.6l7.9-7.9" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" /></svg>
+        <span class="ma-prompt__sr">{attachLabel}</span>
+      </label>
+    )}
+    <button type="submit" class="ma-prompt__send" disabled={disabled}>
+      <svg class="ma-prompt__arrow" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 19V5m0 0-6 6m6-6 6 6" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" /></svg>
+      <span class="ma-prompt__busy"><Spinner size={16} width={2} label="" /></span>
+      <span class="ma-prompt__sr">{sendLabel}</span>
+    </button>
+  </div>
+  {submitOnEnter && <PromptInputSubmitOnEnter />}
+</form>
+
+<style is:global>
+  @layer components {
+    :where(.ma-prompt) {
+      display: grid;
+      gap: 0.5em;
+      padding: 0.75em 0.75em 0.6em;
+      border: 1px solid var(--ma-edge);
+      border-radius: 1.1em;
+      background: var(--ma-panel);
+      color: inherit;
+      box-shadow: 0 1px 2px var(--ma-glow);
+      transition: border-color var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-prompt:focus-within) {
+      border-color: color-mix(in srgb, var(--ma-ink) 40%, transparent);
+    }
+    :where(.ma-prompt__area) {
+      inline-size: 100%;
+      margin: 0;
+      padding: 0.25em 0.35em;
+      border: 0;
+      background: transparent;
+      color: inherit;
+      font: inherit;
+      line-height: 1.5;
+      resize: vertical;
+      outline: none;
+      /* grows with the text to maxRows, then scrolls; the minimum is the rows attribute */
+      field-sizing: content;
+      min-block-size: calc(var(--ma-prompt-rows) * 1.5em + 0.5em);
+      max-block-size: calc(var(--ma-prompt-max) * 1.5em + 0.5em);
+    }
+    @supports (field-sizing: content) {
+      :where(.ma-prompt__area) {
+        resize: none;
+      }
+    }
+    :where(.ma-prompt__area)::placeholder {
+      color: color-mix(in srgb, var(--ma-ink) 40%, transparent);
+      opacity: 1;
+    }
+    :where(.ma-prompt__area:disabled) {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+    :where(.ma-prompt__bar) {
+      display: flex;
+      align-items: center;
+      gap: 0.5em;
+    }
+    :where(.ma-prompt__model) {
+      margin-inline-end: auto;
+    }
+    :where(.ma-prompt__bar > :last-child) {
+      margin-inline-start: auto;
+    }
+    :where(.ma-prompt__attach),
+    :where(.ma-prompt__send) {
+      position: relative;
+      display: grid;
+      place-items: center;
+      inline-size: 2.25em;
+      block-size: 2.25em;
+      margin: 0;
+      padding: 0;
+      border: 1px solid transparent;
+      border-radius: 50%;
+      background: transparent;
+      color: inherit;
+      font: inherit;
+      cursor: pointer;
+      transition:
+        background-color var(--ma-duration-fast) var(--ma-ease-out),
+        opacity var(--ma-duration-fast) var(--ma-ease-out),
+        scale var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-prompt__attach > svg),
+    :where(.ma-prompt__send > svg) {
+      inline-size: 1.15em;
+      block-size: 1.15em;
+      grid-area: 1 / 1;
+    }
+    :where(.ma-prompt__attach:hover) {
+      background: color-mix(in srgb, var(--ma-ink) 8%, transparent);
+    }
+    /* the file input: off screen, not display: none — Tab reaches it and Space opens the picker; the label draws the focus */
+    :where(.ma-prompt__file) {
+      position: absolute;
+      inline-size: 1px;
+      block-size: 1px;
+      margin: -1px;
+      padding: 0;
+      border: 0;
+      overflow: hidden;
+      clip-path: inset(50%);
+      white-space: nowrap;
+    }
+    :where(.ma-prompt__attach:has(.ma-prompt__file:focus-visible)),
+    :where(.ma-prompt__send:focus-visible) {
+      outline: 2px solid var(--ma-ink);
+      outline-offset: 2px;
+    }
+    :where(.ma-prompt__send) {
+      background: var(--ma-ink);
+      color: var(--ma-panel);
+    }
+    :where(.ma-prompt__send:hover) {
+      scale: 1.06;
+    }
+    :where(.ma-prompt__send:active) {
+      scale: 0.96;
+    }
+    /* nothing typed: the button reads as inert but stays clickable — required is what refuses the submit */
+    :where(.ma-prompt:has(.ma-prompt__area:placeholder-shown) .ma-prompt__send) {
+      opacity: 0.35;
+      scale: 1;
+    }
+    :where(.ma-prompt__send:disabled) {
+      cursor: not-allowed;
+      opacity: 0.35;
+      scale: 1;
+      transition: none;
+    }
+    :where(.ma-prompt__busy) {
+      grid-area: 1 / 1;
+      display: grid;
+      opacity: 0;
+      transition: opacity var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-prompt[data-pending] .ma-prompt__busy) {
+      opacity: 1;
+    }
+    :where(.ma-prompt[data-pending] .ma-prompt__arrow) {
+      opacity: 0;
+    }
+    :where(.ma-prompt[data-pending] .ma-prompt__send) {
+      opacity: 1;
+      pointer-events: none;
+    }
+    :where(.ma-prompt__sr) {
+      position: absolute;
+      inline-size: 1px;
+      block-size: 1px;
+      margin: -1px;
+      padding: 0;
+      overflow: hidden;
+      clip-path: inset(50%);
+      white-space: nowrap;
+    }
+    @media (forced-colors: active) {
+      :where(.ma-prompt) {
+        border-color: ButtonText;
+      }
+      :where(.ma-prompt__send) {
+        border-color: ButtonText;
+        forced-color-adjust: none;
+        background: ButtonText;
+        color: Canvas;
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-prompt),
+      :where(.ma-prompt__attach),
+      :where(.ma-prompt__send),
+      :where(.ma-prompt__busy) {
+        transition: none;
+        scale: 1;
+      }
+    }
+  }
+</style>

package/src/components/PromptInput.meta.ts

@@ -0,0 +1,46 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'PromptInput',
+  slug: 'prompt-input',
+  title: 'Prompt Input',
+  description: 'The AI prompt box: a form with a textarea that grows with its content through field-sizing, a model select, an attachment button that is a real file input, and a send button that dims until something is typed and spins while the form carries data-pending. Zero JavaScript by default; submitOnEnter adds a measured script: Enter sends, Shift+Enter breaks the line, and an IME composition is never interrupted.',
+  summary: 'An AI prompt box: a textarea that grows, a model select, a file attachment, and a send button that shows pending.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['click'],
+  support: { baseline: 'newly', needs: ['field-sizing', 'has'], fallback: 'without field-sizing the textarea keeps its rows and a vertical resize handle; without :has() the send button does not dim' },
+  readout: '<PromptInput models={models} attachments submitOnEnter>',
+  usage: `---\nconst models = [{ value: 'fable', label: 'Fable 5.1' }, { value: 'sonnet', label: 'Sonnet 5' }];\n---\n<PromptInput action="/api/chat" method="post" models={models} model="fable" attachments submitOnEnter />\n\n<script>\n  // your handler: mark the form busy while the request runs\n  const form = document.querySelector('.ma-prompt');\n  form.addEventListener('submit', async (e) => {\n    e.preventDefault();\n    if (form.hasAttribute('data-pending')) return;\n    form.dataset.pending = '';\n    try {\n      await fetch('/api/chat', { method: 'POST', body: new FormData(form) });\n    } finally {\n      delete form.dataset.pending;\n    }\n  });\n</script>`,
+  props: [
+    { name: 'name', type: 'string', default: "'prompt'", description: 'The textarea\'s field name.' },
+    { name: 'placeholder', type: 'string', default: "'Ask anything'", description: 'Placeholder; :placeholder-shown is what dims the send button.' },
+    { name: 'value', type: 'string', description: 'Initial text.' },
+    { name: 'rows', type: 'number', default: '1', description: 'Rows when empty: the minimum height, and the fixed height without field-sizing.' },
+    { name: 'maxRows', type: 'number', default: '8', description: 'Rows the box grows to before it scrolls.' },
+    { name: 'models', type: '{ value, label, disabled?, group? }[]', description: 'Options for the model select (name="model"); none hides it.' },
+    { name: 'model', type: 'string', description: 'The selected model.' },
+    { name: 'attachments', type: 'boolean', default: 'false', description: 'Show the paperclip: a <label> around <input type="file" name="files" multiple>, visually hidden, reachable by Tab.' },
+    { name: 'accept', type: 'string', description: 'Accept list for the file input.' },
+    { name: 'submitOnEnter', type: 'boolean', default: 'false', description: 'Enter submits through form.requestSubmit() (validation and your handler run), Shift+Enter is a newline, nothing during IME composition. Adds the internal script, measured on its own fixture.' },
+    { name: 'label', type: 'string', default: "'Message'", description: 'Accessible name of the textarea.' },
+    { name: 'required', type: 'boolean', default: 'true', description: 'The browser refuses an empty submit.' },
+    { name: 'disabled', type: 'boolean', default: 'false', description: 'Disables every control.' },
+    { name: 'sendLabel', type: 'string', default: "'Send'", description: 'Visually hidden label of the send button.' },
+    { name: 'attachLabel', type: 'string', default: "'Attach files'", description: 'Visually hidden label of the attachment button.' },
+    { name: 'modelLabel', type: 'string', default: "'Model'", description: 'Accessible name of the model select.' },
+  ],
+  reducedMotion: 'The button and the spinner switch without transitions; the textarea still grows (a layout, not an animation).',
+  clientRouter: 'A native form; nothing to bind. With submitOnEnter the internal script is bound through the shared runtime and rebinds after every navigation.',
+  craft: [
+    'field-sizing: content makes the textarea follow its text with no measuring script; min and max heights are rows × the line height, so the cap is a row count. Engines without it keep the rows attribute and a resize handle, which is a plain, working textarea.',
+    'The send button never becomes disabled for an empty box: it dims through :has(textarea:placeholder-shown) and stays clickable, so a click on it runs the browser\'s own validation message for required instead of doing nothing.',
+    'The attachment control is a label around a real file input, hidden with clip-path rather than display: none: Tab reaches it, Space opens the picker, the files submit under name="files". A list of the chosen names is the host\'s to render; it is not built here.',
+    'Busy state is the form\'s data-pending attribute, the NewsletterSection contract: a fetch handler toggles one attribute and the arrow gives way to the Spinner. The handler keeps the form in a variable: after an await, e.currentTarget is null, and a delete through it throws and leaves the form busy for good.',
+    'submitOnEnter is a variant on purpose: the default fixture proves the form is 0 B, and the Enter script is measured alone. It calls requestSubmit(), so required, the submit event and your handler all still run; and it checks isComposing (and keyCode 229 for older IMEs) so a Japanese or Chinese reader confirming a candidate does not send the message.',
+  ],
+  related: ['animated-select', 'stateful-button', 'vanish-input'],
+  intents: ['ai prompt input', 'chat input box', 'growing textarea', 'textarea autosize css', 'prompt box with model picker', 'chatgpt style input'],
+  replaces: ['PromptInput (Kokonut UI)', 'AI Input (Kibo UI)', 'react-textarea-autosize'],
+  fixture: { props: { name: 'ma-fixture', placeholder: 'Fixture content for PromptInput', models: [{ value: 'a', label: 'Alpha' }, { value: 'b', label: 'Beta' }], attachments: true }, expect: 'Fixture content for PromptInput', variants: { submitOnEnter: { props: { submitOnEnter: true }, expect: 'data-ma-prompt-enter' } } },
+} satisfies ComponentMeta;

package/src/components/ReadingToc.astro

@@ -0,0 +1,153 @@
+---
+/**
+ * ReadingToc — a table of contents that lights up as you read. The list is
+ * server-rendered from `items` (Astro's own `headings` shape works), the
+ * links are plain anchors, and one passive scroll listener sets
+ * aria-current on the link of the last heading above the reading line —
+ * the only thing a script does. The indicator is CSS from that attribute.
+ * The listener sits on the nearest ancestor of the article that really
+ * scrolls, so it works inside a scrolling box as well as on the page, and
+ * it is dropped before every ClientRouter swap.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Item {
+  slug: string;
+  text: string;
+  /** 2 for h2, 3 for h3 … */
+  depth?: number;
+}
+
+interface Props extends HTMLAttributes<'nav'> {
+  items: Item[];
+  /** Selector of the article the headings live in. */
+  for: string;
+  /** Heading selector inside the article. */
+  headings?: string;
+  /** Distance from the top of the scrollport where a heading counts as current, in px. */
+  offset?: number;
+  title?: string;
+}
+
+const { items, for: target, headings = 'h2, h3', offset = 96, title = 'On this page', class: className, ...rest } = Astro.props;
+const min = Math.min(...items.map((i) => i.depth ?? 2));
+---
+
+<nav class:list={['ma-toc', className]} data-ma-toc data-for={target} data-headings={headings} data-offset={offset} aria-label={title} {...rest}>
+  {title && <p class="ma-toc__title">{title}</p>}
+  <ul class="ma-toc__list">
+    {items.map((i) => (
+      <li class="ma-toc__item" style={`--ma-toc-d:${(i.depth ?? 2) - min}`}>
+        <a class="ma-toc__link" href={`#${i.slug}`}>{i.text}</a>
+      </li>
+    ))}
+  </ul>
+</nav>
+
+<style is:global>
+  @layer components {
+    :where(.ma-toc) {
+      font-size: 0.875rem;
+    }
+    :where(.ma-toc__title) {
+      margin: 0 0 0.5rem;
+      font-size: 0.75em;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      opacity: var(--ma-dim, 0.7);
+    }
+    :where(.ma-toc__list) {
+      list-style: none;
+      margin: 0;
+      padding: 0;
+      border-left: 1px solid var(--ma-edge);
+    }
+    :where(.ma-toc__item) {
+      margin: 0;
+      padding: 0;
+    }
+    :where(.ma-toc__link) {
+      position: relative;
+      display: block;
+      padding: 0.3em 0 0.3em calc(0.9em + var(--ma-toc-d, 0) * 0.9em);
+      color: inherit;
+      text-decoration: none;
+      opacity: var(--ma-dim, 0.7);
+      transition: opacity var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    /* the indicator: a bar on the list's left edge that grows from its middle */
+    :where(.ma-toc__link)::before {
+      content: '';
+      position: absolute;
+      inset: 0.2em auto 0.2em -1px;
+      width: 2px;
+      border-radius: 999px;
+      background: currentColor;
+      scale: 1 0;
+      transition: scale var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-toc__link:hover) {
+      opacity: 0.9;
+    }
+    :where(.ma-toc__link[aria-current]) {
+      opacity: 1;
+    }
+    :where(.ma-toc__link[aria-current])::before {
+      scale: 1 1;
+    }
+    :where(.ma-toc__link:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+      border-radius: 0.25em;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-toc__link),
+      :where(.ma-toc__link)::before {
+        transition: none;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+
+  onMount<HTMLElement>('[data-ma-toc]', (nav, { signal }) => {
+    const article = nav.dataset.for ? document.querySelector(nav.dataset.for) : null;
+    if (!article) return;
+    const heads = Array.from(article.querySelectorAll<HTMLElement>(nav.dataset.headings!)).filter((h) => h.id);
+    const links = new Map(Array.from(nav.querySelectorAll<HTMLAnchorElement>('a[href^="#"]')).map((a) => [decodeURIComponent(a.hash.slice(1)), a]));
+    if (!heads.length) return;
+    // the nearest ancestor that really scrolls decides the line; null is the viewport. overflow-x: hidden alone computes
+    // overflow-y to auto as well, so a page wrapper that only stops sideways scroll also matches; its content never
+    // overflows it, which is how it is told apart
+    let root: Element | null = article.parentElement;
+    while (root && root !== document.body) {
+      const o = getComputedStyle(root).overflowY;
+      if ((o === 'auto' || o === 'scroll') && root.scrollHeight > root.clientHeight) break;
+      root = root.parentElement;
+    }
+    if (root === document.body) root = null;
+    const offset = +nav.dataset.offset!;
+    let current: HTMLElement | null = null;
+    const mark = (h: HTMLElement | null) => {
+      if (h === current) return;
+      current = h;
+      for (const [id, a] of links) {
+        if (h && id === h.id) a.setAttribute('aria-current', 'true');
+        else a.removeAttribute('aria-current');
+      }
+    };
+    // the heading nearest the reading line: the last one whose top is above it
+    const pick = () => {
+      const top = root ? root.getBoundingClientRect().top : 0;
+      let hit: HTMLElement | null = null;
+      for (const h of heads) if (h.getBoundingClientRect().top - top <= offset + 1) hit = h;
+      mark(hit ?? heads[0]!);
+    };
+    // every scroll re-reads the line (scroll fires at most once a frame): a jump from a link, a key or the scrollbar lands
+    // on the right heading too, where an observer on a band below the line saw nothing cross it
+    ((root ?? window) as EventTarget).addEventListener('scroll', pick, { signal, passive: true });
+    pick();
+  });
+</script>

package/src/components/ReadingToc.meta.ts

@@ -0,0 +1,34 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'ReadingToc',
+  slug: 'reading-toc',
+  title: 'Reading TOC',
+  description: 'A table of contents that lights up as you read. The list is server-rendered from items (Astro\'s own headings shape works), the links are plain anchors, and one passive scroll listener sets aria-current on the link of the last heading above the reading line, which is the only thing the script does. The indicator is CSS from that attribute. Works inside a scrolling box as well as on the page, follows jumps from its own links, and is dropped before every navigation.',
+  summary: 'A table of contents that highlights the section you are reading, on the page or inside a scrolling box.',
+  category: 'scroll',
+  tier: 'B',
+  trigger: ['scroll'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<ReadingToc for="article" items={headings}>',
+  usage: `---\nconst { Content, headings } = await render(post);\n---\n<aside><ReadingToc for="#post" items={headings} offset={96} /></aside>\n<article id="post"><Content /></article>`,
+  props: [
+    { name: 'items', type: '{ slug: string; text: string; depth?: number }[]', description: 'The headings; depth indents (2 for h2, 3 for h3).' },
+    { name: 'for', type: 'string', description: 'Selector of the article the headings live in.' },
+    { name: 'headings', type: 'string', default: "'h2, h3'", description: 'Heading selector inside the article; only headings with an id count.' },
+    { name: 'offset', type: 'number', default: '96', description: 'Distance from the top of the scrollport where a heading becomes current, in px; usually your sticky header\'s height.' },
+    { name: 'title', type: 'string', default: "'On this page'", description: 'Heading over the list and the nav\'s label.' },
+  ],
+  reducedMotion: 'The indicator and the link\'s opacity switch at once.',
+  clientRouter: 'Bound through the shared runtime: the scroll listener is added after every navigation and removed before the swap (the binding\'s abort signal), so five round trips leave one listener, not six.',
+  craft: [
+    'The current heading is the last one whose top is above the offset line, recomputed on every scroll (at most once a frame, a rect read per heading): a reader between two headings is in the earlier section, which is the one the indicator should show. An IntersectionObserver on a band under the line looked cheaper and missed every jump, since a heading sent from below the fold to the top by a link never crosses the band.',
+    'The listener sits on the nearest ancestor of the article that really scrolls (its content overflows it), so the same component works in a page, a docs shell with its own scroller and the catalogue tile, and a page wrapper with overflow-x: hidden (which computes overflow-y to auto) is passed over.',
+    'Only aria-current is written. The indicator (a bar that grows from the middle) and the link\'s full opacity are CSS from that attribute, so the accessible state and the visible state cannot disagree.',
+    'Links stay anchors: without the script the TOC still jumps to the section and :target still works.',
+  ],
+  related: ['tracing-beam', 'scroll-progress', 'tabs'],
+  intents: ['table of contents highlight on scroll', 'active heading toc', 'scrollspy', 'on this page navigation', 'reading progress toc'],
+  replaces: ['TableOfContents (Fumadocs)', 'scrollspy (Bootstrap)', 'toc highlight (Starlight)'],
+  fixture: { props: { for: '#ma-fixture-article', items: [{ slug: 'one', text: 'Fixture content for ReadingToc' }, { slug: 'two', text: 'Two' }] }, expect: 'Fixture content for ReadingToc' },
+} satisfies ComponentMeta;

package/src/components/RetroGrid.astro

@@ -0,0 +1,84 @@
+---
+/**
+ * RetroGrid — a perspective grid floor sliding toward the viewer. Two
+ * repeating gradients on one plane rotated in 3D; the motion is a
+ * `translate` of exactly one cell on the compositor (not background-position,
+ * which repaints every frame), so the loop is seamless and costs nothing
+ * on the main thread. A mask fades the horizon. Fills its positioned parent.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Tilt of the floor in degrees; 65 is a floor, 45 a ramp. */
+  angle?: number;
+  /** Cell size in px. */
+  cellSize?: number;
+  /** Line colour. */
+  color?: string;
+  /** Seconds per cell of travel. */
+  speed?: number;
+  /** Fade out toward the horizon. */
+  fade?: boolean;
+  /** Line width in px. */
+  lineWidth?: number;
+  /** Where the horizon sits, as a percentage of the height. */
+  horizon?: number;
+}
+
+const { angle = 65, cellSize = 60, color = 'color-mix(in srgb, var(--ma-ink) 22%, transparent)', speed = 1, fade = true, lineWidth = 1, horizon = 40, class: className, style, ...rest } = Astro.props;
+const inline = [`--ma-retro-angle:${angle}deg`, `--ma-retro-cell:${cellSize}px`, `--ma-retro-color:${color}`, `--ma-retro-dur:${speed}s`, `--ma-retro-line:${lineWidth}px`, `--ma-retro-horizon:${horizon}%`, typeof style === 'string' ? style : '']
+  .filter(Boolean)
+  .join(';');
+---
+
+<div class:list={['ma-retro', className]} aria-hidden="true" data-fade={fade ? '' : undefined} style={inline} {...rest}>
+  <div class="ma-retro__floor"><div class="ma-retro__lines"></div></div>
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-retro) {
+      position: absolute;
+      inset: 0;
+      overflow: hidden;
+      pointer-events: none;
+      perspective: calc(var(--ma-retro-cell, 60px) * 4);
+      contain: strict;
+    }
+    :where(.ma-retro[data-fade]) {
+      mask-image: linear-gradient(to bottom, transparent var(--ma-retro-horizon, 40%), #000 calc(var(--ma-retro-horizon, 40%) + 30%));
+    }
+    /* the floor: a huge plane hinged at the horizon, rotated back */
+    :where(.ma-retro__floor) {
+      position: absolute;
+      inset: var(--ma-retro-horizon, 40%) -100% -100%;
+      transform-origin: 50% 0;
+      transform: rotateX(var(--ma-retro-angle, 65deg));
+    }
+    :where(.ma-retro__lines) {
+      position: absolute;
+      inset: calc(-1 * var(--ma-retro-cell, 60px)) 0 0;
+      background-image:
+        linear-gradient(to right, var(--ma-retro-color) var(--ma-retro-line, 1px), transparent var(--ma-retro-line, 1px)),
+        linear-gradient(to bottom, var(--ma-retro-color) var(--ma-retro-line, 1px), transparent var(--ma-retro-line, 1px));
+      background-size: var(--ma-retro-cell, 60px) var(--ma-retro-cell, 60px);
+      background-position: 50% 0;
+      will-change: translate;
+      animation: ma-retro var(--ma-retro-dur) linear infinite;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-retro__lines) {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-retro {
+    from {
+      translate: 0 0;
+    }
+    to {
+      translate: 0 var(--ma-retro-cell, 60px);
+    }
+  }
+</style>

package/src/components/RetroGrid.meta.ts

@@ -0,0 +1,36 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'RetroGrid',
+  slug: 'retro-grid',
+  title: 'Retro Grid',
+  description: 'A perspective grid floor sliding toward the viewer. Two repeating gradients on one plane rotated in 3D; the motion is a translate of exactly one cell on the compositor, so the loop has no visible seam and never repaints. A mask fades the horizon. Zero JS; fills its positioned parent.',
+  summary: 'A retro perspective grid floor sliding toward the viewer, with the horizon fading out.',
+  category: 'background',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'widely', needs: ['mask-image'], fallback: 'the grid without the horizon fade' },
+  readout: '<RetroGrid angle={65} cellSize={60}>',
+  usage: `<section class="relative overflow-hidden">\n  <RetroGrid />\n  <h1 class="relative">Above the floor</h1>\n</section>`,
+  props: [
+    { name: 'angle', type: 'number', default: '65', description: 'Tilt of the floor in degrees; 65 reads as a floor, 45 as a ramp.' },
+    { name: 'cellSize', type: 'number', default: '60', description: 'Cell size in px; the perspective distance is four cells.' },
+    { name: 'color', type: 'string', default: 'ink at 22 %', description: 'Line colour.' },
+    { name: 'speed', type: 'number', default: '1', description: 'Seconds per cell of travel.' },
+    { name: 'fade', type: 'boolean', default: 'true', description: 'Fade out toward the horizon.' },
+    { name: 'lineWidth', type: 'number', default: '1', description: 'Line width in px.' },
+    { name: 'horizon', type: 'number', default: '40', description: 'Where the horizon sits, as a percentage of the height.' },
+  ],
+  reducedMotion: 'The floor stands still.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'Translate one cell and loop: the plane moves exactly its period, so the wrap is invisible and the animation is compositor-only; background-position would repaint every frame.',
+    'The plane is hinged at the horizon (transform-origin at the top) and rotated back, with perspective set on the parent at four cells: near enough to converge, far enough that the top row is not a blur.',
+    'Linear timing: an eased floor stutters at every loop.',
+    'The lines are the ink token at low alpha, so the grid follows the theme without a second colour.',
+  ],
+  related: ['grid-pattern', 'dot-pattern', 'meteors'],
+  intents: ['retro grid background', 'synthwave grid', 'perspective grid floor', 'moving grid background hero', 'tron grid css'],
+  replaces: ['RetroGrid (Magic UI)', 'GridBackground (Aceternity)'],
+  fixture: { expect: 'class="ma-retro"' },
+} satisfies ComponentMeta;