@moonarc/mcp 0.1.0

package/src/compose.js

@@ -0,0 +1,171 @@
+/**
+ * compose_section: an ordered composition of components for a stated goal, with the total measured cost and a code
+ * skeleton. The one genuinely N-to-1 workflow tool: an agent states an intent and gets a section.
+ *
+ * Costs and browser support come from the catalogue at answer time, never from these recipes, so a component that
+ * gains or loses a script changes the answer without an edit here. The notes carry composition advice only.
+ */
+const RECIPES = [
+  {
+    id: 'hero',
+    words: ['hero', 'landing', 'above the fold', 'headline', 'intro', 'splash'],
+    title: 'Hero',
+    parts: ['Aurora', 'SplitText', 'Reveal', 'RotatingText', 'Typewriter'],
+    code: `<section class="relative overflow-hidden">
+  <Aurora opacity={0.4} />
+  <div class="relative">
+    <SplitText as="h1" text="Your headline, split on the server." />
+    <Reveal delay={400}><p>Supporting copy, revealed once. Ship <RotatingText words={['faster', 'lighter']} /> sites.</p></Reveal>
+    <Reveal delay={550}><a href="/setup/">Primary action</a> <code><Typewriter text="npx astro add moonarc" /></code></Reveal>
+  </div>
+</section>`,
+    notes: ['Aurora is decoration: give it a positioned parent and put the content above it with position: relative.', 'Delays of 400 and 550 ms let the headline finish before the copy starts. Stagger at most three things in a hero.'],
+  },
+  {
+    id: 'hero-field',
+    words: ['cursor', 'pointer', 'interactive hero', 'grid hero', 'cursor field', 'cursor grid', 'mouse'],
+    title: 'Hero with a cursor field',
+    parts: ['CursorGrid', 'SplitText', 'Reveal', 'Magnetic'],
+    code: `<section class="relative min-h-[70vh]">
+  <CursorGrid color="var(--accent)" />
+  <div class="relative">
+    <SplitText as="h1" text="Move your cursor over the grid." />
+    <Reveal delay={400}><Magnetic><a href="/start/">Primary action</a></Magnetic></Reveal>
+  </div>
+</section>`,
+    notes: ['The field lights its cells with hover states. Keep the content above it with position: relative.', 'Magnetic pulls one element; use it on the primary action only.'],
+  },
+  {
+    id: 'faq',
+    words: ['faq', 'faqs', 'questions', 'accordion', 'collapsible', 'disclosure'],
+    title: 'FAQ',
+    parts: ['Accordion', 'Reveal'],
+    code: `<Reveal>
+  <Accordion exclusive open={0} items={[
+    { title: 'Is it really zero JS?', body: '<p>For this one, yes.</p>' },
+    { title: 'Keyboard?', body: '<p>Native.</p>' },
+  ]} />
+</Reveal>`,
+    notes: ['The items are native <details>, so the keyboard works without a script and ::details-content animates the height.', 'exclusive keeps one answer open at a time; leave it off when readers compare answers.'],
+  },
+  {
+    id: 'features',
+    words: ['feature', 'features', 'benefit', 'benefits', 'grid', 'cards', 'card grid', 'bento', 'why choose', 'why us'],
+    title: 'Feature grid',
+    parts: ['Reveal'],
+    code: `<Reveal as="ul" stagger={60} class="grid gap-4 sm:grid-cols-3">
+  <li>Feature one</li>
+  <li>Feature two</li>
+  <li>Feature three</li>
+</Reveal>`,
+    notes: ['One Reveal with stagger and the cards as its direct children. A Reveal per card cannot stagger them.', 'Six cards at 60 ms is 300 ms of stagger; past nine cards, drop to 40 ms.'],
+  },
+  {
+    id: 'logos',
+    words: ['logo', 'logos', 'logo strip', 'logo wall', 'customer logos', 'trusted by', 'partners', 'brands', 'ticker', 'as seen on'],
+    title: 'Logo strip',
+    parts: ['Marquee'],
+    code: `<Marquee duration={28} gap="3rem" label="Customers">
+  <img src="/logos/a.svg" alt="A" height="28" />
+  <img src="/logos/b.svg" alt="B" height="28" />
+</Marquee>`,
+    notes: ['Scale the duration with the content width: about 1 s per 60 px keeps logos readable.', 'label names the strip for screen readers, which hear each logo once.'],
+  },
+  {
+    id: 'testimonials',
+    words: ['testimonial', 'testimonials', 'quote', 'quotes', 'review', 'reviews', 'social proof', 'wall of love', 'customer quotes'],
+    title: 'Testimonial wall',
+    parts: ['Reveal', 'Marquee'],
+    code: `<Reveal as="div" stagger={70} class="grid gap-4 md:grid-cols-2">
+  <blockquote>…</blockquote>
+  <blockquote>…</blockquote>
+</Reveal>
+<!-- or a moving wall: up and down need a height on the strip -->
+<Marquee direction="up" duration={40} style="height: 32rem">
+  <blockquote>…</blockquote>
+</Marquee>`,
+    notes: ['A static staggered grid reads better than a moving wall for more than four quotes; use the vertical Marquee for a sidebar.'],
+  },
+  {
+    id: 'stats',
+    words: ['stat', 'stats', 'statistic', 'statistics', 'number', 'numbers', 'metric', 'metrics', 'kpi', 'kpis', 'counter', 'counters', 'count up'],
+    title: 'Stat row',
+    parts: ['CountUp', 'Progress'],
+    code: `<dl class="grid grid-cols-3 gap-6">
+  <div><dt>Customers</dt><dd><CountUp to={1200} /></dd></div>
+  <div><dt>Countries</dt><dd><CountUp to={48} /></dd></div>
+  <div><dt>Uptime</dt><dd><Progress value={99} /></dd></div>
+</dl>`,
+    notes: ['CountUp counts with CSS counters, and the server HTML already holds the final number.', 'Give CountUp and Progress the same duration so the bar and the number land together.'],
+  },
+  {
+    id: 'cta',
+    words: ['cta', 'call to action', 'signup', 'sign up', 'subscribe', 'get started', 'start now', 'closing'],
+    title: 'Call to action',
+    parts: ['Reveal', 'Typewriter'],
+    code: `<Reveal scale={0.98} class="rounded-2xl border p-10 text-center">
+  <h2>Ready?</h2>
+  <p><code><Typewriter text="npx astro add moonarc" /></code></p>
+  <a href="/setup/">Start</a>
+</Reveal>`,
+    notes: ['Scale from 0.98, never from 0. One Reveal for the whole block.'],
+  },
+];
+
+/** The goals compose_section knows, in the words of its answer when none matches. */
+const GOALS = 'a hero, a hero with a cursor field, an FAQ, a feature grid, a logo strip, a testimonial wall, a stat row, a call to action';
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** How well a recipe answers: each of its words or phrases found as a whole word scores its length in words, so "interactive hero" beats "hero". */
+const scoreOf = (recipe, intent) => recipe.words.reduce((n, w) => n + (new RegExp(`\\b${escape(w).replace(/ /g, '\\s+')}s?\\b`, 'i').test(intent) ? w.split(' ').length : 0), 0);
+
+const fmt = (b) => (b < 1024 ? `${b} B` : `${(b / 1024).toFixed(1)} kB`);
+const list = (names) => (names.length < 3 ? names.join(' and ') : `${names.slice(0, -1).join(', ')} and ${names.at(-1)}`);
+
+/** Every recipe's parts, for tests that hold them against the catalogue. */
+export const recipeParts = () => RECIPES.map((r) => ({ id: r.id, parts: r.parts, code: r.code }));
+
+/**
+ * @param {string} intent
+ * @param {{ components: { name: string, supportLine?: string, support?: { baseline: string, fallback?: string }, cost: { js: { raw: number }, dependsOn: string[] } | null }[], runtime: { raw: number } | null, chunks?: Record<string, { raw: number }> }} catalog
+ */
+export function compose(intent, catalog) {
+  const best = RECIPES.map((r) => ({ r, score: scoreOf(r, intent) })).reduce((a, b) => (b.score > a.score ? b : a), { r: null, score: 0 });
+  if (!best.r) return `No composition matches "${intent}". compose_section has recipes for ${GOALS}. For anything else, call search_motion with the goal and build the section from its results.`;
+  const recipe = best.r;
+  const parts = recipe.parts.map((name) => catalog.components.find((c) => c.name === name)).filter(Boolean);
+
+  // What the page loads for the section, each chunk once: every part's own script, and what the parts share (Reveal,
+  // the runtime, a helper). A dependency that is a component weighs its own script; any other takes the catalogue's
+  // chunk size, and the runtime its measured figure when the catalogue has no chunk sizes.
+  const size = (name) => catalog.components.find((c) => c.name === name)?.cost?.js.raw ?? catalog.chunks?.[name]?.raw ?? (name === 'runtime' ? catalog.runtime?.raw : undefined);
+  const chunks = new Map();
+  for (const c of parts) {
+    if (c.cost?.js.raw) chunks.set(c.name, c.cost.js.raw);
+    for (const d of c.cost?.dependsOn ?? []) if (!chunks.has(d)) chunks.set(d, size(d));
+  }
+  const known = [...chunks].filter(([, b]) => b != null && b > 0);
+  const unknown = [...chunks].filter(([, b]) => b == null).map(([n]) => n);
+  const total = known.reduce((n, [, b]) => n + b, 0);
+  const none = parts.filter((c) => c.cost && c.cost.js.raw === 0).map((c) => c.name);
+  const cost = `${fmt(total)} raw of JavaScript for the whole section${known.length ? `: ${known.map(([n, b]) => `${n} ${fmt(b)} raw`).join(', ')}, each loaded once` : ''}${unknown.length ? ` (plus ${list(unknown)}, not measured in this catalogue)` : ''}.${none.length ? ` ${list(none)} ${none.length === 1 ? 'adds' : 'add'} no script of ${none.length === 1 ? 'its' : 'their'} own.` : ''}`;
+  const support = parts.filter((c) => c.support && c.support.baseline !== 'widely').map((c) => `- ${c.name} needs ${c.supportLine}${c.support.fallback ? `; elsewhere ${c.support.fallback}` : ''}.`);
+
+  return `# ${recipe.title}: a composition for "${intent}"
+
+Order: ${parts.map((c) => c.name).join(' → ')}
+Cost: ${cost}
+
+## Imports
+${parts.map((c) => `import ${c.name} from '@moonarc/core/${c.name}';`).join('\n')}
+
+## Skeleton
+\`\`\`astro
+${recipe.code}
+\`\`\`
+
+## Notes
+${[...recipe.notes.map((n) => `- ${n}`), ...support].join('\n')}
+- Every part has a reduced-motion branch and keeps working after ClientRouter navigation; get_component shows how for each.
+`;
+}

