ranger-compiler 3.5.1 → 3.5.2

package/dist/lib/evg/web/tools/assets-client.mjs

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: MIT
+//
+// THE REQUEST WAS ALREADY MADE.
+//
+// A page built with `inline-assets.mjs` starts every asset it knows it will
+// need — its fonts, its catalogues, the document it opens on — in a few
+// synchronous lines in the head, before the body is parsed and long before
+// the application's module has arrived. This is the other half: a module that
+// picks up those responses by name instead of asking for them again.
+//
+// What it is worth, on the PowerPoint editor: fetching them in a queue after
+// the engine had loaded put the first frame at 4813 ms; starting them in the
+// head put it at 2786. Nothing about the old order was necessary — none of
+// those requests needs any code to be running.
+//
+// A page that has no head-started assets (a source directory opened directly,
+// an editor's preview) still works: it asks, as it always did.
+
+/** The window's asset table, or an empty one. */
+const table = () => (typeof window === "undefined" ? {} : window.__evgAssets || {});
+
+/**
+ * The response for an asset, started in the head if it was.
+ *
+ * A CLONE, never the stored response itself: a body can be read once, and a
+ * page that reads one twice — an editor opening the deck it boots on, and
+ * again to prove it can reopen what it saved — gets "body stream already
+ * read" for the second. The stored response is never consumed, so the clone
+ * always succeeds.
+ */
+export function responseFor(path) {
+  const name = String(path).replace(/^\.\//, "");
+  const started = table()[name];
+  if (started) {
+    return Promise.resolve(started).then((r) => (r instanceof Error ? r : r.clone()));
+  }
+  return fetch("./" + name);
+}
+
+/** An ArrayBuffer the Ranger runtime can read: it wants a DataView beside it. */
+export function asRangerBuffer(ab) {
+  ab._view = new DataView(ab);
+  return ab;
+}
+
+/** An asset as bytes, throwing what the fetch threw rather than a 200 with no body. */
+export async function bytesOf(path) {
+  const res = await responseFor(path);
+  if (res instanceof Error) throw res;
+  if (!res.ok) throw new Error(path + " → " + res.status);
+  return asRangerBuffer(await res.arrayBuffer());
+}
+
+/** An asset as text, for a catalogue or a stylesheet. */
+export async function textOf(path) {
+  const res = await responseFor(path);
+  if (res instanceof Error) throw res;
+  if (!res.ok) throw new Error(path + " → " + res.status);
+  return res.text();
+}
+
+/**
+ * The same faces again, this time to the BROWSER — and it is the half that is
+ * easy to leave out.
+ *
+ * An EVG page loads its fonts into the app's own font manager, which is what
+ * the LAYOUT measures with: how wide a title is, where a line breaks, where a
+ * caret goes. Nothing tells `document.fonts` about them, so when the painter
+ * rasterises a run through a 2D canvas the browser has never heard of the
+ * family and draws its own sans instead — same string, same pixel size,
+ * different face, different width, and a caret most of a letter past the end
+ * of the word.
+ *
+ * A page can declare the same files in CSS instead, and that works — but the
+ * browser then LOADS THEM AGAIN, because a CSS font request and a `fetch()`
+ * are not the same request. Registering the bytes the page already has is the
+ * same result without the second download.
+ *
+ * `faces` is `{ bytes, family, weight, style }`; a face the browser refuses
+ * to parse is one family drawn in a substitute, which is bad but is not a
+ * reason to leave the page blank.
+ */
+export async function registerFaces(faces) {
+  if (typeof FontFace !== "function" || typeof document === "undefined" || !document.fonts) return;
+  await Promise.all(faces.map(async (f) => {
+    if (!f || !f.family) return;
+    try {
+      const face = new FontFace(f.family, f.bytes, { weight: f.weight || "400", style: f.style || "normal" });
+      await face.load();
+      document.fonts.add(face);
+    } catch (e) {
+      console.warn("could not register " + f.family + " with the browser:", e);
+    }
+  }));
+}

package/dist/lib/evg/web/tools/boot-bench.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+//
+// WHEN THE VISITOR SEES SOMETHING, and when they can use it. Any EVG page.
+//
+//   node lib/evg/web/tools/boot-bench.mjs --url <path> --ready <expr> [...]
+//   npm run rt:boot                 RealTrainer, both engines
+//   npm run pptx:boot               the PowerPoint editor
+//   … -- --fast                     no throttling, for a local number
+//
+// Options:
+//   --url <path>       the page, as a path under the repository root
+//   --ready <expr>     a JavaScript expression that becomes true when the app
+//                      has PAINTED. Every page has one; it is what its own
+//                      checks already wait for.
+//   --variant <name>=<query>   run the same page more than once, with a query
+//                      each time — how the two engine arrangements are
+//                      compared. Repeatable; the default is one plain run.
+//   --viewport WxH     default 390x844
+//   --mbps N           default 4;  --fast turns the throttle off
+//   --runs N           default 3, and the median is what is printed
+//
+// The ladder in PLAN_WEB_LOADING.md S2 is stated in milliseconds, and a plan
+// stated in milliseconds that nobody measures is a plan stated in adjectives.
+// This drives the real page in Chromium over a throttled connection and takes
+// two times, both of them from the browser's own clock:
+//
+//   first paint   — anything at all on the screen. With the baked picture in
+//                   the document (web/snapshot.mjs) this is one round trip and
+//                   owes nothing to the bundle.
+//   first frame   — the app has PAINTED. `window.__lastStats` is written by a
+//                   draw, so it is the first moment the picture on screen is
+//                   the app's own rather than the build's.
+//
+// It runs the engine on the main thread and in a Worker, because which of
+// those the deployed page should default to is a question with a number.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer } from "node:http";
+import zlib from "node:zlib";
+import { requireDom, findChromium } from "../../../../gallery/ui/conformance/dom-adapter.mjs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, "..", "..", "..", "..");
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const at = argv.indexOf(name);
+  return at >= 0 ? argv[at + 1] : fallback;
+};
+const PAGE = flag("--url");
+const READY = flag("--ready", "window.__lastStats !== undefined");
+if (!PAGE) {
+  console.error("usage: boot-bench.mjs --url <path under the repo> [--ready <expr>] …");
+  process.exit(2);
+}
+if (!fs.existsSync(path.join(ROOT, PAGE.replace(/^\//, "").split("?")[0]))) {
+  console.error(`no page at ${PAGE} — build it first`);
+  process.exit(3);
+}
+const VARIANTS = [];
+for (let i = 0; i < argv.length; i += 1) {
+  if (argv[i] === "--variant") {
+    const [name, query] = (argv[i + 1] || "").split("=");
+    VARIANTS.push([name, query || ""]);
+  }
+}
+if (!VARIANTS.length) VARIANTS.push(["the page", ""]);
+const [VW, VH] = (flag("--viewport", "390x844").split("x").map(Number));
+const FAST = argv.includes("--fast");
+const RUNS = Number(flag("--runs")) || 3;
+// A mid connection rather than a bad one: enough that bytes are visible in the
+// number, not so little that everything is dominated by the same stall.
+const MBPS = Number(flag("--mbps")) || 4;
+const BYTES_PER_SEC = (MBPS * 1024 * 1024) / 8;
+const LATENCY_MS = 60;
+// And a phone's CPU. Parse and boot are most of what is being compared, and a
+// desktop hides them.
+const CPU_SLOWDOWN = 4;
+
+const TYPES = {
+  ".html": "text/html", ".js": "text/javascript", ".mjs": "text/javascript",
+  ".cjs": "text/javascript", ".css": "text/css", ".json": "application/json",
+};
+// THE THROTTLE IS HERE, not in the browser. Chromium's own network emulation
+// is attached to the page's target and a dedicated Worker's requests go around
+// it — which made the Worker variant look four times faster than it is, on the
+// same bytes. A server that hands out its bytes slowly cannot be gone around.
+//
+// Responses are gzipped, because that is what a real host serves and half of
+// the point of these measurements is how many bytes are on the wire.
+const CHUNK = 16 * 1024;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const server = createServer(async (req, res) => {
+  const rel = decodeURIComponent(new URL(req.url, "http://x").pathname);
+  const file = path.join(ROOT, rel.slice(1));
+  if (!file.startsWith(ROOT) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) {
+    res.writeHead(404).end("not found");
+    return;
+  }
+  const type = TYPES[path.extname(file)] || "application/octet-stream";
+  const raw = fs.readFileSync(file);
+  const body = /text|json|javascript/.test(type) ? zlib.gzipSync(raw, { level: 6 }) : raw;
+  const headers = { "content-type": type, "content-length": String(body.length) };
+  if (body !== raw) headers["content-encoding"] = "gzip";
+  if (!FAST) await sleep(LATENCY_MS);
+  res.writeHead(200, headers);
+  if (FAST) {
+    res.end(body);
+    return;
+  }
+  const perChunkMs = (CHUNK / BYTES_PER_SEC) * 1000;
+  for (let i = 0; i < body.length; i += CHUNK) {
+    res.write(body.subarray(i, i + CHUNK));
+    await sleep(perChunkMs);
+  }
+  res.end();
+});
+await new Promise((r) => server.listen(0, r));
+const port = server.address().port;
+
+const { chromium } = requireDom("playwright-core");
+const browser = await chromium.launch({ executablePath: findChromium() });
+
+/** One cold load, in a context of its own so nothing is cached from the last. */
+async function once(query) {
+  const ctx = await browser.newContext({ viewport: { width: VW, height: VH } });
+  const page = await ctx.newPage();
+  const cdp = await ctx.newCDPSession(page);
+  // The CPU throttle DOES reach the worker (it is a renderer-wide setting);
+  // the network one does not, which is why the server holds the bytes back.
+  if (!FAST) await cdp.send("Emulation.setCPUThrottlingRate", { rate: CPU_SLOWDOWN });
+  const bytes = { total: 0 };
+  page.on("response", async (r) => {
+    const len = Number(r.headers()["content-length"] || 0);
+    bytes.total += len;
+  });
+  const t0 = Date.now();
+  await page.goto(`http://127.0.0.1:${port}${PAGE.startsWith("/") ? "" : "/"}${PAGE}${query}`, { waitUntil: "commit" });
+  await page.waitForFunction(READY, null, { timeout: 180000 });
+  const wall = Date.now() - t0;
+  const paint = await page.evaluate(() => {
+    const at = (name) => {
+      const e = performance.getEntriesByType("paint").find((x) => x.name === name);
+      return e ? Math.round(e.startTime) : null;
+    };
+    return {
+      // `first-paint` is the baked picture: boxes of colour, which is a paint
+      // and not "contentful". `first-contentful-paint` waits for the canvas.
+      fp: at("first-paint"),
+      fcp: at("first-contentful-paint"),
+      frame: Math.round(performance.now()),
+      timeline: performance.getEntriesByType("resource").map((r) => ({
+        name: r.name.split("/").pop(),
+        end: Math.round(r.responseEnd),
+      })),
+    };
+  });
+  await ctx.close();
+  return { ...paint, wall, bytes: bytes.total };
+}
+
+const median = (xs) => xs.slice().sort((a, b) => a - b)[Math.floor(xs.length / 2)];
+
+console.log(
+  FAST ? "no throttling" : `${MBPS} Mbps (served slowly, gzipped), ${LATENCY_MS} ms per request, ${CPU_SLOWDOWN}x CPU`,
+  `— ${RUNS} runs each, ${VW}x${VH}`,
+);
+console.log("");
+console.log("  variant                first paint   contentful   app painted    bytes");
+for (const [name, query] of VARIANTS) {
+  const runs = [];
+  for (let i = 0; i < RUNS; i += 1) runs.push(await once(query));
+  const fp = median(runs.map((r) => r.fp ?? r.frame));
+  const fcp = median(runs.map((r) => r.fcp ?? r.frame));
+  const frame = median(runs.map((r) => r.frame));
+  const kb = Math.round(median(runs.map((r) => r.bytes)) / 1024);
+  console.log(
+    `  ${name.padEnd(22)} ${String(fp + " ms").padStart(9)}   ${String(fcp + " ms").padStart(10)}   ${String(frame + " ms").padStart(9)}    ${kb} KB`,
+  );
+  if (argv.includes("--timeline")) {
+    for (const r of runs[0].timeline) console.log(`      ${String(r.end + " ms").padStart(8)}  ${r.name}`);
+  }
+}
+
+await browser.close();
+server.close();

package/dist/lib/evg/web/tools/inline-assets.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+//
+// WRITE THE HEAD THAT STARTS EVERYTHING.
+//
+//   node lib/evg/web/tools/inline-assets.mjs \
+//     --html DIR/index.html \
+//     --start fonts/A.ttf,fonts/B.ttf,presets.txt,deck.pptx \
+//     --preload-stamped standalone.mjs,gl/evg-webgl.js \
+//     --preload host/app-host.mjs,evg/assets-client.mjs \
+//     --stamp <build id> [--cache no-store] [--asset-query v]
+//
+// Every gallery page fetched its assets the same way and in the same wrong
+// order: after its engine had loaded and its module had run, one await at a
+// time. The requests need no code, so they can go out while the code is still
+// coming — and then a visitor waits for the LONGEST of the downloads rather
+// than for their sum.
+//
+// This writes that head, from a list, so the pattern is one build line per
+// page rather than a paragraph of hand-written script in each. The module side
+// is `assets-client.mjs`, which picks the responses up by name.
+//
+// The list is the build's, taken from wherever the page's own font table
+// lives, so it cannot drift from what the module asks for — an asset in one
+// and not the other is either fetched twice or waited for and never started,
+// and neither shows up as an error.
+
+import fs from "node:fs";
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const at = argv.indexOf(name);
+  return at >= 0 ? argv[at + 1] : fallback;
+};
+const list = (name) => (flag(name, "") ? flag(name, "").split(",").filter(Boolean) : []);
+
+const html = flag("--html");
+const start = list("--start");
+// TWO LISTS, AND THE DIFFERENCE MATTERS. A preload whose URL is not the URL
+// the module actually imports is not a preload: it is a second download of the
+// same file. Builds stamp some of their module URLs with the build id and
+// leave others alone, so which list a module belongs in is the build's answer,
+// not a guess this tool can make.
+const preloadStamped = list("--preload-stamped");
+const preload = list("--preload");
+const stamp = flag("--stamp", "");
+const openParam = flag("--open-param");
+// A page that fetches its assets with a cache mode, or that carries its own
+// `?v=` on to them, must have the head start THOSE requests and not merely
+// similar ones — a different mode or a different query is a different request,
+// and starting the wrong one leaves the module waiting for a response nobody
+// began while paying for one nobody wanted.
+const cacheMode = flag("--cache");
+const assetQuery = flag("--asset-query");
+
+if (!html || !fs.existsSync(html)) {
+  console.error("usage: inline-assets.mjs --html <file> --start a,b [--preload-stamped c] [--preload d] [--stamp id] [--open-param open]");
+  process.exit(2);
+}
+
+const MARK = "<!-- evg:assets -->";
+let src = fs.readFileSync(html, "utf8");
+if (src.includes(MARK)) {
+  console.error(`${html} already carries an evg:assets head`);
+  process.exit(1);
+}
+
+const q = stamp ? `?v=${stamp}` : "";
+const lines = [];
+lines.push(`    ${MARK}`);
+lines.push("    <!-- Generated by lib/evg/web/tools/inline-assets.mjs.");
+lines.push("       * Every asset this page needs, started before the body is parsed:");
+lines.push("       * these requests need no code, so they must not wait for any. The");
+lines.push("       * module picks the responses up by name (assets-client.mjs). -->");
+lines.push("    <script>");
+lines.push("      (function () {");
+lines.push(`        var files = ${JSON.stringify(start)};`);
+if (openParam) {
+  lines.push("        // `?" + openParam + "=` names a file to open instead of the default, and is");
+  lines.push("        // restricted to a plain name so a query string cannot make the page");
+  lines.push("        // fetch somewhere else — the same rule the module applies.");
+  lines.push(`        var wanted = new URLSearchParams(location.search).get(${JSON.stringify(openParam)});`);
+  lines.push("        if (wanted && /^[\\w.-]+$/.test(wanted)) files.push(wanted);");
+}
+if (assetQuery) {
+  lines.push("        // The page's own stamp, carried on to every asset, because that is");
+  lines.push("        // the URL the module will ask for.");
+  lines.push(`        var stamp = new URLSearchParams(location.search).get(${JSON.stringify(assetQuery)});`);
+  lines.push(`        var q = stamp ? '?${assetQuery}=' + encodeURIComponent(stamp) : '';`);
+} else {
+  lines.push("        var q = '';");
+}
+lines.push(`        var opts = ${cacheMode ? JSON.stringify({ cache: cacheMode }) : "undefined"};`);
+lines.push("        window.__evgAssets = {};");
+lines.push("        files.forEach(function (f) {");
+lines.push("          window.__evgAssets[f] = fetch('./' + f + q, opts).catch(function (e) { return e; });");
+lines.push("        });");
+lines.push("      })();");
+lines.push("    </script>");
+for (const mod of preloadStamped) {
+  lines.push(`    <link rel="modulepreload" href="./${mod}${q}" />`);
+}
+for (const mod of preload) {
+  lines.push(`    <link rel="modulepreload" href="./${mod}" />`);
+}
+
+// After the charset, which must stay first, and before anything that could
+// start a download of its own.
+const anchor = /<meta charset="utf-8"\s*\/?>/i;
+if (!anchor.test(src)) {
+  console.error(`${html} has no <meta charset="utf-8"> to write after`);
+  process.exit(1);
+}
+src = src.replace(anchor, (m) => `${m}\n${lines.join("\n")}`);
+fs.writeFileSync(html, src);
+console.log(
+  `  head starts ${start.length} assets${openParam ? " (+?" + openParam + ")" : ""}, ` +
+  `preloads ${preloadStamped.length + preload.length}`,
+);

package/dist/lib/evg/web/tools/minify.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+//
+// MINIFY A COMPILED RANGER BUNDLE.
+//
+//   node lib/evg/web/tools/minify.mjs --file DIR/app.js --keep AppWeb
+//
+// The Ranger backend writes for a reader that does not exist: long
+// identifiers, one statement per line, every temporary named. None of it
+// survives to the browser usefully — the source these pages are compiled from
+// is a .rgr file in this repository, and a stack trace through a generated
+// bundle was never the way anyone debugged one. On the PowerPoint editor it
+// is 3.49 MB against 2.27, and 761 KB gzipped against 639.
+//
+// `--keep` names the one string the page needs out of the file: the global its
+// scope publishes. A minifier renames identifiers and cannot rename a
+// property, so the assignment survives — but a bundle that lost it would load
+// silently and fail at the first line that used it, so it is checked.
+//
+// esbuild comes with the conformance host's dependencies, which these builds
+// do not otherwise need. A tree without them still builds: it ships the
+// larger file and says so.
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, "..", "..", "..", "..");
+
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const at = argv.indexOf(name);
+  return at >= 0 ? argv[at + 1] : undefined;
+};
+const file = flag("--file");
+const keep = flag("--keep");
+if (!file || !fs.existsSync(file)) {
+  console.error("usage: minify.mjs --file <bundle.js> [--keep <global>]");
+  process.exit(2);
+}
+
+let esbuild;
+try {
+  esbuild = createRequire(path.join(ROOT, "gallery/ui/conformance/dom/package.json"))("esbuild");
+} catch {
+  console.log("  (no esbuild — shipping the unminified bundle; npm run ui:conformance:install)");
+  process.exit(0);
+}
+
+const src = fs.readFileSync(file, "utf8");
+const out = esbuild.transformSync(src, { minify: true }).code;
+if (keep && !out.includes(keep)) {
+  console.error(`minifying lost ${keep} from ${file}`);
+  process.exit(1);
+}
+fs.writeFileSync(file, out);
+const kb = (s) => Math.round(s.length / 1024);
+console.log(`  minified ${path.basename(file)} ${kb(src)} KB -> ${kb(out)} KB`);

