Files
luxe/scripts/site-cross.mjs
Evan Whittaker 3c69a90b06 A file lock waits out Windows removing the previous holder's lock; the site's header fits one row on a phone, the tools page draws its claims, and the README opens on the wordmark
- On Windows a lock directory being removed answers access denied, not already exists, so a
  second writer, such as two MCP servers signing in at once, failed instead of waiting.
- The header is Docs, Tools and the GitHub mark, one row down to 320px; /themes folds into the
  homepage's gallery and redirects there.
- The tools page has a terminal of measured rows beside its intro and a chart of whole-task cost
  against Luxe's 1x beside its table; Pi leaves the comparison.
- The README opens on a generated wordmark banner that carries its own colors.
2026-10-17 16:58:08 -05:00

404 lines
17 KiB
JavaScript

#!/usr/bin/env node
/**
* Opens the site in every browser engine the machine can run, and asserts the demos actually start.
*
* `site-check.sh` already drives the *built* site in headless Chrome, which is the right check for
* the thing it guards — a real CSP, real headers, no uncaught exceptions. This one exists because
* two separate bugs slipped past it, and both were invisible for the same two reasons.
*
* **One engine is not coverage.** The demo player is behind a dynamic `import()`, and Vite's dev
* server optimizes it mid-session and invalidates the graph it had already served. Chrome quietly
* re-requests. Firefox calls the interrupted response corrupted, refuses it for a disallowed MIME
* type, and every demo on the page stays blank for the rest of the session.
*
* **The built site is not the dev site.** That failure never touched a production bundle, so no
* amount of checking `dist/` would have found it — and `npm run dev` is what anyone actually looks
* at while working.
*
* So this drives `astro dev` by default, in Chromium, Firefox and WebKit, and asserts the islands
* boot rather than that the markup exists. An engine the host cannot launch is reported and
* skipped: Playwright's WebKit build wants Ubuntu's ICU and libxml2 sonames, which a rolling distro
* does not have, and refusing to run anywhere it is missing would just mean nobody runs it.
*
* node scripts/site-cross.mjs # astro dev, every engine available
* node scripts/site-cross.mjs --built # the built site, served statically
* node scripts/site-cross.mjs --require webkit # fail if that engine cannot launch
*/
import { spawn } from "node:child_process";
import { createServer } from "node:http";
import { readFile, rm } from "node:fs/promises";
import { createRequire } from "node:module";
import { extname, join, normalize } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
const web = fileURLToPath(new URL("../web/", import.meta.url));
/** Pages worth opening, and what has to be alive on each once it has settled. */
const PAGES = [
{ path: "/", demos: true, stills: true },
{ path: "/docs/", demos: false, stills: false },
];
/**
* Console noise that is the browser talking about itself rather than about us.
*
* Firefox warns about scroll-linked effects on any page with a scroll-driven reveal, which is a
* performance note about async panning and not a defect. Everything else is reported.
*/
const IGNORABLE = [
/scroll-linked positioning effect/i,
/\[vite\]/i,
/Download the .* DevTools/i,
// A *cancelled* request, not a failed one. The dev server's HMR client and the island scripts
// are routinely abandoned when a page settles, and Firefox reports that as a binding abort where
// Chrome says nothing at all. Three engines, three spellings for one condition — WebKit's was
// missing, so the optimizer reload that Chrome swallows and Firefox names failed the run outright
// on the engine nobody can reproduce locally.
/NS_BINDING_ABORTED/i,
/net::ERR_ABORTED/i,
/Load request cancelled/i,
];
/**
* Dev-server churn, which is Vite talking about itself.
*
* When the optimizer discovers a dependency it re-bundles and answers in-flight module requests
* with a 504, and its client recovers by reloading the page. Chrome swallows that silently; Firefox
* surfaces the rejected import first. Treating it as a defect makes this check fail on a page whose
* demos all started, which is a check nobody will keep.
*
* So dev is judged on its *end state* — did every island boot — and only the built site is held to
* zero errors. That still catches the failure this file was written for, because that one left the
* demos blank for the rest of the session rather than recovering.
*
* WebKit's spelling carries no URL, so unlike Firefox's it cannot be scoped to `.vite/deps`. It is
* forgiven anyway, and only here: a dev-only reload that recovers is not a defect, and holding one
* engine to a stricter rule than the other two only means its check gets switched off.
*/
const DEV_CHURN = [
/error loading dynamically imported module.*\.vite\/deps/i,
/Outdated Optimize Dep/i,
/Importing a module script failed/i,
];
const args = process.argv.slice(2);
const built = args.includes("--built");
const required = args.flatMap((arg, index) => (arg === "--require" ? [args[index + 1]] : []));
// === Serving ===
const MIME = {
".html": "text/html; charset=utf-8",
".js": "text/javascript; charset=utf-8",
".css": "text/css; charset=utf-8",
".svg": "image/svg+xml",
".json": "application/json",
".cast": "application/json",
".woff2": "font/woff2",
".png": "image/png",
".wasm": "application/wasm",
};
/** Serves `web/dist` the way a static host would, including the `.wasm` type the player needs. */
function serveBuilt(root) {
return new Promise((resolve) => {
const server = createServer(async (request, response) => {
const url = new URL(request.url ?? "/", "http://localhost");
const asked = normalize(join(root, decodeURIComponent(url.pathname)));
if (!asked.startsWith(root)) return response.writeHead(403).end();
// The type comes from the file that is actually sent, not from the path that was asked
// for. A directory has no extension, so deriving it from the URL served `index.html` as
// `application/octet-stream` — and a browser handed that downloads the page instead of
// rendering it, which surfaces as every engine failing to navigate.
for (const file of [asked, join(asked, "index.html")]) {
try {
const body = await readFile(file);
const type = MIME[extname(file)] ?? "application/octet-stream";
response.writeHead(200, { "content-type": type });
return response.end(body);
} catch {
/* try the next candidate */
}
}
response.writeHead(404).end("not found");
});
server.listen(0, () => resolve({ server, port: server.address().port }));
});
}
/**
* Starts `astro dev` on a cold dependency cache and waits for it to answer.
*
* The cache is cleared on purpose, and this is the whole reason the dev mode restarts the server
* per engine rather than sharing one. The failure being guarded against is a *race*: Vite optimizes
* the player the first time something asks for it, mid-session, and only the browser that arrives
* before that has happened is exposed to it. Run Chromium first against a shared server and it
* warms the cache for everyone — Firefox then sails through, the check goes green, and it has
* proved nothing. Verified by deleting the fix and watching this catch it.
*/
async function serveDev(port) {
await rm(join(web, "node_modules/.vite"), { recursive: true, force: true });
// Astro's own entry, not `npx`. A wrapper means the server is a *grandchild*, so stopping it
// needs a signal to the whole process group — and a group kill with the wrong pid takes the
// shell that launched this with it. Spawned directly, `child.kill()` is the server.
const child = spawn(
process.execPath,
[join(web, "node_modules/astro/bin/astro.mjs"), "dev", "--port", String(port)],
{ cwd: web, stdio: "ignore" },
);
return { child, port };
}
function shutdown(target) {
if (target?.server) target.server.close();
if (target?.child && !target.child.killed) {
target.child.kill("SIGTERM");
}
}
async function waitForServer(port, seconds = 90) {
for (let attempt = 0; attempt < seconds * 2; attempt += 1) {
try {
const response = await fetch(`http://localhost:${port}/`);
if (response.ok) return true;
} catch {
/* not up yet */
}
await new Promise((done) => setTimeout(done, 500));
}
return false;
}
// === Checking ===
/**
* Brings the hero to rest before anything is scrolled to.
*
* The hero's demo waits a screen below its place until the opening has played. Centring it from
* there scrolls the page to where it is *waiting*, the scroll assembles the hero, and the demo rises
* into its real place above the viewport — so whether it was ever seen depends on which frame each
* engine paints, and WebKit missed it. A reader never jumps to an element mid-assembly, so the check
* does what a reader's first scroll does and lets it settle.
*/
async function settleHero(tab) {
const assembling = await tab.evaluate(() => {
const hero = document.querySelector("[data-hero]");
if (!hero || getComputedStyle(hero).getPropertyValue("--p").trim() === "1") return false;
dispatchEvent(new Event("scroll"));
return true;
});
if (assembling) await tab.waitForTimeout(1400);
}
/**
* Whether each demo's terminal fills the frame the player sized it for, no wider and no narrower.
*
* The player sets its type from a measured `ch`, and Chromium then rounded each glyph's advance to a
* whole pixel, so a 120-cell line came out 120 roundings off: at this window the hero ran 7% off the
* right of its frame and cut the statusline mid-word, and at others it stopped short and left a
* margin of dead canvas. Nothing threw. Measured at 1600px and twice the density, because that is a
* size where the rounding goes the harmful way, and the system Chrome the smoke run drives already
* uses fractional advances and never showed it.
*/
async function demosFit(browser, port, path) {
const context = await browser.newContext({
viewport: { width: 1600, height: 1000 },
deviceScaleFactor: 2,
colorScheme: "dark",
});
const tab = await context.newPage();
const problems = [];
try {
await tab.goto(`http://localhost:${port}${path}`, { waitUntil: "networkidle" });
await settleHero(tab);
const demos = tab.locator(".demo");
const count = await demos.count();
for (let index = 0; index < count; index += 1) {
const demo = demos.nth(index);
await demo.evaluate((node) => node.scrollIntoView({ block: "center", behavior: "instant" }));
const started = await demo
.locator(".ap-line")
.first()
.waitFor({ timeout: 60_000 })
.then(() => true)
.catch(() => false);
if (!started) continue; // the boot check reports a demo that never starts
// The terminal against the frame the player sized it for. Its own width grows with its
// lines, so comparing those two with each other sees nothing
// Watched for a few seconds rather than read once: the terminal is as wide as its longest
// line so far, and a take whose first frame is short lines is narrow for that instant at
// the right scale. A rounding fault never comes right, so it still fails.
const measure = () =>
demo.evaluate((node) => ({
frame: node.querySelector(".ap-wrapper").getBoundingClientRect().width,
term: node.querySelector(".ap-term").getBoundingClientRect().width,
}));
const fits = (fit) => Math.abs(fit.term - fit.frame) <= Math.max(2, fit.frame * 0.01);
let fit = await measure();
for (let tries = 0; tries < 24 && !fits(fit); tries += 1) {
await tab.waitForTimeout(250);
fit = await measure();
}
if (!fits(fit)) {
problems.push(
`${path}: demo ${index + 1} is ${fit.term.toFixed(0)}px in a ` +
`${fit.frame.toFixed(0)}px frame — glyph advances are being rounded`,
);
}
}
} finally {
await context.close();
}
return problems;
}
/**
* Opens every page in one engine and reports what went wrong.
*
* The assertion that matters is `players === mounts`: markup being present proves the component
* rendered, and every failure this file exists for left the markup perfectly intact and the island
* dead inside it.
*/
async function checkEngine(engine, name, port) {
const browser = await engine.launch();
const problems = [];
try {
for (const page of PAGES) {
const context = await browser.newContext({
viewport: { width: 1440, height: 900 },
colorScheme: "dark",
});
const tab = await context.newPage();
const noise = [];
tab.on("pageerror", (error) => noise.push(`uncaught: ${error}`));
tab.on("console", (message) => {
if (message.type() === "error") noise.push(`console: ${message.text()}`);
});
tab.on("requestfailed", (request) => {
noise.push(`request failed: ${request.url()} (${request.failure()?.errorText})`);
});
await tab.goto(`http://localhost:${port}${page.path}`, { waitUntil: "networkidle" });
await settleHero(tab);
if (page.demos) {
// A demo waits until most of it is on screen before it starts, so bringing its top edge
// into view is not enough to ask whether it works — `scrollIntoViewIfNeeded` scrolls the
// minimum distance, which for a demo taller than half the viewport leaves it below the
// threshold and looking broken. Centring it is what a reader does.
const demos = tab.locator(".demo");
const count = await demos.count();
for (let index = 0; index < count; index += 1) {
const demo = demos.nth(index);
await demo.evaluate((node) =>
node.scrollIntoView({ block: "center", behavior: "instant" }),
);
// Scoped to *this* demo rather than to the page's nth player: they start lazily now,
// so a global index counts whichever happened to boot first.
//
// Generous, because a demo plays once and never pauses: by the time this asks
// about the fifth, four players are still rendering frames behind it. That is
// what a reader scrolling the page has too, but on a shared CI runner it starved
// the later ones past a 20s budget — which failed a different demo each run, in
// one engine, on a page nothing had changed. The claim being made is that a demo
// *starts*, not that it starts inside some particular second.
await demo
.locator(".ap-player")
.waitFor({ timeout: 60_000 })
.catch(() => problems.push(`${page.path}: demo ${index + 1} never started`));
}
if (count === 0) problems.push(`${page.path}: no demos on the page at all`);
}
if (page.stills && (await tab.locator(".still__img").count()) === 0) {
problems.push(`${page.path}: no stills on the page at all`);
}
if (page.demos) problems.push(...(await demosFit(browser, port, page.path)));
const forgiven = built ? IGNORABLE : [...IGNORABLE, ...DEV_CHURN];
for (const line of noise) {
if (!forgiven.some((pattern) => pattern.test(line))) problems.push(`${page.path}: ${line}`);
}
await context.close();
}
} finally {
await browser.close();
}
return problems;
}
// === Run ===
// Resolved against `web/`, not against this file. The script lives in `scripts/`, which has no
// `node_modules` of its own, so a bare specifier here looks in the wrong tree and fails with a
// message about Playwright being missing while it sits installed one directory over.
const { chromium, firefox, webkit } = await (async () => {
try {
const require = createRequire(new URL("../web/package.json", import.meta.url));
const loaded = await import(pathToFileURL(require.resolve("playwright")).href);
// Playwright's entry is CommonJS, and importing one by path puts its exports on `default`
// rather than lifting them — so the named bindings come back undefined and every engine fails
// to launch for a reason that reads like a browser problem.
return loaded.chromium ? loaded : loaded.default;
} catch (error) {
console.error(`playwright is not available: ${error}`);
console.error("run `npm install` in web/, then `npx playwright install`");
process.exit(2);
}
})();
let shared = built ? await serveBuilt(join(web, "dist")) : null;
let current = shared;
process.on("exit", () => shutdown(current));
console.log(`checking the ${built ? "built site" : "dev server"}\n`);
let failed = false;
let port = 4399;
for (const [name, engine] of [
["chromium", chromium],
["firefox", firefox],
["webkit", webkit],
]) {
// A fresh server per engine in dev mode, each on its own port so a lingering listener from the
// previous one cannot be mistaken for this one.
if (!built) {
shutdown(current);
current = await serveDev((port += 1));
if (!(await waitForServer(current.port))) {
console.log(`✗ ${name.padEnd(9)} the dev server never answered`);
failed = true;
continue;
}
}
let problems;
try {
problems = await checkEngine(engine, name, current.port);
} catch (error) {
const missing = /missing dependencies|Executable doesn't exist/i.test(String(error));
if (missing && !required.includes(name)) {
console.log(` ${name.padEnd(9)} skipped — not installed on this host`);
continue;
}
console.log(`✗ ${name.padEnd(9)} could not launch: ${String(error).split("\n")[0]}`);
failed = true;
continue;
}
if (problems.length === 0) {
console.log(`✓ ${name.padEnd(9)} every demo started, no errors`);
} else {
failed = true;
console.log(`✗ ${name}`);
for (const problem of problems.slice(0, 8)) console.log(` ${problem}`);
}
}
shutdown(current);
if (failed) {
console.error("\na browser disagreed with the others — see above.");
process.exit(1);
}
console.log("\nevery engine agrees.");