package/src/install.js

@@ -0,0 +1,29 @@
+// What get_install_command answers. Pure, so tests/registry can hold the copy answer's components.json against the one
+// the site documents on /setup/ and install with it.
+
+/**
+ * The components.json the shadcn CLI needs in an Astro project, which has none. `shadcn init` would write one and add
+ * React with it; this file leaves package.json alone. The same file /setup/ prints.
+ */
+export const componentsJson = (site) => ({
+  $schema: 'https://ui.shadcn.com/schema.json',
+  style: 'new-york',
+  rsc: false,
+  tsx: true,
+  tailwind: { config: '', css: 'src/styles/global.css', baseColor: 'neutral', cssVariables: true },
+  aliases: { components: '@/components', utils: '@/lib/utils', lib: '@/lib' },
+  registries: { '@moonarc': `${site}/r/{name}.json` },
+});
+
+/** `entries`: catalogue entries ({ name, slug }). `method`: 'package' (default) or 'copy'. */
+export function installText(site, entries, method = 'package') {
+  if (method !== 'copy') return `npx astro add moonarc\n\n# then, in a .astro file:\n${entries.map((e) => `import ${e.name} from '@moonarc/core/${e.name}';`).join('\n')}`;
+  return [
+    '1. The shadcn CLI reads components.json, and an Astro project has none. If the project has no components.json, write this one (shadcn init would add React and seven packages these components never import):',
+    JSON.stringify(componentsJson(site), null, 2),
+    '2. The copied files import one another through the @/* alias. tsconfig.json needs it under compilerOptions: "paths": { "@/*": ["./src/*"] }',
+    '3. Run:',
+    `npx shadcn@latest add ${entries.map((e) => `${site}/r/${e.slug}.json`).join(' ')}`,
+    `Files land in src/components/moonarc/ and src/lib/moonarc/, the stylesheets in src/styles/. Import '@/styles/moonarc.css' once. Entrance effects also need the JS gate: ${site}/docs/installation/#manual-install`,
+  ].join('\n\n');
+}

