six-degrees 0.2.0 → 0.3.0-beta.1

package/.next/standalone/scripts/build-app.mjs

@@ -12,12 +12,14 @@
 //
 // What this removes: installing Node, cloning, npm install, and typing a
 // command. The Node runtime is bundled, so the app has no prerequisites at all
-// for the CSV path — download, double-click, drop in your export.
+// for the CSV path — download, double-click, drop in your export. The Electron
+// app also carries the scanner's own Python with its packages installed
+// (bundlePython, DESKTOP.md D2), so scanning needs no install step either.
 //
-// What it does NOT remove: Python and Google Chrome, which the scraper needs.
-// Those stay runtime prerequisites and the Scan page already detects both.
-// Bundling a Chromium instead would make the scraper MORE detectable, not less,
-// which defeats the point of driving the user's real browser.
+// What it does NOT remove: Google Chrome, which the scanner drives. It stays a
+// runtime prerequisite and the Scan page already detects it. Bundling a
+// Chromium instead would make the scanner MORE detectable, not less, which
+// defeats the point of driving the user's real browser.
 //
 // Unsigned, because notarisation needs a paid Apple Developer account. macOS
 // will refuse the first launch; the user allows it once in System Settings.
@@ -25,13 +27,24 @@
 // separate "app is damaged" failure that unsigned arm64 binaries otherwise hit.
 
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, rmSync, cpSync, writeFileSync, existsSync, chmodSync, readFileSync, symlinkSync, lstatSync, renameSync, readlinkSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import {
+  mkdirSync, rmSync, cpSync, writeFileSync, existsSync, chmodSync, readFileSync, symlinkSync, lstatSync, renameSync,
+  readlinkSync, readdirSync, openSync, readSync, closeSync, realpathSync,
+} from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
+import {
+  standaloneBuild, downloadVerified, machoSlices, machoSlice, megabytes, IMPORTS,
+} from '../lib/scanner-python.js';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const pkg = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+// The oldest macOS the app runs on: the bundled Node 24 needs 13.5 (Electron
+// itself needs 13). Written into Info.plist, and every program in the bundled
+// Python is checked against it (checkPython).
+const MACOS_MIN = '13.5';
 
 const NODE_VERSION = process.env.BUNDLE_NODE || 'v24.21.0';
 const ARCH = process.env.BUNDLE_ARCH || (os.arch() === 'x64' ? 'x64' : 'arm64');
@@ -134,9 +147,13 @@ try {
     for (const rel of untracked) console.log(`      ${rel}`);
   }
 } catch { /* not a git checkout: nothing to compare against */ }
