@agent-native/core-corpus 0.213.1 → 0.216.0

package/corpus/templates/slides-2/scripts/export-fidelity/README.md

@@ -0,0 +1,116 @@
+# Export fidelity harness
+
+Verifies Slides → PowerPoint/Google Slides export fidelity by comparing
+Chrome's own text layout for a deck against what Google Slides renders after
+importing the exported PPTX. This exists because an earlier Google Slides
+export fix shipped without ever being checked against real Google Slides —
+the PPTX was valid but nobody diffed its rendered layout against the source.
+
+## Prerequisites
+
+- Local Slides dev server running with `AUTH_MODE=local` (the scripts sign in
+  via the "Continue as local dev" button).
+- Playwright, resolved out of the pnpm store by `resolve-pkg.ts` — no local
+  `package.json` entry needed, but `playwright@1.63.x` must exist under the
+  workspace root's `node_modules/.pnpm`.
+- ImageMagick (`magick` on `PATH`) for `diff.ts` only.
+
+## Commands
+
+Run everything from `templates/slides`, naming the script by its path from
+there — `pnpm exec` resolves relative to the package root, so a bare
+`<script>.ts` is looked up in `templates/slides` and not found:
+
+```bash
+pnpm exec tsx scripts/export-fidelity/export.ts \
+  scripts/export-fidelity/fixtures/agent-dark-deck.json --out <dir> --layout-only
+```
+
+- **`export.ts <fixture.json> --out <dir>`** or **`export.ts --deck <id> --out <dir>`**
+  (add `--layout-only` to skip the PPTX export and reference PNGs) — drives
+  the dev server, creates or reuses a deck, dumps per-line Chrome text layout
+  to `<dir>/layout/slide-NN.json`, exports a PPTX to `<dir>/deck.pptx`, and
+  renders `<dir>/ref/slide-NN.png` reference PNGs.
+- **`google-export.ts --deck <id> --out <dir> [--target google-slides|powerpoint]`**
+  (or `--fixture <fixture.json>` instead of `--deck` to create the deck
+  first) — exports one deck as a PPTX for the given target, writing
+  `<dir>/deck.pptx`. Target defaults to `google-slides`.
+- **`compare-layout.ts <chrome-layout-dir> <google.txt> [--slides <n>]`** —
+  matches Chrome's `layout/slide-NN.json` lines against `google.txt` rows and
+  prints per-slide pass/fail plus `|dy|`/`|dx|` percentile stats. This is the
+  harness's pass/fail gate: it exits nonzero when a line is unmatched, a line
+  break differs, a line sits more than 1.5px out, or a Google row is never
+  claimed. Pass `--slides <n>` — the deck's own slide count — so a dump that
+  stopped early cannot pass by comparing fewer slides on both sides.
+- **`diff.ts <refDir> <candDir> --out <dir>`** — pixel-diffs two directories
+  of `slide-NN.png` renders (full-resolution + blurred/downscaled layout
+  ratio) and writes `<dir>/report.json` and `<dir>/*-compare.png` montages.
+  It is an inspection aid rather than a gate, and fails only when a slide has
+  no usable pair: a pixel threshold tight enough to catch a real regression
+  also fires on ordinary font-rendering differences between machines. Read its
+  ratios and montages; let `compare-layout.ts` decide pass or fail.
+- **`generate-calibration.ts`** (run from `templates/slides`) — rebuilds
+  `calibration.pptx`/`cases.json` from a real exported deck's package parts.
+  Pass `--template <deck.pptx>` — any exported deck, such as the `deck.pptx`
+  written by `export.ts --out <dir>`; its presentation, layout, master and
+  theme parts are reused and only the slides are replaced.
+- **`google-layout.ts`** exports
+  `extractGoogleSlideLayout(slideNumber, { aspect, width })`, not a standalone
+  script — see the extraction procedure below. `aspect` and `width` default to
+  16:9 in a 960-wide coordinate space; pass the deck's own ratio and width for
+  a 1:1, 9:16, 4:5 or 4:3 deck, or it will not find the slide frame.
+
+## Google Slides import procedure (for a browser agent)
+
+1. On `docs.google.com`, inject a visible proxy `<input type="file">`.
+2. Use the browser tool's file-upload action on that proxy input.
+3. Open the Slides file picker — the first click often doesn't open it, click
+   again.
+4. Select the Upload tab by dispatching mouse events inside the same-origin
+   `/picker/` iframe.
+5. Copy the file into the picker iframe's own file input using that iframe's
+   own `DataTransfer`/`File` constructors, then dispatch `change`.
+
+## Extraction procedure
+
+For each slide N:
+
+1. Fully load `.../edit#slide=id.p<N>` (a real navigation, not a hash change
+   — hash-only navigation freezes a hidden tab and the SVG never updates).
+2. Emit browser JS from the extractor once, since `google-layout.ts` is
+   TypeScript and a console will not parse it:
+
+   ```bash
+   pnpm exec tsc scripts/export-fidelity/google-layout.ts --ignoreConfig \
+     --target es2022 --lib es2022,dom --outDir /tmp/gl
+   sed 's/^export //' /tmp/gl/google-layout.js
+   ```
+
+   Paste that output into the page — or hand the same stripped source to a
+   browser automation tool's page-eval — and then call
+   `extractGoogleSlideLayout(N)`. For a deck that is not 16:9, pass its ratio
+   and coordinate width, e.g.
+   `extractGoogleSlideLayout(N, { aspect: 4 / 5, width: 720 })`, or the frame
+   search finds nothing and it throws.
+
+3. Browser tools may cap output around 1KB per call — page the returned rows
+   and append each page to `google.txt`.
+4. Once every slide is appended, run
+   `compare-layout.ts <chrome-layout-dir> google.txt --slides <n>` with the
+   deck's own slide count, so a capture that stopped early on both sides
+   cannot pass by comparing matching prefixes.
+
+## Measured Google Slides import rules
+
+- Line pitch = `spcPct × 1.2 × size`.
+- `spcPts` is unreliable — use `spcPct`.
+- First baseline sits `0.96 × size × min(1, pct)` below the top of the text area.
+- Centered and bottom-anchored blocks are `1.2 × size × min(1, pct) + (n−1) × pitch` tall.
+- No letter-spacing.
+- `roundRect` text inset = `min(w,h) × adj/100000 × 0.29289`.
+- Google re-wraps text itself, so pin line breaks rather than relying on the source's.
+
+## Expected result
+
+On `fixtures/agent-dark-deck.json` with `--target google-slides`: all 8
+slides within 1.5px, 0 line-break mismatches.

