@@ -35,6 +35,7 @@ import { checkStacks } from "./checks.mjs";
 import { stackPageHtml } from "./lib/stack-page.mjs";
 import { freshnessLineHtml, freshnessPageHtml, freshnessStats, newEntriesLineHtml } from "./lib/freshness.mjs";
 import { licenceTerms, listStackFiles, owes, parseStack, pickPath } from "./lib/stacks.mjs";
+import { createDistWriter } from "./lib/dist-writer.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, "..");
@@ -281,36 +282,8 @@ function notFoundHtml(site) {
 `;
 }
 
-/*
- * Output goes through one writer that creates a directory once, writes a
- * file only when its bytes changed and remembers every path it produced, so
- * the build can prune what an earlier build left behind instead of wiping
- * dist/ and recreating 420 directories (94% of the build time on a slow
- * disk). `--clean` still wipes first; the result is byte-identical either way.
- */
-const produced = new Set();
-const madeDirs = new Set();
-let writes = 0;
-
-function ensureDir(dir) {
-  if (madeDirs.has(dir)) return;
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  madeDirs.add(dir);
-}
-
-/** Writes `content` (string or Buffer) to dist-relative `rel` if it differs. */
-function writeOut(rel, content) {
-  const full = path.join(DIST, rel);
-  produced.add(rel.split(path.sep).join("/"));
-  ensureDir(path.dirname(full));
-  const next = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
-  if (fs.existsSync(full)) {
-    const stat = fs.statSync(full);
-    if (stat.isFile() && stat.size === next.length && fs.readFileSync(full).equals(next)) return;
-  }
-  fs.writeFileSync(full, next);
-  writes += 1;
-}
+// Output writer: writes only changed bytes and prunes what it did not produce (lib/dist-writer.mjs).
+const { ensureDir, writeOut, pruneDist, produced, writes } = createDistWriter(DIST);
 
 /** Copies a file into dist (through writeOut, so unchanged files are left alone). */
 function copyOut(src, rel) {
@@ -333,20 +306,6 @@ function copyPublic(src, skip, prefix = "") {
   }
 }
 
-/** Removes every file and directory in dist that this build did not produce. */
-function pruneDist(dir = DIST, prefix = "") {
-  let kept = 0;
-  for (const name of fs.readdirSync(dir)) {
-    const full = path.join(dir, name);
-    const rel = prefix ? `${prefix}/${name}` : name;
-    if (fs.statSync(full).isDirectory()) {
-      if (pruneDist(full, rel) === 0) fs.rmSync(full, { recursive: true, force: true });
-      else kept += 1;
-    } else if (produced.has(rel)) kept += 1;
-    else fs.rmSync(full, { force: true });
-  }
-  return kept;
-}
 
 /** Returns file => link resolver for links in that file's body (`file.path` is repo-relative). */
 function linkResolvers(entries, config, entryBase = "../") {
@@ -769,7 +728,7 @@ function main() {
   console.log(
     `Prerendered ${visible.length} entry rows into index.html; wrote ${pages.written.length} entry pages, ${stackPages.written.length} stack pages, ${categoryPages.written.length} category pages, ${guidePages.written.length} guide pages, sitemap.xml, robots.txt, 404.html, freshness/index.html`
   );
-  console.log(`${writes} of ${produced.size} output files changed${clean ? " (clean build)" : ""}; ${((Date.now() - started) / 1000).toFixed(1)}s`);
+  console.log(`${writes()} of ${produced.size} output files changed${clean ? " (clean build)" : ""}; ${((Date.now() - started) / 1000).toFixed(1)}s`);
 }
 
 main();
@@ -0,0 +1,53 @@
+/**
+ * The build's output writer. It creates a directory once, writes a file only
+ * when its bytes changed and remembers every path it produced, so the build
+ * can prune what an earlier build left behind instead of wiping dist/ and
+ * recreating 420 directories (94% of the build time on a slow disk).
+ * `--clean` still wipes first; the result is byte-identical either way.
+ * The directory is a parameter so the tests can run it in a temp dir (#265).
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export function createDistWriter(dist) {
+  const produced = new Set();
+  const madeDirs = new Set();
+  let writes = 0;
+
+  function ensureDir(dir) {
+    if (madeDirs.has(dir)) return;
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    madeDirs.add(dir);
+  }
+
+  /** Writes `content` (string or Buffer) to dist-relative `rel` if it differs. */
+  function writeOut(rel, content) {
+    const full = path.join(dist, rel);
+    produced.add(rel.split(path.sep).join("/"));
+    ensureDir(path.dirname(full));
+    const next = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
+    if (fs.existsSync(full)) {
+      const stat = fs.statSync(full);
+      if (stat.isFile() && stat.size === next.length && fs.readFileSync(full).equals(next)) return;
+    }
+    fs.writeFileSync(full, next);
+    writes += 1;
+  }
+
+  /** Removes every file and directory in dist that this build did not produce. */
+  function pruneDist(dir = dist, prefix = "") {
+    let kept = 0;
+    for (const name of fs.readdirSync(dir)) {
+      const full = path.join(dir, name);
+      const rel = prefix ? `${prefix}/${name}` : name;
+      if (fs.statSync(full).isDirectory()) {
+        if (pruneDist(full, rel) === 0) fs.rmSync(full, { recursive: true, force: true });
+        else kept += 1;
+      } else if (produced.has(rel)) kept += 1;
+      else fs.rmSync(full, { force: true });
+    }
+    return kept;
+  }
+
+  return { ensureDir, writeOut, pruneDist, produced, writes: () => writes };
+}
@@ -2120,6 +2120,35 @@ eq("search: q from the URL is capped", readState(`?q=${"a".repeat(5000)}`, { q:
   eq("plainText: links and emphasis stripped", plainText("See **[the guide](a.md)** and `code`\n now"), "See the guide and code now");
 }
 
+/* incremental dist writer (#265) ------------------------------------------ */
+{
+  const { createDistWriter } = await import("./dist-writer.mjs");
+  const fsm = (await import("node:fs")).default;
+  const osm = (await import("node:os")).default;
+  const pathm = (await import("node:path")).default;
+  const dir = fsm.mkdtempSync(pathm.join(osm.tmpdir(), "fgda-dist-"));
+  try {
+    const first = createDistWriter(dir);
+    first.writeOut("a/index.html", "hello");
+    first.writeOut("b.txt", "same");
+    eq("dist: first build writes both", first.writes(), 2);
+    fsm.mkdirSync(pathm.join(dir, "old"), { recursive: true });
+    fsm.writeFileSync(pathm.join(dir, "old", "x.html"), "stale");
+
+    const second = createDistWriter(dir);
+    second.writeOut("a/index.html", "hello");
+    second.writeOut("b.txt", "diff"); // same size, other bytes
+    eq("dist: unchanged bytes are not rewritten, changed ones are", second.writes(), 1);
+    eq("dist: same-size change lands", fsm.readFileSync(pathm.join(dir, "b.txt"), "utf8"), "diff");
+    second.pruneDist();
+    eq("dist: a stale file is removed", fsm.existsSync(pathm.join(dir, "old", "x.html")), false);
+    eq("dist: its empty directory is pruned", fsm.existsSync(pathm.join(dir, "old")), false);
+    eq("dist: a directory holding a produced file stays", fsm.existsSync(pathm.join(dir, "a", "index.html")), true);
+  } finally {
+    fsm.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 /* report (keep last) ------------------------------------------------------ */
 if (failures.length) {
   console.error(`lib.test failed (${failures.length}):`);