Document reusable review capabilities and publish compressed comic

apps/docs/scripts/auth-cli.ts

@@ -141,6 +141,7 @@ async function main() {
     "/",
     "/docs/00-endor-concepts-draft",
     "/figures/endor-architecture.svg",
+    "/figures/endor-review-gate.webp",
     "/docs/pretext/01-chapter",
     "/materials/pretext/verify.cjs",
     "/materials/pretext/results.chrome156.json",
@@ -184,13 +185,30 @@ async function main() {
   const searchIndex = await searchResponse.json();
   assert.ok(searchIndex.some((doc: { slug: string; searchText: string }) => doc.slug === "pretext/04-chapter" && doc.searchText.includes("getSegmentMetrics")));
   let home = "";
+  let purpose = "";
   for (const route of routes) {
     const response = await request(route, { headers });
     assert.equal(response.status, 200, route);
     if (route === "/") home = await response.text();
+    if (route === "/docs/04-endor-purpose-draft") purpose = await response.text();
   }
   assert.ok(home.includes("资料库"));
   assert.ok(home.includes("/docs/pretext/00-overview"));
+  // Inline preview and zoom dialog must both use the compressed browser asset.
+  assert.equal(
+    [...purpose.matchAll(/<img\b[^>]*\bsrc="\/figures\/endor-review-gate\.webp"/g)].length,
+    2,
+    "The comic preview and lightbox must use WebP",
+  );
+  assert.ok(!purpose.includes("endor-review-gate.png"));
+  const comic = await request("/figures/endor-review-gate.webp", { headers });
+  assert.equal(comic.status, 200);
+  assert.match(comic.headers.get("content-type") || "", /image\/webp/);
+  assert.deepEqual(
+    Buffer.from(await comic.arrayBuffer()),
+    readFileSync(join(__dirname, "public/figures/endor-review-gate.webp")),
+  );
+  assert.equal((await request("/figures/endor-review-gate.png", { headers })).status, 404);
   const assets = new Set(
     [...home.matchAll(/(?:src|href)="(\/_next\/static\/[^" ]+)"/g)].map((m) =>
       m[1].replaceAll("&amp;", "&"),

apps/docs/scripts/build-doc-images.mjs

@@ -0,0 +1,62 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import sharp from "sharp";
+
+const root = fileURLToPath(new URL("../../../", import.meta.url));
+const sources = path.join(root, "tools/figures/assets");
+const output = path.join(root, "apps/docs/public/figures");
+const check = process.argv.includes("--check");
+const policy = JSON.parse(await readFile(path.join(root, "content/image-policy.json"), "utf8"));
+
+async function files(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  return (await Promise.all(entries.map((entry) => {
+    const name = path.join(directory, entry.name);
+    return entry.isDirectory() ? files(name) : [name];
+  }))).flat().sort();
+}
+
+// Originals stay outside public; both inline and lightbox images use the WebP.
+for (const name of await files(path.join(root, "apps/docs/public"))) {
+  if (/\.(?:png|jpe?g|tiff?|bmp)$/i.test(name)) {
+    throw new Error(`Original raster exposed in public: ${path.relative(root, name)}. Move it to tools/figures/assets and run images.`);
+  }
+}
+for (const name of await files(path.join(root, "content/docs"))) {
+  if (!name.endsWith(".md")) continue;
+  const content = await readFile(name, "utf8");
+  const images = [
+    ...content.matchAll(/!\[[^\]]*\]\(<?([^\s)>]+)/g),
+    ...content.matchAll(/<img\b[^>]*\bsrc=["']([^"']+)/gi),
+  ];
+  for (const [, source] of images) {
+    if (/\.(?:png|jpe?g|tiff?|bmp)(?:[?#]|$)/i.test(source)) {
+      throw new Error(`${path.relative(root, name)} embeds an original raster: ${source}. Use the compressed WebP.`);
+    }
+  }
+}
+
+await mkdir(output, { recursive: true });
+for (const source of await files(sources)) {
+  if (!/\.(?:png|jpe?g|tiff?|bmp)$/i.test(source)) continue;
+  const relative = path.relative(sources, source).replace(/\.[^.]+$/, ".webp");
+  const destination = path.join(output, relative);
+  const original = await readFile(source);
+  const encoded = await sharp(original)
+    .rotate()
+    .resize({ width: policy.maxWidth, withoutEnlargement: true })
+    .webp({ quality: policy.quality, effort: 6 })
+    .toBuffer();
+  if (encoded.length > policy.maxBytes) {
+    throw new Error(`${relative}: ${encoded.length} bytes exceeds the ${policy.maxBytes}-byte image budget.`);
+  }
+  if (check) {
+    const committed = await readFile(destination);
+    if (!encoded.equals(committed)) throw new Error(`${relative} is stale. Run pnpm --filter @endor/docs images and commit the output.`);
+  } else {
+    await mkdir(path.dirname(destination), { recursive: true });
+    await writeFile(destination, encoded);
+  }
+  console.log(`${check ? "Verified" : "Generated"} ${relative}: ${original.length} → ${encoded.length} bytes (${(100 * (1 - encoded.length / original.length)).toFixed(1)}% smaller)`);
+}