@orbytes/astrolab 0.3.0

package/src/pin/shot.mjs

@@ -0,0 +1,427 @@
+// orbytes-pin — the screenshot.
+//
+// ONE chromium for the whole dev session, launched lazily on the first pin and kept warm
+// (../../docs/PIN-CONTRACT.md § Screenshots). A cold launch costs over a second; a warm one is a page
+// open. You never wait on either, because index.mjs replies to the browser before this runs.
+//
+// None of the four capture settings below is a default. Each was worked out against a real site,
+// and each is there because its absence produced a wrong picture:
+//   · freeze motion BOTH ways — `reducedMotion: "reduce"` only reaches a section that authored a
+//     prefers-reduced-motion block, and an injected `animation:none` cannot touch motion driven
+//     by JS or a canvas. The site it was written against runs lenis and motion, so on a real
+//     orbytes build neither half is optional.
+//   · settle every image before the shutter — a lazy image below the fold shoots as a white hole
+//     that is indistinguishable from a real missing image.
+//   · hide the dev toolbar.
+//   · delete the destination FIRST, so a timeout leaves no stale PNG that reads like a success.
+//
+// Two decisions are this file's own and are argued here rather than inherited:
+//   · The page is scrolled to the payload's `scroll` position before the shutter. The contract's
+//     rect is already in DOCUMENT coordinates and Playwright's `clip` is document-relative when
+//     `fullPage: true` is set (see the screenshot call — the contract omits that flag, and the
+//     claim is false without it), so
+//     this is not clip maths (the contract forbids that) — it is reproducing what was on screen
+//     when the pin was placed, which matters because a JS scroll-reveal leaves an out-of-view section at
+//     opacity 0 and an `animation:none` stylesheet cannot undo an inline style.
+//   · The unpainted-image refusal is scoped to images that OVERLAP the clip. Refusing on any
+//     unpainted image anywhere is right for a whole-page render; here it would throw away a good
+//     screenshot over a hole in a different section.
+//
+// `url` is the document the picker measured `rect` and `selector` IN, which since 2026-09-21 is
+// not always the page that was on screen. The component lab renders every story inside a
+// same-origin <iframe> of `/lab/stories/<id>`, and the picker now descends into it, so a lab pin
+// arrives here carrying the STORY's url, the story window's viewport and scroll, and a rect in
+// the story document's own coordinates. That is the only combination this file can act on: it
+// re-loads `url` and clips `rect` against whatever comes back, so a url naming the shell and a
+// rect measured inside the frame would photograph the wrong document and say nothing about it.
+// The four travel together or not at all — and `verifyClip` below refuses the shot when the page
+// that loaded cannot contain the rect it was handed (› verifyClip).
+//
+// And one job that is not a screenshot at all, here because this is the only place that has what
+// it needs (› countSelector). This file already loads the page FRESH in a real browser — a second
+// process, a second DOM, every framework re-initialised from scratch. That is precisely the
+// negative control a selector needs: the pick-time page cannot tell you whether a selector
+// survives a reload, because it IS the load the selector was written against. So before the
+// shutter we ask the fresh page how many nodes the ticket's selector actually finds, and write
+// the answer back into the ticket. It costs one `querySelectorAll` on a page that is already
+// open. A ticket whose selector died is still workable by hand — source file, screenshot and
+// outer_html are all correct — so it is labelled, never discarded. The defect was the silence.
+//
+// `playwright` is loaded by DYNAMIC import inside getBrowser(), never at module scope, and that is
+// load-bearing rather than tidy. It is an OPTIONAL peer (package.json
+// `peerDependenciesMeta.playwright.optional`) and the integration has a `shots: false` option that
+// says screenshots are not wanted — but a static import here is reached from the package root
+// entry, so a site without playwright installed could not even LOAD its astro.config, let alone
+// run with shots off. The promise and the code disagreed; the code is now the one that changed.
+// Found on the move into astrolab, 2026-09-22.
+import { linkSync, mkdirSync, copyFileSync, readdirSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { PIN_FENCE, recordSelectorMatches } from "./tickets.mjs";
+import { readFileSync } from "node:fs";
+
+const FREEZE_CSS =
+  "*,*::before,*::after{animation:none!important;transition:none!important;" +
+  "animation-duration:0s!important;transition-duration:0s!important;" +
+  "animation-delay:0s!important;transition-delay:0s!important;" +
+  "animation-play-state:paused!important;caret-color:transparent!important;scroll-behavior:auto!important}" +
+  "html{scroll-behavior:auto!important}video,marquee{animation-play-state:paused!important}";
+
+const TOOLBAR_CSS = "astro-dev-toolbar{display:none!important}";
+
+let browser = null;
+let launching = null; // single-flight, so two pins in the same tick cannot launch two chromiums
+let launchMs = null;
+
+/**
+ * playwright, loaded on demand. One sentence when it is not installed, not a resolution stack:
+ * this is an optional peer, and the honest answer is "install it, or turn shots off".
+ */
+async function loadChromium() {
+  try {
+    const { chromium } = await import("playwright");
+    return chromium;
+  } catch (e) {
+    throw new Error(
+      "orbytes-pin cannot take screenshots: playwright is not installed. " +
+        "Run `npm i -D playwright && npx playwright install chromium`, or pass " +
+        "`pin: { shots: false }` to orbytesLab() to write tickets without pictures. " +
+        `(${String(e?.message ?? e).split("\n")[0]})`,
+    );
+  }
+}
+
+/** The warm browser, launched on first use. */
+export async function getBrowser() {
+  if (browser?.isConnected()) return browser;
+  if (!launching) {
+    const started = Date.now();
+    launching = loadChromium()
+      .then((chromium) => chromium.launch())
+      .then((b) => {
+        browser = b;
+        launchMs = Date.now() - started;
+        // A crash must not leave a dead handle that every later pin reuses.
+        b.once("disconnected", () => { if (browser === b) browser = null; });
+        return b;
+      })
+      .finally(() => { launching = null; });
+  }
+  return launching;
+}
+
+/** Milliseconds the cold launch took, or null if the browser has not been launched yet. */
+export const coldLaunchMs = () => launchMs;
+
+/** Close the warm browser. Idempotent; safe to call on a server that never took a shot. */
+export async function close() {
+  const b = browser;
+  browser = null;
+  if (b) await b.close().catch(() => {});
+}
+
+/**
+ * The ticket file this shot belongs to.
+ *
+ * `ticketFile` is the caller's job and the documented route. The derivation from the PNG path is
+ * a deliberate fallback, not a shortcut: the screenshot's basename IS the ticket number
+ * (`pin-007.png` ↔ `pin-007-<slug>.md`) and `link` is `<repo>/<backlogDir>/assets/pin-007.png`,
+ * so `../tasks` is one directory hop away. It exists so that the truth still reaches the ticket
+ * if a caller is written that forgets to pass the path — a fix that silently stops running is
+ * the same class of defect as the one it fixes.
+ *
+ * @returns {string|null} absolute path, or null when nothing on disk answers to that number
+ */
+function ticketFor({ ticketFile, link, dest }) {
+  if (ticketFile) return ticketFile;
+  const png = link || dest;
+  if (!png) return null;
+  const num = /^pin-(\d+)\.png$/.exec(basename(png));
+  if (!num) return null;
+  const tasks = join(dirname(dirname(png)), "tasks");
+  let names;
+  try {
+    names = readdirSync(tasks);
+  } catch {
+    return null;
+  }
+  const hit = names.find((n) => n.startsWith(`pin-${num[1]}-`) && n.endsWith(".md"));
+  return hit ? join(tasks, hit) : null;
+}
+
+/** The `selector:` line out of a ticket's pin block. Used only when the caller did not pass one. */
+function selectorFromTicket(absolute) {
+  let text;
+  try {
+    text = readFileSync(absolute, "utf8");
+  } catch {
+    return null;
+  }
+  const fence = text.indexOf(PIN_FENCE);
+  if (fence === -1) return null;
+  const end = text.indexOf("\n```", fence + PIN_FENCE.length);
+  const m = /^selector:[ \t]*(.*)$/m.exec(text.slice(fence, end === -1 ? undefined : end));
+  if (!m) return null;
+  const raw = m[1].trim();
+  if (raw.startsWith("'") && raw.endsWith("'") && raw.length > 1) return raw.slice(1, -1).replace(/''/g, "'");
+  if (raw.startsWith('"') && raw.endsWith('"') && raw.length > 1) return raw.slice(1, -1);
+  return raw || null;
+}
+
+/**
+ * How many nodes `selector` matches on the fresh page. `null` when the question could not be
+ * asked at all — no selector to test, or a selector the browser refuses to parse.
+ *
+ * Note the two truths this does NOT conflate. Zero is an answer: the selector is dead, and the
+ * ticket says so. `null` is the absence of an answer, and it leaves the ticket reading `pending`
+ * — which is also true, because nothing was tested. Neither is ever rounded to "fine".
+ */
+async function countSelector(page, selector) {
+  if (typeof selector !== "string" || selector.trim() === "") return null;
+  return page.evaluate((sel) => {
+    try {
+      return document.querySelectorAll(sel).length;
+    } catch {
+      return null; // not a selector this browser will parse — an answer nobody can give
+    }
+  }, selector);
+}
+
+/** Do two boxes share any area at all? */
+const overlaps = (a, b) =>
+  a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+
+const box = (r) => `${Math.round(r.width)}x${Math.round(r.height)} at (${Math.round(r.x)}, ${Math.round(r.y)})`;
+
+/**
+ * Refuse a clip the loaded page cannot be describing.
+ *
+ * The failure this exists for is silent by construction. `rect` is in document coordinates of
+ * whichever document the picker measured it in; if `url` names a different one — the lab shell
+ * instead of the story inside its iframe — the clip still lands somewhere, the PNG is still
+ * written, `selector_matches` is still counted, and every trail behind it reads clean. The
+ * picture is simply of the wrong thing, and nothing on the ticket says so.
+ *
+ * So this REFUSES rather than warns (a guard that warns is not a guard). Two checks, both of
+ * which are the same question — can this page contain that rect? — and both scoped to
+ * disagreements that cannot be a layout shift:
+ *
+ *   1. the clip must share some area with the loaded document's own scrollable box. A rect from
+ *      a taller page hangs off the bottom of a short one entirely;
+ *   2. when the selector resolves to EXACTLY ONE node on this page, that node's document rect
+ *      must share some area with the clip. One node is the only case where there is an
+ *      unambiguous answer to compare against; 0 and 2+ are already reported as such.
+ *
+ * Zero overlap, not "close enough": a lazy image settling or a font swapping can move an element
+ * by hundreds of pixels and that is a healthy shot, so the line is drawn where the picture
+ * provably cannot contain the element rather than where it is merely off.
+ *
+ * @throws with a plain sentence naming both boxes and the url.
+ */
+async function verifyClip(page, { url, clip, selector, matches }) {
+  const seen = await page.evaluate(
+    ({ sel, one }) => {
+      const doc = document.documentElement;
+      const out = {
+        page: { x: 0, y: 0, width: doc.scrollWidth, height: doc.scrollHeight },
+        node: null,
+      };
+      if (one && sel) {
+        const el = document.querySelector(sel);
+        if (el) {
+          const r = el.getBoundingClientRect();
+          out.node = { x: r.left + scrollX, y: r.top + scrollY, width: r.width, height: r.height };
+        }
+      }
+      return out;
+    },
+    { sel: selector, one: matches === 1 },
+  );
+
+  if (!overlaps(clip, seen.page)) {
+    throw new Error(
+      `the clip ${box(clip)} falls entirely outside ${url}, whose document is ${box(seen.page)} — ` +
+        `that rect was measured in a different document, so this would photograph the wrong page`,
+    );
+  }
+  if (seen.node && !overlaps(clip, seen.node)) {
+    throw new Error(
+      `on ${url} the ticket's selector finds one element at ${box(seen.node)}, which does not ` +
+        `overlap the clip ${box(clip)} at all — the rect and the selector describe different ` +
+        `documents, so this would photograph the wrong thing`,
+    );
+  }
+}
+
+/**
+ * Capture one pin.
+ *
+ * @param {object} o
+ * @param {string} o.origin   the dev server's own origin — read from Vite, never hardcoded
+ * @param {string} o.url      site path, e.g. "/" or "/about?x=1"
+ * @param {{width:number,height:number,dpr:number}} o.viewport
+ * @param {{x:number,y:number}} o.scroll
+ * @param {{x:number,y:number,width:number,height:number}} o.rect  DOCUMENT coordinates
+ * @param {string} o.dest     absolute path of the canonical copy (the archive)
+ * @param {string} [o.link]   absolute path to hardlink the canonical copy to (the board's assets)
+ * @param {string} [o.selector]   the ticket's CSS selector, re-counted on the fresh page
+ * @param {string} [o.ticketFile] absolute path of the ticket to record the count in
+ * @param {(msg:string)=>void} [o.log]
+ * @returns {Promise<{ ms:number, cold:boolean, linked:"hardlink"|"copy"|"none", selectorMatches:number|null }>}
+ *   `selectorMatches` is the node count on the fresh load: 1 is healthy, 0 means the selector is
+ *   dead, more than 1 means it is ambiguous, and null means the question could not be asked.
+ */
+export async function shoot({ origin, url, viewport, scroll, rect, dest, link, selector, ticketFile, log = () => {} }) {
+  const started = Date.now();
+  const cold = !browser?.isConnected();
+  const b = await getBrowser();
+
+  // Before anything can fail: nothing stale may survive this call under either name.
+  mkdirSync(dirname(dest), { recursive: true });
+  rmSync(dest, { force: true });
+  if (link) { mkdirSync(dirname(link), { recursive: true }); rmSync(link, { force: true }); }
+
+  const width = Math.max(320, Math.round(Number(viewport.width) || 1440));
+  const height = Math.max(240, Math.round(Number(viewport.height) || 960));
+  const page = await b.newPage({
+    viewport: { width, height },
+    deviceScaleFactor: Math.min(3, Math.max(1, Number(viewport.dpr) || 1)),
+    reducedMotion: "reduce",
+  });
+
+  try {
+    const target = new URL(url, origin).href;
+    const response = await page.goto(target, { waitUntil: "networkidle" });
+    if (!response) throw new Error(`${url} returned no response`);
+    if (response.status() >= 400) throw new Error(`${url} answered ${response.status()}`);
+
+    await page.addStyleTag({ content: TOOLBAR_CSS });
+    await page.addStyleTag({ content: FREEZE_CSS });
+    await page.evaluate(() => {
+      for (const v of document.querySelectorAll("video")) { try { v.pause(); v.currentTime = 0; } catch {} }
+    });
+
+    // Settle: force every lazy image to load, decode them, wait for fonts, then take up the
+    // position the pin was placed at so a scroll-reveal has fired.
+    // The sweep stops one viewport past the bottom of the clip rather than walking the whole
+    // document: an image below the clip cannot appear in this shot, and on a long page the
+    // difference is seconds of 50 ms steps for nothing.
+    await page.evaluate(async ({ to, until }) => {
+      for (const img of document.querySelectorAll("img")) {
+        img.loading = "eager";
+        img.setAttribute("fetchpriority", "high");
+        if (img.dataset.src && !img.src) img.src = img.dataset.src;
+      }
+      const step = Math.max(200, Math.floor(innerHeight / 2));
+      const last = Math.min(document.documentElement.scrollHeight, until);
+      for (let y = 0; y <= last; y += step) {
+        scrollTo(0, y);
+        await new Promise((r) => setTimeout(r, 50));
+      }
+      scrollTo(to.x, to.y);
+      await new Promise((r) => setTimeout(r, 120));
+      await Promise.all([...document.querySelectorAll("img")].map((i) => (i.decode ? i.decode().catch(() => {}) : null)));
+      if (document.fonts) await document.fonts.ready;
+    }, {
+      to: { x: Math.round(Number(scroll?.x) || 0), y: Math.round(Number(scroll?.y) || 0) },
+      until: Math.round(Number(rect.y) + Number(rect.height)) + height,
+    });
+
+    // A smooth-scroll library (lenis, here) animates towards the target after the settle pass.
+    // Shooting mid-flight moves every pixel in frame, so hold until the position stops changing.
+    const want = { x: Math.round(Number(scroll?.x) || 0), y: Math.round(Number(scroll?.y) || 0) };
+    for (let i = 0; i < 20; i++) {
+      const stable = await page.evaluate(async (to) => {
+        scrollTo(to.x, to.y);
+        const a = scrollY;
+        await new Promise((r) => setTimeout(r, 50));
+        return Math.abs(a - scrollY) < 1;
+      }, want);
+      if (stable) break;
+    }
+    await page.waitForTimeout(150);
+
+    const clip = {
+      x: Math.max(0, Math.round(Number(rect.x))),
+      y: Math.max(0, Math.round(Number(rect.y))),
+      width: Math.max(1, Math.round(Number(rect.width))),
+      height: Math.max(1, Math.round(Number(rect.height))),
+    };
+
+    // Scoped refusal: an image that OVERLAPS the clip and is still unpainted would shoot as a
+    // hole, and a hole is indistinguishable from a real missing image. Images elsewhere on the
+    // page are none of this shot's business.
+    const holes = await page.evaluate((c) => {
+      return [...document.querySelectorAll("img")]
+        .filter((i) => {
+          const r = i.getBoundingClientRect();
+          const x = r.left + scrollX, y = r.top + scrollY;
+          return x < c.x + c.width && x + r.width > c.x && y < c.y + c.height && y + r.height > c.y;
+        })
+        .filter((i) => !i.complete || i.naturalWidth === 0)
+        .map((i) => i.currentSrc || i.src);
+    }, clip);
+    if (holes.length) {
+      throw new Error(`${holes.length} image(s) inside the clip are still unpainted — refusing to shoot a hole and call it a screenshot`);
+    }
+
+    // `fullPage: true` is what MAKES the contract's "clip is document-relative" true, and it is
+    // not optional. Measured 2026-09-21 on playwright 1.63.0: without it, `clip` is relative to
+    // the VIEWPORT and a clip below the fold throws "Clipped area is either empty or outside the
+    // resulting image" — the contract's rect, which is in document coordinates, would never
+    // shoot. With it, Chromium rasterises the clip region alone, not the whole page: a clip at
+    // y=25000 on a 30,200px page at dpr 2 took 78 ms and produced a 2.8 KB file. So the contract
+    // still holds — no scroll maths is added to the rect — but the flag has to be there.
+    // The fresh-load selector count, taken HERE: after the settle pass, on the same DOM the
+    // shutter is about to photograph, so the number and the picture describe one moment. Any
+    // earlier and a scroll-revealed or carousel-driven element would be counted in a state the
+    // screenshot does not show.
+    const ticket = ticketFor({ ticketFile, link, dest });
+    const probe = typeof selector === "string" && selector.trim() !== ""
+      ? selector
+      : ticket
+        ? selectorFromTicket(ticket)
+        : null;
+    const selectorMatches = await countSelector(page, probe);
+
+    // Last thing before the shutter, and a refusal rather than a warning: a picture of the wrong
+    // document is worse than no picture, because a picture reads as the truth.
+    await verifyClip(page, { url, clip, selector: probe, matches: selectorMatches });
+
+    await page.screenshot({ path: dest, fullPage: true, clip });
+
+    // Recorded AFTER the shutter, so a shot that fails leaves the ticket honestly saying
+    // `pending` rather than claiming a check that produced no picture. A count of null is not
+    // written at all — there is nothing true to write.
+    if (ticket && Number.isInteger(selectorMatches)) {
+      try {
+        recordSelectorMatches(ticket, selectorMatches);
+      } catch (e) {
+        // Loud, because a count computed and then dropped is exactly the silence this fixes.
+        log(`could not record selector_matches=${selectorMatches} in ${basename(ticket)}: ${e.message}`);
+      }
+    } else if (probe && !ticket) {
+      log(`selector counted ${selectorMatches} times on a fresh load but no ticket file was found to record it in`);
+    }
+
+    let linked = "none";
+    if (link) {
+      try {
+        linkSync(dest, link);
+        linked = "hardlink";
+      } catch (e) {
+        // Different filesystem (the archive is under $HOME, the repo may not be) — say so.
+        copyFileSync(dest, link);
+        linked = "copy";
+        log(`hardlink failed (${e.code ?? e.message}); copied instead — two copies of this PNG now exist on disk`);
+      }
+    }
+    return { ms: Date.now() - started, cold, linked, selectorMatches };
+  } catch (e) {
+    // A failed shot leaves NO file behind under either name.
+    rmSync(dest, { force: true });
+    if (link) rmSync(link, { force: true });
+    throw e;
+  } finally {
+    await page.close().catch(() => {});
+  }
+}

package/src/pin/source-stamp.mjs

@@ -0,0 +1,159 @@
+// orbytes-pin — the source attribute.
+//
+// Astro 7 does NOT emit `data-astro-source-file` (../../docs/PIN-CONTRACT.md § Source attribution), so
+// this package injects its own at SECTION granularity: the first top-level element of every
+// `.astro` file under the configured directories gets `data-orbytes-src="<repo-relative path>"`,
+// and the picker walks up from the clicked node to the nearest ancestor carrying it.
+//
+// Two decisions make this safe to run over real files:
+//
+//  1. It is a `load` hook, not a `transform`. Astro's own `astro:build` plugin is `enforce: "pre"`
+//     and its `load` filter matches only `?astro` sub-requests, never the bare `.astro` id — so a
+//     `pre` load here always wins the bare id whatever the plugin order, and Astro's compiler
+//     receives the stamped source. A `transform` would race Astro's, which is also `pre`.
+//  2. The attribute is inserted immediately after the TAG NAME, not at the end of the opening tag.
+//     `<section` becomes `<section data-orbytes-src="…"`. Nothing else in the tag is parsed, so no
+//     attribute value, expression, spread or self-closing slash can be mangled, and because the
+//     insert adds no newline every line number in the file stays where it was.
+//
+// A matched file with no element to stamp THROWS naming the file (contract non-negotiable 3:
+// guards refuse, they do not warn). Two cases reach that throw — a template with no tag at all,
+// and a template whose first tag is a component (`<About01Hero />`): Astro passes an attribute on
+// a component as a prop, and a component that does not spread its props drops it silently, which
+// is precisely the wrong-result-with-a-clean-trail this refuses to produce. Exempt a file with
+// the `stampSkip` option, never with a warning.
+//
+// Error text is repo-relative on purpose: a thrown load error is rendered into Vite's browser
+// overlay, and an absolute /Users/... path there is the leak contract non-negotiable 2 forbids.
+import { readFileSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+
+const posix = (p) => p.split(sep).join("/");
+
+// The two comment forms that legally precede a template's root: an HTML comment, and the
+// JSX-style brace comment Astro also accepts.
+const COMMENTS = [
+  { open: "<!--", close: "-->" },
+  { open: "{/*", close: "*/}" },
+];
+
+/**
+ * Where the template begins: after the frontmatter fence, or 0 when there is none.
+ * The opening fence must be the first thing in the file (after an optional BOM); a `---` further
+ * down is a horizontal rule in the template and must not be mistaken for one.
+ */
+export function templateStart(code) {
+  const bom = code.charCodeAt(0) === 0xfeff ? 1 : 0;
+  if (!/^-{3}[ \t]*\r?\n/.test(code.slice(bom))) return bom;
+  const close = /\r?\n-{3}[ \t]*(\r?\n|$)/.exec(code.slice(bom));
+  if (!close) throw new Error("the frontmatter fence is opened and never closed");
+  return bom + close.index + close[0].length;
+}
+
+/**
+ * The offset just past the name of the first top-level HTML element, or a `reason` when there is
+ * none. Skips whitespace and both comment forms; refuses everything else.
+ * @returns {{ at: number, tag: string } | { reason: string }}
+ */
+export function findFirstElement(code, from) {
+  let i = from;
+  for (;;) {
+    while (i < code.length && /\s/.test(code[i])) i++;
+    const comment = COMMENTS.find((c) => code.startsWith(c.open, i));
+    if (!comment) break;
+    const end = code.indexOf(comment.close, i + comment.open.length);
+    if (end === -1) return { reason: `an unterminated ${comment.open} comment precedes the template's first element` };
+    i = end + comment.close.length;
+  }
+  if (i >= code.length) return { reason: "the template is empty" };
+  if (code[i] !== "<") {
+    return { reason: `the template opens with ${JSON.stringify(code.slice(i, i + 24))}, not an element` };
+  }
+  if (code.startsWith("<>", i)) return { reason: "the template's root is a fragment (<>), which renders no element to stamp" };
+  const name = /^<([A-Za-z][A-Za-z0-9._:-]*)/.exec(code.slice(i, i + 80));
+  if (!name) return { reason: `the template opens with ${JSON.stringify(code.slice(i, i + 24))}, not an element` };
+  const tag = name[1];
+  if (/^[A-Z]/.test(tag) || tag.includes(".")) {
+    return {
+      reason:
+        `the template's first top-level tag is the component <${tag}>, not an element. Astro passes an ` +
+        `attribute on a component as a prop, so the stamp would be dropped silently. Wrap it in an ` +
+        `element, or list this file in the integration's stampSkip option`,
+    };
+  }
+  return { at: i + name[0].length, tag };
+}
+
+const attrSafe = (p) => p.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+
+/**
+ * Stamp one `.astro` source. `relPath` is already repo-relative, posix-separated.
+ * Idempotent: a file that already carries the attribute on its first tag is returned unchanged.
+ * @throws when there is no element to stamp — with the repo-relative path in the message.
+ */
+export function stampSource(code, relPath) {
+  let start;
+  try {
+    start = templateStart(code);
+  } catch (e) {
+    throw new Error(`orbytes-pin cannot stamp ${relPath}: ${e.message}`);
+  }
+  const found = findFirstElement(code, start);
+  if ("reason" in found) throw new Error(`orbytes-pin cannot stamp ${relPath}: ${found.reason}.`);
+
+  // Idempotence is checked inside the opening tag only, so a stamp on a nested element (or the
+  // string appearing in a comment further down) never makes this a no-op.
+  const tagEnd = code.indexOf(">", found.at);
+  if (tagEnd !== -1 && code.slice(found.at, tagEnd).includes("data-orbytes-src")) return code;
+
+  return `${code.slice(0, found.at)} data-orbytes-src="${attrSafe(relPath)}"${code.slice(found.at)}`;
+}
+
+/**
+ * The dev-only Vite plugin.
+ *
+ * `dirs` and `skip` are both SITE-relative, and they are resolved the same way on purpose.
+ *
+ * Until the move into astrolab (2026-09-22) they were not: `dirs` resolved against `siteRoot`
+ * while `skip` was compared to a path made relative to `repoRoot`, so a live value had to carry a
+ * `site/` prefix that the option it sits beside must not have. The two agreed only in a repo whose
+ * app sits in `site/`, and they failed SILENTLY everywhere else — a root-shaped repo's exemption
+ * matched nothing, the file it named stopped being exempt, and the stamp's hard throw came back on
+ * a file somebody had already decided to let through. Nothing says so; the entry just stops
+ * working. A repo shape is exactly the thing that changes when a package moves, which is why it
+ * was fixed on the way in rather than found later.
+ *
+ * Both spellings are accepted — the site-relative one this option now documents, and the
+ * repo-relative one a config written before today carries — because an exemption that quietly
+ * lapses is the defect, and refusing the old spelling would recreate it once.
+ *
+ * @param {{ repoRoot: string, siteRoot: string, dirs: string[], skip?: string[] }} options
+ *   `dirs` are site-relative directories; `skip` are site-relative `.astro` paths exempt from the
+ *   throw (a repo-relative path is accepted too).
+ */
+export function sourceStampPlugin({ repoRoot, siteRoot, dirs, skip = [] }) {
+  const roots = dirs.map((d) => posix(resolve(siteRoot, d)) + "/");
+  // Absolute, so the comparison is against the id Vite hands `load` rather than against one of two
+  // possible relative spellings of it.
+  const exempt = new Set(
+    skip.flatMap((entry) => {
+      const raw = posix(String(entry)).replace(/^\.\//, "");
+      return [posix(resolve(siteRoot, raw)), posix(resolve(repoRoot, raw))];
+    }),
+  );
+  return {
+    name: "orbytes-pin/source-stamp",
+    // `pre` puts this ahead of every transform, and `serve` is the third assertion that nothing
+    // in this package can run in `astro build` (contract non-negotiable 1).
+    enforce: "pre",
+    apply: "serve",
+    load(id) {
+      const file = posix(id.split("?")[0]);
+      if (!file.endsWith(".astro")) return null;
+      if (!roots.some((r) => file.startsWith(r))) return null;
+      if (exempt.has(file)) return null;
+      const relPath = posix(relative(repoRoot, file));
+      return { code: stampSource(readFileSync(file, "utf8"), relPath), map: null };
+    },
+  };
+}