package/dist/lib/evg/web/tracer/build.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * Build the live bitmap-tracer page.
+ *
+ *   node lib/evg/web/tracer/build.mjs
+ *   node lib/evg/web/tracer/build.mjs --out path/to/evg/tracer
+ *
+ * Compiles EvgBitmapTracer to a browser IIFE (no require) and copies the HTML
+ * + sample image beside it. The EVG showcase build calls the same steps for
+ * /evg/tracer/ on GitHub Pages.
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, "../../../..");
+const argv = process.argv.slice(2);
+const outFlag = argv.indexOf("--out");
+const OUT = outFlag >= 0 ? path.resolve(argv[outFlag + 1]) : path.join(HERE, "dist");
+const STAGE = path.join(HERE, ".stage");
+
+fs.mkdirSync(STAGE, { recursive: true });
+fs.mkdirSync(OUT, { recursive: true });
+
+const env = {
+  ...process.env,
+  RANGER_LIB: "./compiler/Lang.rgr:./lib/stdops.rgr",
+};
+
+const log = execFileSync(
+  process.execPath,
+  [
+    "dist/rgrc.js",
+    "-es6",
+    "lib/evg/EvgBitmapTracer.rgr",
+    `-d=${path.relative(ROOT, STAGE)}`,
+    "-o=evg_bitmap_tracer.js",
+    "-nodecli",
+  ],
+  { cwd: ROOT, env, encoding: "utf8" }
+);
+
+if (log.includes("Compilation FAILED")) {
+  process.stderr.write(log + "\n");
+  process.exit(1);
+}
+
+const rawPath = path.join(STAGE, "evg_bitmap_tracer.js");
+if (!fs.existsSync(rawPath)) {
+  process.stderr.write("compiler wrote no " + rawPath + "\n");
+  process.exit(1);
+}
+
+let bundle = fs.readFileSync(rawPath, "utf8").replace(/^#![^\n]*\n/, "");
+
+{
+  const previous = globalThis.require;
+  globalThis.require = undefined;
+  const found = (0, eval)(
+    bundle + "; typeof EvgBitmapTracer + '|' + typeof ImageBuffer + '|' + typeof EvgTraceOptions"
+  );
+  globalThis.require = previous;
+  if (found !== "function|function|function") {
+    throw new Error(
+      "evg_bitmap_tracer.js missing browser exports (got " + found + ")"
+    );
+  }
+}
+
+const scoped =
+  "// GENERATED from lib/evg/EvgBitmapTracer.rgr — do not edit.\n" +
+  "(function () {\n" +
+  bundle +
+  "\n;globalThis.EvgBitmapTracer = EvgBitmapTracer;" +
+  "\n;globalThis.EvgTraceOptions = EvgTraceOptions;" +
+  "\n;globalThis.EvgTraceLayer = EvgTraceLayer;" +
+  "\n;globalThis.ImageBuffer = ImageBuffer;" +
+  "\n})();\n";
+
+fs.writeFileSync(path.join(OUT, "evg_bitmap_tracer.js"), scoped);
+fs.copyFileSync(path.join(HERE, "index.html"), path.join(OUT, "index.html"));
+fs.copyFileSync(path.join(HERE, "sample.png"), path.join(OUT, "sample.png"));
+
+fs.rmSync(STAGE, { recursive: true, force: true });
+process.stdout.write("Wrote tracer page to " + path.relative(ROOT, OUT) + "\n");