package/src/license.js

@@ -0,0 +1,47 @@
+/**
+ * Pro gating. Plan-level, not per-call: the key is validated once per process against Polar's customer-portal
+ * license-key endpoint (no token needed; the organisation id is not a secret) and a final answer is kept for the
+ * process. A key Polar does not know is final: the tool result says subscription_required and tells the agent not to
+ * retry. A failure that says nothing about the key (a timeout, a 5xx, a 429, a network error, a body it cannot read)
+ * is not kept, so the next call asks again.
+ *
+ * The organisation is Moonarc's production organisation, written here so a subscriber sets only MOONARC_KEY;
+ * MOONARC_POLAR_ORG and MOONARC_LICENSE_ENDPOINT point it at the sandbox or at a test's mock. Without an organisation
+ * every key is refused: a build that names none must not grant Pro to any string.
+ */
+const ORGANIZATION = '2a6a3f61-ff75-4b83-b809-a3e2a835bfd8'; // Moonarc's production organisation on Polar (slug moonarc)
+const KEY = process.env.MOONARC_KEY;
+const ORG = process.env.MOONARC_POLAR_ORG || ORGANIZATION;
+const ENDPOINT = process.env.MOONARC_LICENSE_ENDPOINT ?? 'https://api.polar.sh/v1/customer-portal/license-keys/validate';
+const REFUSED = 'subscription_required: the license key is invalid, revoked, or the subscription ended. Do not retry; tell the user to check https://moonarc.dev/account/';
+
+let cached = null;
+
+/** @returns {Promise<{ ok: boolean, plan: 'free'|'pro', reason?: string, validated?: boolean, expiresAt?: string|null }>} */
+export async function licenseStatus() {
+  if (cached) return cached;
+  if (!KEY) return (cached = { ok: false, plan: 'free', reason: 'no MOONARC_KEY set' });
+  if (!ORG) return (cached = { ok: false, plan: 'free', reason: 'Pro is not open yet: this build of @moonarc/mcp names no Polar organisation' });
+  let res;
+  try {
+    res = await fetch(ENDPOINT, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ key: KEY, organization_id: ORG }), signal: AbortSignal.timeout(8000) });
+  } catch (err) {
+    const why = err?.name === 'TimeoutError' ? 'no answer within 8 s' : err?.message;
+    return { ok: false, plan: 'free', reason: `license service unreachable (${why}); Pro tools unavailable offline, try again later` };
+  }
+  if (res.status === 403) return (cached = { ok: false, plan: 'free', reason: REFUSED });
+  if (res.status === 404) {
+    // Polar's own "not found" names the resource ({"error":"ResourceNotFound"}); a 404 without it is a route or an API
+    // version Polar does not serve ({"detail":"Not Found"}), which says nothing about the key
+    const body = await res.json().catch(() => null);
+    if (body?.error === 'ResourceNotFound') return (cached = { ok: false, plan: 'free', reason: REFUSED });
+    return { ok: false, plan: 'free', reason: 'license service answered 404 for its own route; update @moonarc/mcp' };
+  }
+  if (!res.ok) return { ok: false, plan: 'free', reason: `license service returned ${res.status}; try again later` };
+  const data = await res.json().catch(() => null);
+  if (!data) return { ok: false, plan: 'free', reason: 'license service returned an unreadable answer; try again later' };
+  // Pro and Team grant the same license-key benefit, so the answer cannot tell them apart; both run the same tools
+  return (cached = { ok: true, plan: 'pro', validated: true, expiresAt: data.expires_at ?? null });
+}
+
+export const hasKey = Boolean(KEY);