package/corpus/templates/slides-2/scripts/export-fidelity/compare-layout-lib.ts

@@ -0,0 +1,241 @@
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+const norm = (text: string) => text.replace(/\s+/g, " ").trim().toLowerCase();
+const TOLERANCE_PX = 1.5;
+
+type GoogleRow = {
+  slide: number;
+  x: number;
+  base: number;
+  right: number;
+  text: string;
+  used: boolean;
+};
+
+type ChromeLine = {
+  text: string;
+  x: number;
+  right: number;
+  baseline: number;
+};
+
+type ChromeText = {
+  align?: string;
+  font: {
+    family: string;
+    sizePx: number;
+    lineHeightPx: number;
+    letterSpacingPx: number;
+  };
+  lines: ChromeLine[];
+};
+
+export interface LayoutComparisonResult {
+  lines: number;
+  unmatched: number;
+  breakMismatches: number;
+  outOfTolerance: number;
+  unclaimed: number;
+  dy: number[];
+  dx: number[];
+  output: string[];
+  success: boolean;
+}
+
+function parseGoogleRows(googleFile: string): GoogleRow[] {
+  return readFileSync(googleFile, "utf8")
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      const fields = line.split("|");
+      if (fields.length < 5) {
+        throw new Error(`Malformed row in ${googleFile}: ${line}`);
+      }
+      const [slideText, xText, baseText, rightText, ...text] = fields;
+      if (
+        [slideText, xText, baseText, rightText].some((value) => !value.trim())
+      ) {
+        throw new Error(`Malformed row in ${googleFile}: ${line}`);
+      }
+      const row = {
+        slide: Number(slideText),
+        x: Number(xText),
+        base: Number(baseText),
+        right: Number(rightText),
+        text: norm(text.join("|")),
+        used: false,
+      };
+      if (![row.slide, row.x, row.base, row.right].every(Number.isFinite)) {
+        throw new Error(`Malformed row in ${googleFile}: ${line}`);
+      }
+      return row;
+    });
+}
+
+function slideNumberOf(name: string): number {
+  const match = name.match(/\d+/);
+  if (!match) throw new Error(`Invalid slide layout filename: ${name}`);
+  return Number(match[0]);
+}
+
+function layoutFilesIn(anDir: string): string[] {
+  const files = readdirSync(anDir)
+    .filter((name) => /^slide-\d+\.json$/.test(name))
+    .sort((a, b) => slideNumberOf(a) - slideNumberOf(b));
+  if (!files.length)
+    throw new Error(`No slide-NN.json layout files in ${anDir}`);
+  const numbers = files.map(slideNumberOf);
+  if (numbers.some((value, index) => value !== index + 1)) {
+    throw new Error(
+      `Layout dump is not a contiguous slide-01..N set in ${anDir}: got ${numbers.join(", ")}`,
+    );
+  }
+  return files;
+}
+
+const percentile = (values: number[], p: number) => {
+  const sorted = values.map(Math.abs).sort((a, b) => a - b);
+  return sorted.length
+    ? sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * p))]
+    : Number.NaN;
+};
+
+export function compareLayoutFiles(
+  anDir: string,
+  googleFile: string,
+  expectedSlides?: number,
+): LayoutComparisonResult {
+  const google = parseGoogleRows(googleFile);
+  const layoutFiles = layoutFilesIn(anDir);
+  if (expectedSlides !== undefined && layoutFiles.length !== expectedSlides) {
+    throw new Error(
+      `Layout dump has ${layoutFiles.length} slide(s), expected ${expectedSlides}`,
+    );
+  }
+
+  let lines = 0;
+  let breakMismatches = 0;
+  let unmatched = 0;
+  const dys: number[] = [];
+  const dxs: number[] = [];
+  const output: string[] = [];
+
+  for (const file of layoutFiles) {
+    const { slide, texts } = JSON.parse(
+      readFileSync(path.join(anDir, file), "utf8"),
+    ) as { slide: number; texts: ChromeText[] };
+    const pool = google.filter((entry) => entry.slide === slide);
+    const slideLines = texts.reduce((sum, text) => sum + text.lines.length, 0);
+    if (!pool.length) {
+      lines += slideLines;
+      unmatched += slideLines;
+      output.push(
+        `slide ${slide}: NO GOOGLE ROWS - ${slideLines} line(s) counted unmatched`,
+      );
+      continue;
+    }
+
+    const rows: string[] = [];
+    for (const text of texts) {
+      for (const line of text.lines) {
+        lines++;
+        const wanted = norm(line.text);
+        const nearest = (candidates: GoogleRow[]) =>
+          candidates.sort(
+            (a, b) =>
+              Math.hypot(a.x - line.x, a.base - line.baseline) -
+              Math.hypot(b.x - line.x, b.base - line.baseline),
+          )[0];
+        const exact = nearest(
+          pool.filter((entry) => !entry.used && entry.text === wanted),
+        );
+        const match =
+          exact ??
+          nearest(
+            pool.filter(
+              (entry) =>
+                !entry.used &&
+                (entry.text.startsWith(wanted.slice(0, 10)) ||
+                  wanted.startsWith(entry.text.slice(0, 10))),
+            ),
+          );
+        if (!match) {
+          unmatched++;
+          rows.push(`  MISSING "${line.text.slice(0, 40)}"`);
+          continue;
+        }
+
+        match.used = true;
+        if (!exact) {
+          breakMismatches++;
+          rows.push(
+            `  BREAK   chrome "${line.text.slice(0, 40)}" vs google "${match.text.slice(0, 40)}"`,
+          );
+        }
+        const dy = match.base - line.baseline;
+        const anchor =
+          text.align === "center"
+            ? "centre"
+            : text.align === "right" || text.align === "end"
+              ? "right"
+              : "left";
+        const dx =
+          anchor === "centre"
+            ? (match.x + match.right) / 2 - (line.x + line.right) / 2
+            : anchor === "right"
+              ? match.right - line.right
+              : match.x - line.x;
+        dys.push(dy);
+        dxs.push(dx);
+        if (Math.abs(dy) > TOLERANCE_PX || Math.abs(dx) > TOLERANCE_PX) {
+          rows.push(
+            `  OFF dy ${dy.toFixed(1)} d${anchor} ${dx.toFixed(1)} "${line.text.slice(0, 30)}" (${text.font.family} ${text.font.sizePx}px lh ${text.font.lineHeightPx} ls ${text.font.letterSpacingPx} ${text.align})`,
+          );
+        }
+      }
+    }
+    output.push(
+      `slide ${slide}: ${rows.length ? `\n${rows.join("\n")}` : `all lines within ${TOLERANCE_PX}px, same breaks`}`,
+    );
+  }
+
+  const outOfTolerance = dys.filter(
+    (value, index) =>
+      Math.abs(value) > TOLERANCE_PX ||
+      Math.abs(dxs[index] ?? 0) > TOLERANCE_PX,
+  ).length;
+  const unclaimedRows = google.filter((entry) => !entry.used);
+  if (unclaimedRows.length) {
+    const slides = [...new Set(unclaimedRows.map((entry) => entry.slide))].sort(
+      (a, b) => a - b,
+    );
+    output.push(
+      `UNCLAIMED ${unclaimedRows.length} google row(s) on slide(s) ${slides.join(", ")}`,
+    );
+  }
+  output.push(
+    `lines ${lines}, unmatched ${unmatched}, break mismatches ${breakMismatches}; |dy| median ${percentile(dys, 0.5).toFixed(2)} p95 ${percentile(dys, 0.95).toFixed(2)} max ${percentile(dys, 1).toFixed(2)}; |dx| median ${percentile(dxs, 0.5).toFixed(2)} p95 ${percentile(dxs, 0.95).toFixed(2)} max ${percentile(dxs, 1).toFixed(2)}`,
+  );
+  if (unmatched || breakMismatches || outOfTolerance || unclaimedRows.length) {
+    output.push(
+      `FAIL: ${unmatched} unmatched, ${breakMismatches} break mismatch(es), ${outOfTolerance} line(s) over ${TOLERANCE_PX}px, ${unclaimedRows.length} unclaimed google row(s)`,
+    );
+  }
+
+  return {
+    lines,
+    unmatched,
+    breakMismatches,
+    outOfTolerance,
+    unclaimed: unclaimedRows.length,
+    dy: dys,
+    dx: dxs,
+    output,
+    success:
+      unmatched === 0 &&
+      breakMismatches === 0 &&
+      outOfTolerance === 0 &&
+      unclaimedRows.length === 0,
+  };
+}