-// The scraper is not part of the standalone output but the Scan page runs it.
+// The files the app runs from scripts/, copied by name so the app never
+// depends on what Next's tracing happens to bring along (TRAPS §27): the
+// scanner the Scan page runs, and apply-update.sh, the in-app updater's helper.
+// The helper ships inside the app, so the version that swaps the app is the one
+// the user is running, never a script fetched from the main branch.
 for (const rel of ['scripts/scrape.py', 'scripts/image_store.py', 'scripts/requirements.txt',
-                   'scripts/score_new_connections.sql', 'scripts/audit-avatars.mjs']) {
+                   'scripts/audit-avatars.mjs', 'scripts/apply-update.sh']) {
   const from = path.join(ROOT, rel);
   if (existsSync(from)) {
     mkdirSync(path.join(SERVER_DIR, path.dirname(rel)), { recursive: true });
@@ -171,6 +188,8 @@ export SIX_DEGREES_BIND=127.0.0.1
 export NEXT_TELEMETRY_DISABLED=1
 export SIX_DEGREES_ROOT="$HERE/app"
 export SIX_DEGREES_INSTALL=mac-app
+# This app's own bundle, for the in-app updater (lib/updater.js runningBundle).
+export SIX_DEGREES_APP="$(cd "$HERE/../.." && pwd)"
 export HOSTNAME=127.0.0.1
 
 # Walk up from 6363 so a second copy does not fight the first.
@@ -308,7 +327,7 @@ async function buildElectronShell() {
     darwinDarkModeSupport: true,
     // The bundled Node 24 needs macOS 13.5 (Electron itself needs 13), so say
     // so, and macOS explains it instead of the app failing to start.
-    extendInfo: { LSMinimumSystemVersion: '13.5' },
+    extendInfo: { LSMinimumSystemVersion: MACOS_MIN },
     osxSign: false,        // signed ad hoc below, after everything is in place
   });
   console.log(`  Electron ${electronVersion} (${ARCH})`);
@@ -316,14 +335,237 @@ async function buildElectronShell() {
   renameSync(path.join(built, `${APP_NAME}.app`), APP);
   rmSync(STAGE, { recursive: true, force: true });
 
+  // Put straight into the finished app, so its links are made where they stay
+  // and nothing copies them again (TRAPS §37).
+  await bundlePython(path.join(APP, 'Contents', 'Resources'));
+
   step('Signing (ad-hoc)');
   // Electron's framework and helpers must all carry the same kind of signature,
   // or macOS refuses to load them; re-signing the whole bundle ad hoc does that.
+  // --deep reaches nested bundles, not loose programs and libraries in
+  // Resources: the Python's were signed one by one first (signPython), and this
+  // seals them into the app's signature with everything else.
   run('codesign', ['--force', '--deep', '--sign', '-', APP]);
   run('codesign', ['--verify', '--deep', '--strict', APP]);
   console.log('  signed ad-hoc and verified — no Apple account needed, still unnotarised');
 }
 
+// ---- the scanner's Python (Electron app only; DESKTOP.md D2) ------------------
+// A standalone CPython from python-build-standalone, with the scanner's packages
+// installed, at Contents/Resources/python. desktop/main.mjs names it to the
+// server (SIX_DEGREES_PYTHON), which runs the scanner on it before any other
+// Python: no install step, and scanning works offline.
+//
+// Pinned twice: the Python by the release and SHA-256 in lib/scanner-python.js,
+// the packages by the hash of every file in scripts/requirements.txt. Downloads
+// are cached in ~/.cache/six-degrees-build like Node's, and checked every build.
+// Built on a Mac with the same chip (release.yml has one job per chip): pip runs
+// this Python to install into it.
+async function bundlePython(resources) {
+  const build = standaloneBuild(`darwin-${ARCH}`);
+  const xy = build.version.split('.').slice(0, 2).join('.');
+  const py = path.join(resources, 'python');
+  const lib = path.join(py, 'lib', `python${xy}`);
+
+  step(`Fetching Python ${build.version} (${ARCH})`);
+  const archive = path.join(CACHE, build.file);
+  if (existsSync(archive) && sha256File(archive) === build.sha256) {
+    console.log('  using the cached download (its SHA-256 matches the pinned one)');
+  } else {
+    rmSync(archive, { force: true });
+    await downloadVerified(build.url, archive, { sha256: build.sha256, size: build.size, idleMs: 60000 });
+    console.log(`  downloaded ${megabytes(build.size)} MB; its SHA-256 matches the pinned one`);
+  }
+  rmSync(py, { recursive: true, force: true });
+  run('tar', ['-xzf', archive, '-C', resources]);
+  const python = path.join(py, 'bin', 'python3');
+  // Only this Python's own packages and settings: nothing from the build
+  // machine's user site-packages, PYTHONPATH or pip configuration.
+  const env = {
+    HOME: os.homedir(), TMPDIR: os.tmpdir(), PATH: '/usr/bin:/bin:/usr/sbin:/sbin', LANG: 'en_US.UTF-8',
+    PYTHONNOUSERSITE: '1', PYTHONDONTWRITEBYTECODE: '1',
+  };
+  try {
+    execFileSync(python, ['-c', 'pass'], { env, stdio: 'ignore' });
+  } catch {
+    console.error(`\n  ✗ The ${ARCH} Python can't run on this Mac. Build on a Mac with that chip (release.yml does), or install Rosetta for an Intel build.\n`);
+    process.exit(1);
+  }
+
+  step('Installing the scanner\'s packages into it');
+  run(python, ['-s', '-m', 'pip', '--isolated', 'install', '--disable-pip-version-check', '--no-input',
+    '--no-warn-script-location', '--no-compile', '--index-url', 'https://pypi.org/simple',
+    '--cache-dir', path.join(CACHE, 'pip'), '--require-hashes', '--only-binary', ':all:',
+    '-r', path.join(ROOT, 'scripts', 'requirements.txt')], { env });
+  run(python, ['-s', '-m', 'pip', '--isolated', 'check', '--disable-pip-version-check'], { env });
+
+  const full = duKb(py);
+  trimPython(py, lib, xy);
+  const trimmed = duKb(py);
+  const shared = shareDriverNode(lib, resources);
+  signPython(py);
+  checkPython(py, lib, env);
+  console.log(`  Python ${build.version} and the scanner's packages: ${Math.round(full / 1024)} MB installed, `
+    + `${Math.round(trimmed / 1024)} MB after trimming, ${Math.round(duKb(py) / 1024)} MB in the app`
+    + (shared ? ' (Playwright runs on the app\'s own Node)' : ''));
+}
+
+function sha256File(file) {
+  return createHash('sha256').update(readFileSync(file)).digest('hex');
+}
+
+function duKb(dir) {
+  return Number.parseInt(execFileSync('du', ['-sk', dir]).toString(), 10) || 0;
+}
+
+// Every file under `dir`, not following links.
+function* walk(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const at = path.join(dir, entry.name);
+    if (entry.isDirectory()) yield* walk(at);
+    else yield { at, entry };
+  }
+}
+
+// The Mach-O programs and libraries under `dir`, as { file, slices, head }.
+function machoFiles(dir) {
+  const found = [];
+  for (const { at, entry } of walk(dir)) {
+    if (!entry.isFile()) continue;
+    const head = readAt(at, 0, 65536);
+    const slices = machoSlices(head);
+    if (slices.length) found.push({ file: at, slices });
+  }
+  return found;
+}
+
+function readAt(file, offset, length) {
+  const fd = openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(length);
+    const n = readSync(fd, buf, 0, length, offset);
+    return buf.subarray(0, n);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// What the scanner never uses, taken out to keep the download small. None of
+// it is imported by scrape.py or its packages (checkPython proves the imports
+// still load, and CI runs the scanner's pure functions on this Python):
+//   - bin/ keeps only the interpreter. pip's console scripts (idna, normalizer,
+//     playwright) name the build machine's path in their first line, and pip
+//     itself goes below: nothing installs into the app once it is built.
+//   - IDLE, tkinter and Tcl/Tk, turtle, lib2to3, ensurepip, the C headers and
+//     build files, man pages, test suites, and bytecode: without
+//     __pycache__ a module is compiled as it is imported (about 0.3 s for the
+//     scanner's), and ownPythonEnv never lets it write any into the app.
+//   - libpython's shared library: the interpreter has Python built in, so it is
+//     kept only if something inside links to it.
+function trimPython(py, lib, xy) {
+  step('Trimming what the scanner never uses');
+  const keepInBin = new Set([`python${xy}`, 'python3', 'python']);
+  for (const name of readdirSync(path.join(py, 'bin'))) {
+    if (!keepInBin.has(name)) rmSync(path.join(py, 'bin', name), { recursive: true, force: true });
+  }
+  const remove = [
+    'include', 'share', 'lib/pkgconfig',
+    ...readdirSync(path.join(py, 'lib')).filter((n) => /^(libtcl|libtk|tcl|tk|itcl|thread)/.test(n)).map((n) => `lib/${n}`),
+    ...['idlelib', 'tkinter', 'turtledemo', 'turtle.py', 'lib2to3', 'ensurepip', 'test', 'idle_test', `config-${xy}-darwin`]
+      .map((n) => path.relative(py, path.join(lib, n))),
+    ...readdirSync(path.join(lib, 'lib-dynload')).filter((n) => n.startsWith('_tkinter.')).map((n) => path.relative(py, path.join(lib, 'lib-dynload', n))),
+    ...readdirSync(path.join(lib, 'site-packages')).filter((n) => n === 'pip' || /^pip-.*\.dist-info$/.test(n))
+      .map((n) => path.relative(py, path.join(lib, 'site-packages', n))),
+  ];
+  for (const rel of remove) rmSync(path.join(py, rel), { recursive: true, force: true });
+  for (const dir of [...findDirs(py, (n) => n === '__pycache__'), ...findDirs(path.join(lib, 'site-packages'), (n) => n === 'tests')]) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  const libpython = path.join(py, 'lib', `libpython${xy}.dylib`);
+  if (existsSync(libpython)) {
+    const users = machoFiles(py).filter((m) => m.file !== libpython
+      && m.slices.some((s) => (machoSlice(readAt(m.file, s.offset, 65536)) || { dylibs: [] }).dylibs.some((d) => d.endsWith(`/libpython${xy}.dylib`))));
+    if (users.length) console.log(`  keeping libpython${xy}.dylib: ${path.relative(py, users[0].file)} links to it`);
+    else rmSync(libpython);
+  }
+}
+
+function findDirs(dir, match) {
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const at = path.join(dir, entry.name);
+    if (match(entry.name)) found.push(at);
+    else found.push(...findDirs(at, match));
+  }
+  return found;
+}
+
+// Playwright's driver carries its own Node (about 120 MB). When that is byte
+// for byte the Node the app already bundles for its server (Playwright 1.63
+// ships Node 24.21.0, the version build-app pins), the driver's becomes a link
+// to the app's: the same program, about 40 MB less to download. When they
+// differ, the driver keeps its own. Resolves whether it shared.
+function shareDriverNode(lib, resources) {
+  const driverNode = path.join(lib, 'site-packages', 'playwright', 'driver', 'node');
+  const appNode = path.join(resources, 'node');
+  if (!existsSync(driverNode) || !existsSync(appNode)) return false;
+  if (sha256File(driverNode) !== sha256File(appNode)) {
+    console.log('  Playwright\'s Node differs from the app\'s, so the driver keeps its own');
+    return false;
+  }
+  rmSync(driverNode);
+  symlinkSync(path.relative(path.dirname(driverNode), appNode), driverNode);
+  if (realpathSync(driverNode) !== realpathSync(appNode)) throw new Error('The driver\'s link to the app\'s Node is wrong.');
+  return true;
+}
+
+// Every program and library in the Python, signed ad hoc like the rest of the
+// app. On Apple Silicon unsigned code isn't allowed to run at all.
+function signPython(py) {
+  const files = machoFiles(py).map((m) => m.file);
+  for (let i = 0; i < files.length; i += 64) {
+    // Its only chatter is "replacing existing signature", once a file.
+    mustRun('codesign', ['--force', '--sign', '-', ...files.slice(i, i + 64)], process.env, 'Signing the app\'s Python failed');
+  }
+  console.log(`  signed ${files.length} programs and libraries ad hoc`);
+}
+
+// The Python as the app will run it: every program is for this chip and this
+// app's oldest macOS, the imports load (the compiled parts too: TRAPS §30), and
+// Playwright's driver starts. Any failure fails the build.
+function checkPython(py, lib, env) {
+  step('Checking the Python inside the app');
+  const newer = (v) => {
+    const [a, b] = [String(v).split('.').map(Number), MACOS_MIN.split('.').map(Number)];
+    return (a[0] - b[0] || (a[1] || 0) - (b[1] || 0)) > 0;
+  };
+  for (const m of machoFiles(py)) {
+    const slice = m.slices.find((s) => s.arch === ARCH);
+    const rel = path.relative(py, m.file);
+    if (!slice) throw new Error(`${rel} isn't built for ${ARCH}.`);
+    const info = machoSlice(readAt(m.file, slice.offset, 65536));
+    if (info?.minos && newer(info.minos)) throw new Error(`${rel} needs macOS ${info.minos}; the app promises ${MACOS_MIN}.`);
+  }
+  const python = path.join(py, 'bin', 'python3');
+  console.log(`  ${mustRun(python, ['-s', '-c', `${IMPORTS}; import sys; from importlib.metadata import version as v; `
+    + 'print("Python", sys.version.split()[0], "· Playwright", v("playwright"), "· requests", v("requests"), "· Pillow", v("pillow"))'],
+  env, 'The scanner\'s packages don\'t load in the app\'s Python')}`);
+  const driver = path.join(lib, 'site-packages', 'playwright', 'driver');
+  console.log(`  Playwright's driver starts: ${mustRun(path.join(driver, 'node'), [path.join(driver, 'package', 'cli.js'), '--version'],
+    env, 'Playwright\'s driver doesn\'t start')}`);
+}
+
+// What a check printed, or the build stops with what went wrong.
+function mustRun(file, args, env, what) {
+  try {
+    return execFileSync(file, args, { env, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+  } catch (err) {
+    console.error(`\n  ✗ ${what}:\n${String(err.stderr || err.message).trim().split('\n').slice(-8).map((l) => `      ${l}`).join('\n')}\n`);
+    process.exit(1);
+  }
+}
+
 // The app icon, from an SVG: sharp (already here, Next depends on it) draws it
 // at 1024px, sips makes the sizes macOS wants, iconutil packs them.
 async function makeIcns(svg, out) {

package/.next/standalone/scripts/gen-synthetic.mjs

@@ -179,6 +179,21 @@ function main() {
     const circle = Array.from({ length: size }, () => person(2, b.id));
     degree2.push(...circle);
   }
+  // In a real network some people are known by more than one of your
+  // connections: that is what "reachable 2+ ways" counts, and what makes
+  // sorting Degrees by ways in worth doing. About one in seven gets a second
+  // route, and some of those a third. Same person, same profile, another bridge.
+  const shared = [];
+  for (const p of degree2) {
+    if (rand() >= 0.15) continue;
+    const others = bridges.filter((b) => b.id !== p.source_connection_id);
+    const routes = rand() < 0.3 ? 2 : 1;
+    for (let k = 0; k < routes; k++) {
+      const b = others.splice(Math.floor(rand() * others.length), 1)[0];
+      shared.push({ ...p, id: `${p.id}-via${k + 1}`, source_connection_id: b.id, influence_signals: {} });
+    }
+  }
+  degree2.push(...shared);
   // Everyone again, together: circles now exist, so bridges get their boost.
   scoreRows([...degree1, ...degree2]);
   degree1.sort((a, b) => b.power_score - a.power_score);
@@ -205,7 +220,7 @@ function main() {
   const kb = Math.round(JSON.stringify(payload).length / 1024);
   console.log(`wrote ${out}  (${kb} KB, seed ${seed})`);
   console.log(`  1st degree : ${degree1.length}`);
-  console.log(`  2nd degree : ${degree2.length} across ${BRIDGE_COUNT} bridges`);
+  console.log(`  2nd degree : ${degree2.length - shared.length} people across ${BRIDGE_COUNT} bridges, ${new Set(shared.map((r) => r.profile_url)).size} of them reachable 2+ ways`);
   console.log(`  catalysts  : ${bridges.filter((b) => b.is_catalyst).length}`);
   console.log(`  tier mix   : ${['S','A','B','C','D'].map((t) => `${t}:${tiers[t] || 0}`).join('  ')}`);
 }

package/.next/standalone/scripts/readme_buttons.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Draw the README's download buttons.
+
+A GitHub README can't style links, so the buttons are pictures: drawn here from
+HTML in Chrome, with the app icon inside, and saved at twice their shown size so
+they stay sharp. Each has its own background, so it reads on GitHub's light and
+dark themes alike. No server needed:
+
+    python3 scripts/readme_buttons.py
+
+Requires playwright (pip3 install playwright) and Google Chrome. Redraw whenever
+the icon (desktop/icon/icon.svg) or the wording changes.
+"""
+import pathlib
+import re
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+OUT = ROOT / "docs" / "img"
+ICON = (ROOT / "desktop" / "icon" / "icon.svg").read_text()
+# The icon's artwork sits in its 1024 canvas with a margin (the macOS grid).
+# Cropping to the rounded square lets it fill its spot in the button. A new
+# icon with another canvas needs a new crop, so stop rather than draw it wrong.
+CROP = "100 100 824 824"
+root = re.search(r"<svg\b[^>]*>", ICON)
+if not root or 'viewBox="0 0 1024 1024"' not in root.group(0):
+    sys.exit('desktop/icon/icon.svg is no longer a 1024 canvas (viewBox="0 0 1024 1024"): '
+             "update CROP in scripts/readme_buttons.py, then look at docs/img/download-*.png")
+tag = re.sub(r'\s(?:viewBox|width|height)="[^"]*"', "", root.group(0))
+ICON = ICON[:root.start()] + tag.replace("<svg", f'<svg viewBox="{CROP}"', 1) + ICON[root.end():]
+
+ARROW = """<svg class="arrow" viewBox="0 0 24 24" width="30" height="30" aria-hidden="true">
+  <circle cx="12" cy="12" r="11" fill="none" stroke="currentColor" stroke-width="1.6" opacity=".55"/>
+  <path d="M12 6.5v9M7.8 11.6 12 15.8l4.2-4.2" fill="none" stroke="currentColor" stroke-width="2"
+        stroke-linecap="round" stroke-linejoin="round"/></svg>"""
+
+# (file, top line, big line, bottom line, style)
+BUTTONS = [
+    ("download-apple-silicon.png", "Click to download for Mac", "Apple Silicon", "M1 or newer", "green"),
+    ("download-intel.png",         "Click to download for Mac", "Intel",         "Macs with an Intel chip", "slate"),
+]
+
+CSS = """
+* { box-sizing: border-box; margin: 0; }
+body { background: transparent; font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", sans-serif;
+       -webkit-font-smoothing: antialiased; }
+.pad { display: inline-block; padding: 6px 8px 12px; }
+.btn { display: flex; align-items: center; gap: 16px; width: 330px; padding: 13px 18px 13px 14px;
+       border-radius: 16px; color: #fff; }
+/* Dark enough that white text passes WCAG AA (4.5:1) everywhere on it. */
+.green { background: linear-gradient(180deg, #1f883d 0%, #1a7f37 55%, #116329 100%);
+         box-shadow: 0 1px 0 rgba(255,255,255,.22) inset, 0 0 0 1px rgba(0,0,0,.12), 0 6px 16px rgba(17,99,41,.35); }
+.slate { background: linear-gradient(180deg, #3a414a 0%, #2b3137 55%, #24292f 100%);
+         box-shadow: 0 1px 0 rgba(255,255,255,.16) inset, 0 0 0 1px rgba(255,255,255,.14), 0 6px 16px rgba(0,0,0,.28); }
+.icon { flex: none; width: 56px; height: 56px; border-radius: 13px; overflow: hidden;
+        box-shadow: 0 0 0 1px rgba(255,255,255,.18), 0 2px 6px rgba(0,0,0,.35); }
+.icon svg { display: block; width: 56px; height: 56px; }
+.text { flex: 1; min-width: 0; line-height: 1.15; }
+.top { font-size: 12.5px; font-weight: 600; letter-spacing: .02em; }
+.big { font-size: 25px; font-weight: 800; letter-spacing: -.01em; margin: 2px 0 3px; }
+.sub { font-size: 13.5px; font-weight: 500; }
+.arrow { flex: none; color: #fff; }
+"""
+
+
+def button_html(top, big, sub, style):
+    return f"""<!doctype html><html><head><style>{CSS}</style></head><body>
+<div class="pad" id="shot"><div class="btn {style}">
+  <div class="icon">{ICON}</div>
+  <div class="text"><div class="top">{top}</div><div class="big">{big}</div><div class="sub">{sub}</div></div>
+  {ARROW}
+</div></div></body></html>"""
+
+
+def main():
+    from playwright.sync_api import sync_playwright
+
+    with sync_playwright() as p:
+        browser = p.chromium.launch(channel="chrome")
+        page = browser.new_page(viewport={"width": 600, "height": 200}, device_scale_factor=2)
+        for name, top, big, sub, style in BUTTONS:
+            page.set_content(button_html(top, big, sub, style))
+            page.locator("#shot").screenshot(path=str(OUT / name), omit_background=True)
+            print(f"  wrote docs/img/{name}")
+        browser.close()
+
+
+if __name__ == "__main__":
+    main()

package/.next/standalone/scripts/requirements.txt

@@ -1,4 +1,106 @@
-playwright>=1.40.0
-requests>=2.31.0
-Pillow>=10.0.0
-tzdata>=2024.1; sys_platform == "win32"
+# The scanner's Python packages (scripts/scrape.py), pinned to exact versions,
+# with the SHA-256 of every file pip may install for each. The same file goes
+# into the Python inside the Mac app when it is built (scripts/build-app.mjs),
+# and into the scanner's own environment when the Scan page sets one up.
+#
+# To change a version, edit its line and run
+#   node scripts/pin-python-packages.mjs
+# which rewrites the hashes from PyPI. Every dependency is listed: once hashes
+# are used, pip refuses anything that isn't.
+
+--only-binary :all:
+--require-hashes
+
+# Drives the user's own Google Chrome (channel="chrome"), so no browser is downloaded.
+# Its wheel carries Playwright's driver, which it needs.
+playwright==1.63.0 \
+    --hash=sha256:354e15b29503565fc598b89f16fbe070459343bef9d7498a93e304864000c6a7 \
+    --hash=sha256:84c540759e8e7f01e690e197e04060f48899d37cea322299f255843273d3385d \
+    --hash=sha256:ad21bc07516b187965a7521c5cf0df0bd657b17482eaad74335272d35a2b07de \
+    --hash=sha256:c89fc4736502a1f0fac2c8ca5d10c0cbc1c669f1f4774a2d8507a43140e4d53f \
+    --hash=sha256:fd1aa00631d44d55e56e0975bf3f3f285fac4a9fd2813183f0c12a488f1a1b24
+
+# Playwright's own dependencies: greenlet, pyee, and pyee's typing-extensions.
+greenlet==3.5.6 \
+    --hash=sha256:1c20ea32a73d17b9b60e3371240e17b0068120c98a5ec01a224a7dd8c89733ba \
+    --hash=sha256:45bfd2b51e38aaa5f9849f114d9c7c1d75f69187c849b3549cd64c465283abfa \
+    --hash=sha256:8cddea1b8339451c2fb3388e138347b6126744f33b611bdb55b7357361cfef46 \
+    --hash=sha256:95e7c44d072db623a1aab04ce488cf9533294a77ed9d072cd503a3596f4106ac \
+    --hash=sha256:975736b002ed080d124cf81a79cb7e05cb26d6b3f5c7a7b651c0fcce70353aa1 \
+    --hash=sha256:9a09d59bef1db94f384b5bcc2d523694d338f3df6b757aeeaf7baca5d0c0be88 \
+    --hash=sha256:a5876d0a60355af98d535c47f6cd6eb0f8a432396dab26845d380b92f8412422 \
+    --hash=sha256:a6a4b98a9132e0f45c9fc245a63894cfd8c45fb7a0d6bffc5eab3ec327cf7324 \
+    --hash=sha256:b7d501d5eb5d4f67207df364752ad697465b834268744be7581c18d81d35d41d \
+    --hash=sha256:c59acfa8eb73a1e0d484392dc002bdf001fd4ce73394e0132df3d1ab6093d7cb \
+    --hash=sha256:c75116c9de79949de23006e2d9b35ee82874c594fcf5c0311b439acaa14b8441 \
+    --hash=sha256:e85880b538e59a59f55117b81f208a6660ad5ac328aad9305f812d9b8bc67a0f \
+    --hash=sha256:eed88b64a5e5da72d6a71cdc5aaeefaa5ced9b748f8d19f89800b339961dad39 \
+    --hash=sha256:f96f0e30b5a95c7631b12bfe214cbc90ec8fe8cfa36920596c10514a65743519 \
+    --hash=sha256:f98e8215e172f567ce80eeaed9107fb4d32b6c44f26983d9b8334658136a205a
+
+pyee==13.0.1 \
+    --hash=sha256:af2f8fede4171ef667dfded53f96e2ed0d6e6bd7ee3bb46437f77e3b57689228
+
+typing-extensions==4.16.0 \
+    --hash=sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8
+
+requests==2.34.2 \
+    --hash=sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0
+
+# requests' own dependencies: certifi, charset-normalizer, idna, urllib3.
+certifi==2026.7.22 \
+    --hash=sha256:62f22742b58a1a33014a2b6b706588a8d7e2a88ae7bd1a6ebe8c992928483775
+
+charset-normalizer==3.5.1 \
+    --hash=sha256:15f024313246a4ed976c60f440bb8d257815513a681d212ff74fd46f7d715a90 \
+    --hash=sha256:2f06b7eae9dbe77fe1d644ca244dad508de8d302870a43f3c559b521270938a0 \
+    --hash=sha256:41876ee62a3dddf48ff1121ad8f0798032aa03f2fd35f21f34a4cab14f18d8d2 \
+    --hash=sha256:4582c27e8c889d64811987b5967fbd3ae0c823fe1fd933b543d55ac20bb475fa \
+    --hash=sha256:5b6d1386bf0096d26d3a863dc0a487a5b4eb9aa93cf5ba69683d29dde6b9d60f \
+    --hash=sha256:62b55f6722735a6c472f88361cde6640608773d9443cebdbb51abf436a1fcdd3 \
+    --hash=sha256:6df0ec430f9a831772c23ca5a224cba36517a58a84bb32c32bb59a9fa67c47f6 \
+    --hash=sha256:94d78ecec2605a8d0398b0f365d5f12a63248438516f5dac536a5eff7337df4a \
+    --hash=sha256:96eefc178f8636b9c760c5829345307fd81cfae9ab1e80997dbddeb0f54ee9a3 \
+    --hash=sha256:a6dac12ff6b846103483683f60c5f8fee205121adc58ffd87e90a90a3af69e99 \
+    --hash=sha256:aa2bb0b37202dca27175591f761108b5d34096ade1191ffe4808bdf6b1571488 \
+    --hash=sha256:b9af956078716df40d985fb0dfeb2c2120c5ca92ba4ff4b388acfd01cdc14d08 \
+    --hash=sha256:c428c6c31eb5f4277d7f8eccaf767fbd548ddd5ce3c8b4f4cbbfab3d96b5904c \
+    --hash=sha256:c7b742bf31c88566b4bb6335a7f393bb322e580b6bb98df7bd0c25e6e3519ce8 \
+    --hash=sha256:cee5dd7c6fb5dd52a0fe2a740f9bc6e3593f5f8b1788bde49de02086f30182b2 \
+    --hash=sha256:d1ee1e296209fdce05b81b663250eefa02213a2da7b41bf26f7829b8ba3545aa \
+    --hash=sha256:e90251c0c7bdd54a100a0dce3c07b7e637278c93af29dbf78ebb89a58c4bac7d \
+    --hash=sha256:e9fbdce1e47394b09bc9f26ab117dfc8d6491977a11d86f592bb42c779db2fda \
+    --hash=sha256:eda059b6bc8bc0812d626fd91a7ce01bf583df0a61296eff390fd94141a34e30
+
+idna==3.20 \
+    --hash=sha256:ab7ae7122974553370f0bdb919e1a960b2cd1bc1ef0276416d896db81c14582c
+
+urllib3==2.8.0 \
+    --hash=sha256:0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3
+
+# Profile photos (scripts/image_store.py).
+pillow==12.3.0 \
+    --hash=sha256:00808c5e14ef63ac5161091d242999076604ff74b883423a11e5d7bbb38bf756 \
+    --hash=sha256:0847a763afefb695bc912d7c131e7e0632d4edc1d8698f58ddabec8e46b8b6d3 \
+    --hash=sha256:23d27a3e0307ec2244cc51e7287b919aa68d097504ebe19df4e76a98a3eea5bd \
+    --hash=sha256:251bf95b67017e27b13d82f5b326234ca62d70f9cf4c2b9032de2358a3b12c7b \
+    --hash=sha256:37d6d0a00072fd2948eb22bce7e1475f34569d90c87c59f7a2ec59541b77f7a6 \
+    --hash=sha256:5594fc43d548a7ed94949d139aa1341b270f1863f11cfd37f5a6c8b778a6b67f \
+    --hash=sha256:6c0016e7b354317c4e9e525b937ac8596c38d2d232b419529b9cd7a1cd46e39a \
+    --hash=sha256:78cb2c6865a35ab8ff8b75fd122f6033b92a62c82801110e48ddd6c936a45d91 \
+    --hash=sha256:7a743ff716f746fc19a9557f60dab1600d4613255f8a7aeb3cdde4db7eb15a66 \
+    --hash=sha256:ba09209fbe443b4acccebe845d8a138b89a8f4fbaeedd44953490b5315d5e965 \
+    --hash=sha256:ba54cfebe86920a559a7c4d6b9050791c20513650a1952ebe3368c7dc70306f8 \
+    --hash=sha256:bcb46e2f9feff8d06323983bd83ed00c201fdcab3d74973e7072a889b3979fcd \
+    --hash=sha256:bcc33feacfaefce60c12fd500a277533bdc02b10a19f7f6d348763d8140bbba7 \
+    --hash=sha256:d69141514cc30b774ceea5e3ed3a6635c8d8a96edf664689b890f4089111fb35 \
+    --hash=sha256:d9c7f76c0673154f044e9d78c8655fb4213f6ca31a836df48b40fe5d187717b9 \
+    --hash=sha256:e158cb00350dc278f3b91551101aa7d12415a66ebf2c91d8d5ac14e56ddd3ad0 \
+    --hash=sha256:e9aeb04d6aef139de265b29683e119b638208f88cf73cdd1658aa07221165321 \
+    --hash=sha256:f0606c8bf2cdefea14a43530f7657cbbb7ecf1c4222512492ef4a4434a9501ec \
+    --hash=sha256:f7401aebd7f581d7f83a439d87d474999317ee099218e5ad25d125290990ba65 \
+    --hash=sha256:ffd0c5368496f41b0944be820fcb7a838aa6e623d250b01acf2643939c3f99d7
+
+# Windows only: Python there has no time zone database (docs/brain/DESKTOP.md D3).
+tzdata==2026.4 ; sys_platform == "win32" \
+    --hash=sha256:c2169a8b0a7a5e9674da5a135ccdfb2b3e671b333ed9fed17b41f73c34476e81

package/.next/standalone/scripts/screenshots.py

@@ -102,6 +102,8 @@ def main():
             if script:
                 page.evaluate(script)
                 page.wait_for_timeout(1500)
+            # The dev server's own badge (Next.js's "N" in a corner) isn't part of the app.
+            page.add_style_tag(content="nextjs-portal { display: none !important; }")
             page.screenshot(path=str(OUT / name))
             print(f"  wrote docs/img/{name}")