package/src/measure.js

@@ -0,0 +1,269 @@
+/**
+ * measure_budget and `moonarc measure`: the JavaScript each page of a built Astro site makes the browser load.
+ *
+ * measurePage() is the method Moonarc's own CI runs: tests/budget/measure.ts re-exports it, so the budget suite, the
+ * template ceilings and this tool are one computation and cannot drift apart again. It counts external scripts, inline
+ * scripts the browser runs (a JSON, JSON-LD or import-map block is data), modulepreloads, the component and renderer an
+ * <astro-island> loads, and every chunk those import, statically or dynamically with a fixed path, each once per page.
+ * Astro inlines small scripts and stylesheets into the HTML, so counting dist/_astro alone under-reports.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, posix, relative, sep } from 'node:path';
+import { gzipSync } from 'node:zlib';
+
+/** @typedef {{ raw: number, gzip: number }} Bytes */
+/** @typedef {Bytes & { kind: 'inline-script'|'script'|'modulepreload'|'inline-style'|'stylesheet', ref: string, shared: boolean, file?: string }} Asset */
+/** @typedef {{ page: string, js: Bytes, jsOwn: Bytes, css: Bytes, assets: Asset[], html: string, external: string[], missing: { ref: string, from: string }[] }} PageCost */
+/**
+ * @typedef {object} MeasureOptions
+ * @property {RegExp} [own] which script refs count as the page's own; default: any `*astro_type_script*` chunk
+ * @property {string} [base] the site's `base` ("/docs"): stripped from root-relative refs, whose files sit at the top of dist
+ * @property {'throw'|'collect'} [missing] a referenced file that is not there: throw (the default), or list it in `missing`
+ * @property {Map<string, { text?: string, size: Bytes }>} [files] a cache shared by the pages of one build: the chunks
+ *   and stylesheets are the same files on every page, and gzipping them again for each page is most of the time
+ */
+
+const bytes = (s) => {
+  const b = typeof s === 'string' ? Buffer.from(s) : s;
+  return { raw: b.byteLength, gzip: gzipSync(b).byteLength };
+};
+
+/** Rollup names a page's own script `<file>.astro_astro_type_script_…js`; anything else it imports is a shared chunk. */
+const isShared = (ref) => !/astro_type_script/.test(ref);
+
+/** Another origin, a protocol-relative URL or a data: URL: not a file of this build. */
+const isExternal = (spec) => /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(spec);
+
+/** One attribute of a tag's attribute string, quoted either way or bare; '' when present without a value. */
+export function attr(attrs, name) {
+  const m = attrs.match(new RegExp(`(?:^|\\s)${name}(?:\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>\`]+))|(?=[\\s/>]|$))`, 'i'));
+  return m ? (m[1] ?? m[2] ?? m[3] ?? '') : undefined;
+}
+
+// The HTML standard runs a <script> as JavaScript when its type is absent or empty, "module", or a JavaScript MIME
+// type; any other type (application/json, application/ld+json, importmap, speculationrules, text/template) makes it a
+// data block the browser never executes, so it is not JavaScript the page costs (cb-23: Globe's 710 B JSON was counted).
+const JS_TYPES = /^(?:module|(?:text|application)\/(?:x-)?(?:java|ecma)script|text\/javascript1\.[0-5]|text\/(?:jscript|livescript))$/i;
+const runsAsScript = (attrs) => {
+  const type = attr(attrs, 'type')?.trim();
+  // a nomodule script is for browsers without modules: every browser that runs the page's modules skips it
+  return (type === undefined || type === '' || JS_TYPES.test(type)) && attr(attrs, 'nomodule') === undefined;
+};
+
+/**
+ * Sum every byte of JS and CSS a page causes the browser to load.
+ * @param {string} distDir @param {string} htmlPath @param {MeasureOptions} [options] @returns {PageCost}
+ */
+export function measurePage(distDir, htmlPath, options = {}) {
+  const html = readFileSync(htmlPath, 'utf8');
+  // a script in an HTML comment never runs
+  const live = html.replace(/<!--[\s\S]*?-->/g, '');
+  const page = '/' + relative(distDir, htmlPath).split(sep).join('/');
+  const base = options.base && options.base !== '/' ? `/${options.base.replace(/^\/+|\/+$/g, '')}` : '';
+  /** @type {Asset[]} */
+  const assets = [];
+  const external = [];
+  const missing = [];
+  /** A file of the build: its text when it is a script (to follow its imports), and its size. */
+  const read = (file, text) => {
+    const hit = options.files?.get(file);
+    if (hit && (hit.text !== undefined || !text)) return hit;
+    const entry = text ? { text: readFileSync(file, 'utf8') } : {};
+    entry.size = bytes(entry.text ?? readFileSync(file));
+    options.files?.set(file, entry);
+    return entry;
+  };
+  const locate = (ref) => join(distDir, base && (ref === base || ref.startsWith(`${base}/`)) ? ref.slice(base.length) || '/' : ref);
+  const lost = (ref, from, kind) => {
+    if (options.missing !== 'collect') throw new Error(`Referenced ${kind} missing: ${ref} (from ${from})`);
+    missing.push({ ref, from });
+  };
+
+  // Follow static and dynamic imports so shared chunks (e.g. the runtime, split out once two pages use it) are
+  // attributed to every page that loads them.
+  const seen = new Set();
+  const addChunk = (spec, kind, importer = page) => {
+    if (isExternal(spec)) {
+      if (!external.includes(spec)) external.push(spec);
+      return;
+    }
+    // Chunks import each other with relative specifiers; HTML uses root-relative ones.
+    const ref = spec.startsWith('/') ? spec : posix.join(posix.dirname(importer), spec);
+    if (seen.has(ref)) return;
+    seen.add(ref);
+    const file = locate(ref);
+    if (!existsSync(file)) return lost(ref, importer, kind);
+    const { text, size } = read(file, true);
+    assets.push({ kind, ref, shared: options.own ? !options.own.test(ref) : isShared(ref), ...size, file });
+    for (const dep of importsOf(text)) addChunk(dep, 'script', ref);
+  };
+
+  for (const m of live.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) {
+    const attrs = m[1] ?? '';
+    if (!runsAsScript(attrs)) continue;
+    const src = attr(attrs, 'src');
+    if (src) {
+      addChunk(src, 'script');
+    } else if (m[2]?.trim()) {
+      // Classic (non-module) inline scripts come from integration head-inline
+      // injections such as the data-ma-js gate: a site-wide constant, not a component's cost.
+      const isModule = attr(attrs, 'type')?.trim().toLowerCase() === 'module';
+      assets.push({ kind: 'inline-script', ref: `inline#${assets.length}${isModule ? '' : ':classic'}`, shared: !isModule, ...bytes(m[2]) });
+      for (const dep of importsOf(m[2])) addChunk(dep, 'script');
+    }
+  }
+  // Islands load their component and renderer through attributes on <astro-island>, not <script>
+  // tags; the browser fetches them all the same, so they count (React, ReactDOM, the framework
+  // runtime and the component itself arrive this way).
+  for (const m of live.matchAll(/<astro-island\b([^>]*)>/g)) {
+    for (const key of ['component-url', 'renderer-url', 'before-hydration-url']) {
+      const url = attr(m[1] ?? '', key);
+      if (url) addChunk(url, 'script');
+    }
+  }
+  for (const m of live.matchAll(/<link\b([^>]*)>/gi)) {
+    const attrs = m[1] ?? '';
+    const rel = (attr(attrs, 'rel') ?? '').toLowerCase().split(/\s+/);
+    const href = attr(attrs, 'href');
+    if (!href) continue;
+    if (rel.includes('modulepreload')) addChunk(href, 'modulepreload');
+    if (rel.includes('stylesheet')) {
+      if (isExternal(href)) {
+        if (!external.includes(href)) external.push(href);
+        continue;
+      }
+      const file = locate(href);
+      if (!existsSync(file)) {
+        lost(href, page, 'stylesheet');
+        continue;
+      }
+      assets.push({ kind: 'stylesheet', ref: href, shared: false, ...read(file, false).size, file });
+    }
+  }
+  for (const m of live.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)) {
+    if (m[1]?.trim()) assets.push({ kind: 'inline-style', ref: `inline#${assets.length}`, shared: false, ...bytes(m[1]) });
+  }
+
+  const sum = (kinds, ownOnly = false) =>
+    assets
+      .filter((a) => kinds.includes(a.kind) && (!ownOnly || !a.shared))
+      .reduce((acc, a) => ({ raw: acc.raw + a.raw, gzip: acc.gzip + a.gzip }), { raw: 0, gzip: 0 });
+
+  const JS = ['inline-script', 'script', 'modulepreload'];
+  return { page: htmlPath, js: sum(JS), jsOwn: sum(JS, true), css: sum(['inline-style', 'stylesheet']), assets, html, external, missing };
+}
+
+/** Root-relative module specifiers a script body imports, statically or dynamically. */
+export function importsOf(body) {
+  const out = [];
+  for (const m of body.matchAll(/(?:\bfrom\s*|\bimport\s*\(?\s*)["']((?:\.{0,2}\/)[^"']+\.m?js)["']/g)) out.push(m[1]);
+  return out;
+}
+
+/** The name Rollup gives a chunk: `Reveal.astro_astro_type_script_index_0_lang.V9DYN4Ia.js` is Reveal, `runtime.B9PHC9Fq.js` is runtime. */
+export const chunkName = (ref) => ref.split('/').pop().replace(/\.astro_astro_type_script.*$/, '').replace(/\.[\w-]+\.m?js$/, '');
+
+// A framework's runtime, by what its bundle contains: Rollup names a renderer chunk `client.<hash>.js` whatever the
+// framework, so the name says nothing.
+const FRAMEWORKS = [
+  ['React', /react-dom|\breact\.(?:transitional\.)?element\b/],
+  ['Preact', /\bpreact\b/],
+  ['Vue', /__vue_app__|__VUE_/],
+  ['Svelte', /\bsvelte\b/],
+  ['Solid', /\bsolid-js\b|_\$HY\b/],
+];
+
+const isDir = (p) => existsSync(p) && statSync(p).isDirectory();
+function* pagesIn(dir) {
+  for (const f of readdirSync(dir).sort()) {
+    const p = join(dir, f);
+    if (statSync(p).isDirectory()) yield* pagesIn(p);
+    else if (f.endsWith('.html')) yield p;
+  }
+}
+
+/** The URL a page answers at: index.html is /, about/index.html is /about/, 404.html is /404. */
+const routeOf = (root, file) => {
+  const rel = relative(root, file).split(sep).join('/');
+  if (rel === 'index.html') return '/';
+  if (rel.endsWith('/index.html')) return `/${rel.slice(0, -'index.html'.length)}`;
+  return `/${rel.replace(/\.html$/, '')}`;
+};
+
+/**
+ * Every prerendered page of a build. A server build (dist/client beside dist/server) is measured in client/, the half
+ * the browser downloads; a route rendered on demand has no HTML file there, so it is not in the result.
+ * @param {string} dir the folder astro build wrote
+ * @param {{ ceiling?: number, base?: string, library?: Set<string> }} [options] `library`: chunk names that are Moonarc's
+ */
+export function measureDist(dir, { ceiling, base, library = new Set() } = {}) {
+  if (!isDir(dir)) throw new Error(`No such folder: ${dir}. Build first (astro build), then pass the folder it wrote.`);
+  const adapter = isDir(join(dir, 'client')) && isDir(join(dir, 'server'));
+  const root = adapter ? join(dir, 'client') : dir;
+  const files = [...pagesIn(root)];
+  if (files.length === 0) throw new Error(`No HTML pages in ${root}. Pass the folder astro build wrote: dist, which holds client/ and server/ after a server build.`);
+
+  const cache = new Map();
+  const found = new Map();
+  const frameworksOf = (file) => {
+    if (!found.has(file)) found.set(file, FRAMEWORKS.filter(([, re]) => re.test(cache.get(file)?.text ?? '')).map(([name]) => name));
+    return found.get(file);
+  };
+  const missing = [];
+  const routes = files.map((file) => {
+    const cost = measurePage(root, file, { base, missing: 'collect', files: cache });
+    const route = routeOf(root, file);
+    for (const m of cost.missing) missing.push({ ...m, route });
+    const js = cost.assets.filter((a) => a.kind !== 'inline-style' && a.kind !== 'stylesheet');
+    const share = (test) => js.filter((a) => test(a.ref)).reduce((n, a) => n + a.raw, 0);
+    const frameworks = [...new Set(js.filter((a) => a.file).flatMap((a) => frameworksOf(a.file)))];
+    return {
+      route,
+      total: cost.js,
+      css: cost.css,
+      router: share((ref) => /(^|\/)ClientRouter\.astro_astro_type_script/.test(ref)),
+      lib: share((ref) => !ref.startsWith('inline#') && library.has(chunkName(ref))),
+      islands: [...cost.html.replace(/<!--[\s\S]*?-->/g, '').matchAll(/<astro-island\b/g)].length,
+      frameworks,
+      external: cost.external,
+      assets: cost.assets,
+    };
+  });
+
+  if (missing.length) {
+    const refs = [...new Set(missing.map((m) => m.ref))];
+    throw new Error(`${refs.length === 1 ? 'A file the pages load is' : `${refs.length} files the pages load are`} not in ${root}: ${refs.slice(0, 3).join(', ')}${refs.length > 3 ? ', …' : ''} (first on ${missing[0].route}). ${baseHint(root, refs[0], base) ?? 'Build again, and pass the folder astro build wrote.'}`);
+  }
+  routes.sort((a, b) => b.total.raw - a.total.raw || a.route.localeCompare(b.route));
+  const over = ceiling != null ? routes.filter((r) => r.total.raw > ceiling).map((r) => r.route) : [];
+  return { dist: root, layout: adapter ? 'server' : 'static', ceiling: ceiling ?? null, base: base ?? null, routes, over, external: [...new Set(routes.flatMap((r) => r.external))] };
+}
+
+/** A site built with `base: '/docs'` loads /docs/_astro/x.js from dist/_astro/x.js: say so when that is what is missing. */
+function baseHint(root, ref, base) {
+  if (base || !ref.startsWith('/')) return null;
+  const parts = ref.split('/').filter(Boolean);
+  for (let i = 1; i < parts.length; i++) {
+    if (existsSync(join(root, ...parts.slice(i)))) {
+      const guess = `/${parts.slice(0, i).join('/')}`;
+      return `The site looks built with base "${guess}": pass it as base (--base ${guess} on the command line).`;
+    }
+  }
+  return null;
+}
+
+const fmt = (b) => (b < 1024 ? `${b} B` : `${(b / 1024).toFixed(1)} kB`);
+
+export function formatMeasure(r) {
+  const lines = r.routes.map((x) => {
+    const flags = [
+      x.islands ? `⚠ ${x.islands} island${x.islands === 1 ? '' : 's'}${x.frameworks.length ? ` (${x.frameworks.join(', ')})` : ''}` : x.frameworks.length ? `⚠ ${x.frameworks.join(', ')} runtime` : '',
+      x.external.length ? `+ ${x.external.length} from another origin, not measured` : '',
+    ].filter(Boolean);
+    return `  ${x.total.raw > (r.ceiling ?? Infinity) ? '✗' : '✓'} ${x.route.padEnd(36)} ${fmt(x.total.raw).padStart(8)} raw  ${fmt(x.total.gzip).padStart(8)} gzip   router ${fmt(x.router)} raw  moonarc ${fmt(x.lib)} raw${flags.length ? `  ${flags.join('  ')}` : ''}`;
+  });
+  const head = `moonarc measure · ${r.routes.length} routes${r.ceiling != null ? ` · ceiling ${fmt(r.ceiling)} raw` : ''}${r.over.length ? ` · ${r.over.length} over` : ''}`;
+  const where = `  ${r.dist}${r.layout === 'server' ? ': the client half of a server build (a route rendered on demand has no HTML here)' : ''}${r.base ? `, base ${r.base}` : ''}`;
+  const external = r.external.length ? [`  not measured, from another origin: ${r.external.join(', ')}`] : [];
+  return [head, where, ...lines, ...external].join('\n');
+}