package/corpus/templates/slides-2/scripts/export-fidelity/compare-layout.ts

@@ -0,0 +1,30 @@
+import { compareLayoutFiles } from "./compare-layout-lib.js";
+
+const [anDir, googleFile] = process.argv.slice(2);
+if (!anDir || !googleFile) {
+  console.error(
+    "Usage: pnpm exec tsx compare-layout.ts <anLayoutDir> <google.txt> [--slides <n>]",
+  );
+  process.exit(1);
+}
+
+const slidesFlag = process.argv.indexOf("--slides");
+const slidesValue =
+  slidesFlag === -1 ? undefined : Number(process.argv[slidesFlag + 1]);
+if (slidesFlag === -1) {
+  console.warn(
+    "No --slides <n> given, so the layout dump is taken as the whole deck.",
+  );
+} else if (!(slidesValue && slidesValue > 0)) {
+  console.error("--slides must be a positive integer");
+  process.exit(1);
+}
+
+try {
+  const result = compareLayoutFiles(anDir, googleFile, slidesValue);
+  for (const line of result.output) console.log(line);
+  if (!result.success) process.exitCode = 1;
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/corpus/templates/slides-2/scripts/export-fidelity/diff.ts

@@ -0,0 +1,222 @@
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+
+import { resolvePnpmEntry } from "./resolve-pkg.ts";
+
+const pixelmatchMod: any = await import(resolvePnpmEntry("pixelmatch", "7.2"));
+const pixelmatch: any = pixelmatchMod.default;
+const pngjsMod: any = await import(resolvePnpmEntry("pngjs", "7."));
+const PNG: any = pngjsMod.PNG ?? pngjsMod.default?.PNG;
+
+const LAYOUT_WIDTH = 400;
+const LAYOUT_HEIGHT = 225;
+
+function parseArgs(argv: string[]) {
+  const outIndex = argv.indexOf("--out");
+  if (outIndex === -1 || !argv[outIndex + 1] || !argv[0] || !argv[1]) {
+    throw new Error("Usage: diff.ts <refDir> <candDir> --out <dir>");
+  }
+  return {
+    refDir: path.resolve(argv[0]),
+    candDir: path.resolve(argv[1]),
+    outDir: path.resolve(argv[outIndex + 1]),
+  };
+}
+
+function loadPng(file: string) {
+  return PNG.sync.read(readFileSync(file));
+}
+
+function magick(args: string[]) {
+  execFileSync("magick", args, { stdio: ["ignore", "ignore", "inherit"] });
+}
+
+function ensureSize(
+  inputPath: string,
+  width: number,
+  height: number,
+  outPath: string,
+): string {
+  const img = loadPng(inputPath);
+  if (img.width === width && img.height === height) return inputPath;
+  magick([inputPath, "-resize", `${width}x${height}!`, outPath]);
+  return outPath;
+}
+
+interface Row {
+  slide: string;
+  width?: number;
+  height?: number;
+  mismatchedPixels?: number;
+  pixelRatio?: number;
+  layoutMismatchedPixels?: number;
+  layoutRatio?: number;
+  error?: string;
+}
+
+async function main() {
+  const { refDir, candDir, outDir } = parseArgs(process.argv.slice(2));
+  mkdirSync(outDir, { recursive: true });
+  const workDir = path.join(outDir, "_work");
+  mkdirSync(workDir, { recursive: true });
+
+  const refFiles = readdirSync(refDir)
+    .filter((f) => /^slide-\d+\.png$/.test(f))
+    .sort();
+  if (refFiles.length === 0) {
+    throw new Error(`No slide-NN.png files found in ${refDir}`);
+  }
+
+  const rows: Row[] = [];
+  for (const fname of readdirSync(candDir)
+    .filter((f) => /^slide-\d+\.png$/.test(f))
+    .sort()) {
+    if (!refFiles.includes(fname)) {
+      rows.push({
+        slide: fname.replace(/\.png$/, ""),
+        error: "unexpected candidate",
+      });
+    }
+  }
+  for (const fname of refFiles) {
+    const slide = fname.replace(/\.png$/, "");
+    const refPath = path.join(refDir, fname);
+    const candSrcPath = path.join(candDir, fname);
+    if (!existsSync(candSrcPath)) {
+      rows.push({ slide, error: "missing candidate" });
+      continue;
+    }
+
+    const refImg = loadPng(refPath);
+    const { width, height } = refImg;
+    const candResizedPath = ensureSize(
+      candSrcPath,
+      width,
+      height,
+      path.join(workDir, `${slide}-cand-resized.png`),
+    );
+    const candImg = loadPng(candResizedPath);
+
+    const diffImg = new PNG({ width, height });
+    const mismatchedPixels = pixelmatch(
+      refImg.data,
+      candImg.data,
+      diffImg.data,
+      width,
+      height,
+      {
+        threshold: 0.1,
+        includeAA: false,
+      },
+    );
+    const pixelRatio = mismatchedPixels / (width * height);
+    const diffPath = path.join(workDir, `${slide}-diff.png`);
+    writeFileSync(diffPath, PNG.sync.write(diffImg));
+
+    const refLayoutPath = path.join(workDir, `${slide}-ref-layout.png`);
+    const candLayoutPath = path.join(workDir, `${slide}-cand-layout.png`);
+    magick([
+      refPath,
+      "-resize",
+      `${LAYOUT_WIDTH}x${LAYOUT_HEIGHT}!`,
+      "-blur",
+      "0x2",
+      refLayoutPath,
+    ]);
+    magick([
+      candResizedPath,
+      "-resize",
+      `${LAYOUT_WIDTH}x${LAYOUT_HEIGHT}!`,
+      "-blur",
+      "0x2",
+      candLayoutPath,
+    ]);
+    const refLayoutImg = loadPng(refLayoutPath);
+    const candLayoutImg = loadPng(candLayoutPath);
+    const layoutMismatchedPixels = pixelmatch(
+      refLayoutImg.data,
+      candLayoutImg.data,
+      null,
+      LAYOUT_WIDTH,
+      LAYOUT_HEIGHT,
+      { threshold: 0.15, includeAA: false },
+    );
+    const layoutRatio = layoutMismatchedPixels / (LAYOUT_WIDTH * LAYOUT_HEIGHT);
+
+    const comparePath = path.join(outDir, `${slide}-compare.png`);
+    magick([
+      refPath,
+      candResizedPath,
+      diffPath,
+      "-bordercolor",
+      // guard:allow-raw-color — separator between tiles in a generated PNG, not themed UI
+      "#808080",
+      "-border",
+      "4x0",
+      "+append",
+      comparePath,
+    ]);
+
+    rows.push({
+      slide,
+      width,
+      height,
+      mismatchedPixels,
+      pixelRatio: Number(pixelRatio.toFixed(6)),
+      layoutMismatchedPixels,
+      layoutRatio: Number(layoutRatio.toFixed(6)),
+    });
+  }
+
+  const numericRows = rows.filter((r) => r.pixelRatio !== undefined);
+  const summary = {
+    slideCount: rows.length,
+    maxPixelRatio: numericRows.length
+      ? Math.max(...numericRows.map((r) => r.pixelRatio!))
+      : null,
+    maxLayoutRatio: numericRows.length
+      ? Math.max(...numericRows.map((r) => r.layoutRatio!))
+      : null,
+    missing: rows.filter((r) => r.error).map((r) => r.slide),
+  };
+
+  writeFileSync(
+    path.join(outDir, "report.json"),
+    JSON.stringify(
+      { refDir, candDir, generatedAt: new Date().toISOString(), summary, rows },
+      null,
+      2,
+    ),
+  );
+
+  console.table(
+    rows.map((r) => ({
+      slide: r.slide,
+      pixelRatio: r.pixelRatio ?? "-",
+      layoutRatio: r.layoutRatio ?? "-",
+      mismatched: r.mismatchedPixels ?? "-",
+      error: r.error ?? "",
+    })),
+  );
+  console.log(
+    `[diff] max pixelRatio=${summary.maxPixelRatio} max layoutRatio=${summary.maxLayoutRatio}`,
+  );
+  if (summary.missing.length) {
+    console.error(
+      `[diff] FAILED: ${summary.missing.length} slide(s) with no usable pair: ${summary.missing.join(", ")}`,
+    );
+    process.exitCode = 1;
+  }
+}
+
+main().catch((err) => {
+  console.error("[diff] FAILED:", err);
+  process.exit(1);
+});