@writedocs/generator 0.4.4 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {

package/src/layout/components/AskAiWidget.astro

@@ -34,10 +34,23 @@ const askAiId = process.env.WRITEDOCS_ASK_AI_ID || config.integrations.askAi?.id
 const askAiInitScript = askAiId
   ? `DocsBotAI.init(${JSON.stringify({ id: askAiId })});`
   : null;
+// O ClientRouter (BaseLayout.astro) troca o <body> inteiro a cada navegação,
+// e o DocsBot monta o widget num #docsbotai-root que ele mesmo anexa ao
+// <body> - então o widget ia embora junto com o body antigo. Rodar o init de
+// novo não resolve: o router não reexecuta script inline de conteúdo
+// idêntico, e o mount() do DocsBot recusa montar duas vezes sem unmount().
+// Aqui o root vivo é marcado com o mesmo atributo de `transition:persist`
+// que o Astro já sabe mover, e o documento novo ganha um slot com o mesmo
+// nome - o swap do Astro leva o elemento inteiro (shadow root com os
+// estilos, estado do React, chat aberto) para a página nova. Roda uma vez
+// só pelo mesmo motivo acima, e o listener no `document` sobrevive às
+// navegações.
+const askAiPersistScript = `document.addEventListener("astro:before-swap",function(e){var r=document.getElementById("docsbotai-root");if(!r)return;r.setAttribute("data-astro-transition-persist","wd-ask-ai");var s=e.newDocument.createElement("div");s.setAttribute("data-astro-transition-persist","wd-ask-ai");e.newDocument.body.appendChild(s);});`;
 ---
 {askAiId && (
   <>
     <script is:inline set:html={askAiLoaderScript} />
     {askAiInitScript && <script is:inline set:html={askAiInitScript} />}
+    <script is:inline set:html={askAiPersistScript} />
   </>
 )}

package/src/lib/styles-asset-integration.js

@@ -1,210 +1,244 @@
-// Lets a static asset referenced by a root-relative URL - a writedocs.json
-// field (styles.favicon, styles.logo, footer.logo, styles.background.
-// images.{light,dark}, seo.ogImage, styles.fonts.*.source - the exact set
-// collectConfiguredAssetPaths() in lib/config.ts resolves) *or* a plain
-// image written directly into a page's own MDX/Markdown body
-// (`![alt](/images/foo.png)`, a raw `<img src="/images/foo.png">`, the
-// `<Image src="...">` component, `<Card img="...">`, ...) - resolve from
-// *anywhere* in the project, not just public/. "Any place to store
-// assets" is the whole point: a site author shouldn't have to know Astro
-// has a public/ convention at all, let alone reorganize their project
-// around it, just to reference an image from a doc page.
-//
-// Deliberately NOT implemented as "copy everything into public/ (or a
-// merged scratch dir) before Astro starts, then leave Astro's own
-// publicDir alone": that would either (a) write into the user's own
-// public/ folder as a side effect - a real file appearing in their
-// project tree that they didn't create, which writedocsTempDir()'s own
-// doc comment already argues against doing anywhere in this codebase, or
-// (b) point publicDir at a one-shot copied scratch dir instead of the
-// real public/, which would regress `writedocs dev`'s live file-reload
-// for the *existing*, common case of a file genuinely living under
-// public/ - Vite's own dev server watches and serves publicDir straight
-// off disk per-request with no copy step involved at all today; a byte
-// copy taken once at startup wouldn't pick up a live edit to that file
-// without a full dev-server restart.
-//
-// Instead, this is a small Astro integration with two hooks, each
-// resolving fresh rather than relying on any one-shot copy:
-// - astro:server:setup (dev): adds Vite dev-server middleware that
-//   intercepts any request whose extension looks like a static asset
-//   (looksLikeAssetPath() below - images/fonts, the same set
-//   MIME_BY_EXTENSION already knows how to serve) and - only if it
-//   doesn't already exist under public/ (that stays Vite's own job,
-//   unshadowed) - streams it straight from wherever it lives in the
-//   project. Not scoped to writedocs.json's own configured fields specifically
-//   (an earlier version of this file was) - a page's own MDX can
-//   reference an image path this integration has no way to know about
-//   ahead of time short of parsing every page's content on every
-//   request, so instead of trying to enumerate what *should* be
-//   reachable, it just resolves whatever *is* actually requested,
-//   directly, the same way Vite's own publicDir serving already does.
-// - astro:build:done: a one-time pass after Astro's own build finishes.
-//   First, the same writedocs.json-field-driven copy as before (still needed
-//   as its own pass - background images/font sources render into CSS
-//   `url(...)` inside a `<style>` block, and seo.ogImage into a `<meta
-//   content="...">` tag, neither of which the second pass below would
-//   ever see). Second, copyReferencedContentAssets() below scans every
-//   built .html page for `src="/..."` references (an `<img>`, mainly -
-//   see its own comment) not already present in the output, and resolves
-//   + copies each the same way - this is what actually covers a plain
-//   content image, since there's no fixed field name to read it from up
-//   front the way there is for writedocs.json's own fields. A real static
-//   build has no "later" for a live-reload concern to apply to, so a
-//   single pass of each here is sufficient.
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { loadDocsConfig, collectConfiguredAssetPaths } from './config.ts';
-
-const MIME_BY_EXTENSION = {
-  '.svg': 'image/svg+xml',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.avif': 'image/avif',
-  '.ico': 'image/x-icon',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.ttf': 'font/ttf',
-  '.otf': 'font/otf',
-};
-
-function mimeFor(filePath) {
-  return MIME_BY_EXTENSION[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
-}
-
-/** Resolves a root-relative `urlPath` (e.g. "/images/hero.svg") against
- *  `contentDir` directly - not `<contentDir>/public` - the fallback
- *  location for one of the styles/footer/seo asset fields
- *  (collectConfiguredAssetPaths()) when it isn't sitting under public/.
- *  Segment-by-segment path-traversal guard (no
- *  `..`/`.` segments) since `urlPath` ultimately comes from an incoming
- *  request URL in the dev-server case, not just trusted writedocs.json
- *  content. Returns an absolute path, or null if nothing real is there. */
-function resolveOutsidePublic(urlPath, contentDir) {
-  const segments = urlPath.replace(/^\/+/, '').split('/');
-  if (segments.some((segment) => segment === '..' || segment === '.' || segment === '')) return null;
-  const absolute = path.join(contentDir, ...segments);
-  try {
-    return fs.statSync(absolute).isFile() ? absolute : null;
-  } catch {
-    return null;
-  }
-}
-
-function publicPathFor(urlPath, contentDir) {
-  const segments = urlPath.replace(/^\/+/, '').split('/');
-  return path.join(contentDir, 'public', ...segments);
-}
-
-/** Root-relative, recognized-extension paths only - the same "does this
- *  look like a static asset at all" question mimeFor()'s own map already
- *  answers, reused here as the dev-middleware/build-scan gate instead of
- *  a fixed list of writedocs.json field names. Deliberately permissive: a page
- *  or config field asking for a path this returns true for gets a real
- *  attempt to resolve it from anywhere in the project; anything else
- *  (an actual API route, a `.html` page request, ...) is left alone,
- *  same as before this existed. */
-function looksLikeAssetPath(urlPath) {
-  return Object.prototype.hasOwnProperty.call(MIME_BY_EXTENSION, path.extname(urlPath).toLowerCase());
-}
-
-/** Recursively lists every `.html` file under `dir`. Astro's own build
- *  output is already a flat-ish tree of one .html per route, so this is
- *  just a plain walk - no globbing dependency needed for something this
- *  small. */
-function listHtmlFiles(dir) {
-  const results = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      results.push(...listHtmlFiles(full));
-    } else if (entry.isFile() && entry.name.endsWith('.html')) {
-      results.push(full);
-    }
-  }
-  return results;
-}
-
-/** Scans every built page for root-relative, recognized-extension `src="/..."`
- *  references (`<img src="...">`, mainly - what `Image.astro`, `Frame.astro`,
- *  and a raw `![]()`/`<img>` in MDX all ultimately render down to; a
- *  `srcset="..."` attribute is checked too, since it's the same kind of
- *  reference and costs nothing extra to also cover) that aren't already
- *  present in the build output, and copies each one in from wherever it
- *  resolves in the project via resolveOutsidePublic() - the same
- *  fallback the dev middleware below already uses, just applied once,
- *  after the fact, to the rendered HTML instead of to live requests.
- *  This is what actually covers a plain content-body image: unlike a
- *  writedocs.json field, there's no fixed set of field names to read a
- *  content image's path from ahead of time, so instead this reads
- *  whatever `src` a page's own rendered markup ends up containing. */
-function copyReferencedContentAssets(outDir, contentDir) {
-  const attrPattern = /\b(?:src|srcset)="([^"]+)"/g;
-  for (const htmlFile of listHtmlFiles(outDir)) {
-    const html = fs.readFileSync(htmlFile, 'utf8');
-    let match;
-    while ((match = attrPattern.exec(html))) {
-      // srcset can hold a comma-separated list of "url descriptor" pairs -
-      // split it out; a plain src is already just the one URL.
-      const candidates = match[1].split(',').map((part) => part.trim().split(/\s+/)[0]).filter(Boolean);
-      for (const urlPath of candidates) {
-        if (!urlPath.startsWith('/') || urlPath.startsWith('//')) continue; // only root-relative - not external, not protocol-relative
-        if (!looksLikeAssetPath(urlPath)) continue;
-        const segments = urlPath.replace(/^\/+/, '').split('/');
-        const outPath = path.join(outDir, ...segments);
-        if (fs.existsSync(outPath)) continue; // already present - via public/'s passthrough copy, or a previous iteration of this same loop
-        const resolved = resolveOutsidePublic(urlPath, contentDir);
-        if (!resolved) continue; // doesn't resolve to a real file anywhere in the project either - leave the broken reference as-is, same as today
-        fs.mkdirSync(path.dirname(outPath), { recursive: true });
-        fs.copyFileSync(resolved, outPath);
-      }
-    }
-  }
-}
-
-export function stylesAssetFallback(contentDir) {
-  return {
-    name: 'writedocs-styles-asset-fallback',
-    hooks: {
-      'astro:server:setup': ({ server }) => {
-        server.middlewares.use((req, res, next) => {
-          if (!req.url) return next();
-          const urlPath = req.url.split('?')[0];
-          if (!looksLikeAssetPath(urlPath)) return next();
-          if (fs.existsSync(publicPathFor(urlPath, contentDir))) return next(); // real public/ file - Vite's own static serving already handles it, don't shadow
-          const resolved = resolveOutsidePublic(urlPath, contentDir);
-          if (!resolved) return next();
-          res.setHeader('Content-Type', mimeFor(resolved));
-          fs.createReadStream(resolved).pipe(res);
-        });
-      },
-      'astro:build:done': async ({ dir }) => {
-        const outDir = fileURLToPath(dir);
-        const config = loadDocsConfig(contentDir);
-        // Pass 1: writedocs.json's own configured fields. Kept as its own,
-        // field-name-driven pass rather than folded into pass 2 below -
-        // background images/font sources render into CSS `url(...)`
-        // inside a `<style>` block, and seo.ogImage into a `<meta
-        // content="...">` tag, none of which pass 2's src="..."/
-        // srcset="..." attribute scan would ever see.
-        for (const urlPath of collectConfiguredAssetPaths(config)) {
-          const segments = urlPath.replace(/^\/+/, '').split('/');
-          const outPath = path.join(outDir, ...segments);
-          if (fs.existsSync(outPath)) continue; // already present via public/'s normal passthrough copy
-          const resolved = resolveOutsidePublic(urlPath, contentDir);
-          if (!resolved) continue; // not configured to a real file anywhere - same as today, just renders a broken <link>/<img>
-          fs.mkdirSync(path.dirname(outPath), { recursive: true });
-          fs.copyFileSync(resolved, outPath);
-        }
-        // Pass 2: arbitrary content-body assets - anything a page's own
-        // rendered HTML references by src/srcset that pass 1 didn't
-        // already account for.
-        copyReferencedContentAssets(outDir, contentDir);
-      },
-    },
-  };
-}
+// Lets a static asset referenced by a root-relative URL - a writedocs.json
+// field (styles.favicon, styles.logo, footer.logo, styles.background.
+// images.{light,dark}, seo.ogImage, styles.fonts.*.source - the exact set
+// collectConfiguredAssetPaths() in lib/config.ts resolves) *or* a plain
+// image written directly into a page's own MDX/Markdown body
+// (`![alt](/images/foo.png)`, a raw `<img src="/images/foo.png">`, the
+// `<Image src="...">` component, `<Card img="...">`, ...) - resolve from
+// *anywhere* in the project, not just public/. "Any place to store
+// assets" is the whole point: a site author shouldn't have to know Astro
+// has a public/ convention at all, let alone reorganize their project
+// around it, just to reference an image from a doc page.
+//
+// Deliberately NOT implemented as "copy everything into public/ (or a
+// merged scratch dir) before Astro starts, then leave Astro's own
+// publicDir alone": that would either (a) write into the user's own
+// public/ folder as a side effect - a real file appearing in their
+// project tree that they didn't create, which writedocsTempDir()'s own
+// doc comment already argues against doing anywhere in this codebase, or
+// (b) point publicDir at a one-shot copied scratch dir instead of the
+// real public/, which would regress `writedocs dev`'s live file-reload
+// for the *existing*, common case of a file genuinely living under
+// public/ - Vite's own dev server watches and serves publicDir straight
+// off disk per-request with no copy step involved at all today; a byte
+// copy taken once at startup wouldn't pick up a live edit to that file
+// without a full dev-server restart.
+//
+// Instead, this is a small Astro integration with two hooks, each
+// resolving fresh rather than relying on any one-shot copy:
+// - astro:server:setup (dev): adds Vite dev-server middleware that
+//   intercepts any request whose extension looks like a static asset
+//   (looksLikeAssetPath() below - images/fonts, the same set
+//   MIME_BY_EXTENSION already knows how to serve) and - only if it
+//   doesn't already exist under public/ (that stays Vite's own job,
+//   unshadowed) - streams it straight from wherever it lives in the
+//   project. Not scoped to writedocs.json's own configured fields specifically
+//   (an earlier version of this file was) - a page's own MDX can
+//   reference an image path this integration has no way to know about
+//   ahead of time short of parsing every page's content on every
+//   request, so instead of trying to enumerate what *should* be
+//   reachable, it just resolves whatever *is* actually requested,
+//   directly, the same way Vite's own publicDir serving already does.
+// - astro:build:done: a one-time pass after Astro's own build finishes.
+//   First, the same writedocs.json-field-driven copy as before (still needed
+//   as its own pass - background images/font sources render into CSS
+//   `url(...)` inside a `<style>` block, and seo.ogImage into a `<meta
+//   content="...">` tag, neither of which the second pass below would
+//   ever see). Second, copyReferencedContentAssets() below scans every
+//   built .html page for `src="/..."` references (an `<img>`, mainly -
+//   see its own comment) not already present in the output, and resolves
+//   + copies each the same way - this is what actually covers a plain
+//   content image, since there's no fixed field name to read it from up
+//   front the way there is for writedocs.json's own fields. A real static
+//   build has no "later" for a live-reload concern to apply to, so a
+//   single pass of each here is sufficient.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadDocsConfig, collectConfiguredAssetPaths } from './config.ts';
+
+const MIME_BY_EXTENSION = {
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+};
+
+function mimeFor(filePath) {
+  return MIME_BY_EXTENSION[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
+}
+
+/** Resolves a root-relative `urlPath` (e.g. "/images/hero.svg") against
+ *  `contentDir` directly - not `<contentDir>/public` - the fallback
+ *  location for one of the styles/footer/seo asset fields
+ *  (collectConfiguredAssetPaths()) when it isn't sitting under public/.
+ *  Segment-by-segment path-traversal guard (no
+ *  `..`/`.` segments) since `urlPath` ultimately comes from an incoming
+ *  request URL in the dev-server case, not just trusted writedocs.json
+ *  content. Returns an absolute path, or null if nothing real is there. */
+function resolveOutsidePublic(urlPath, contentDir) {
+  const segments = urlPath.replace(/^\/+/, '').split('/');
+  if (segments.some((segment) => segment === '..' || segment === '.' || segment === '')) return null;
+  const absolute = path.join(contentDir, ...segments);
+  try {
+    return fs.statSync(absolute).isFile() ? absolute : null;
+  } catch {
+    return null;
+  }
+}
+
+function publicPathFor(urlPath, contentDir) {
+  const segments = urlPath.replace(/^\/+/, '').split('/');
+  return path.join(contentDir, 'public', ...segments);
+}
+
+/** Root-relative, recognized-extension paths only - the same "does this
+ *  look like a static asset at all" question mimeFor()'s own map already
+ *  answers, reused here as the dev-middleware/build-scan gate instead of
+ *  a fixed list of writedocs.json field names. Deliberately permissive: a page
+ *  or config field asking for a path this returns true for gets a real
+ *  attempt to resolve it from anywhere in the project; anything else
+ *  (an actual API route, a `.html` page request, ...) is left alone,
+ *  same as before this existed. */
+function looksLikeAssetPath(urlPath) {
+  return Object.prototype.hasOwnProperty.call(MIME_BY_EXTENSION, path.extname(urlPath).toLowerCase());
+}
+
+/** Recursively lists every `.html` file under `dir`. Astro's own build
+ *  output is already a flat-ish tree of one .html per route, so this is
+ *  just a plain walk - no globbing dependency needed for something this
+ *  small. */
+function listHtmlFiles(dir) {
+  return listFilesWithExtension(dir, '.html');
+}
+
+// Generalização de listHtmlFiles, usada também para achar os .css do build.
+function listFilesWithExtension(dir, extension) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...listFilesWithExtension(full, extension));
+    } else if (entry.isFile() && entry.name.endsWith(extension)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/** Scans every built page for root-relative, recognized-extension `src="/..."`
+ *  references (`<img src="...">`, mainly - what `Image.astro`, `Frame.astro`,
+ *  and a raw `![]()`/`<img>` in MDX all ultimately render down to; a
+ *  `srcset="..."` attribute is checked too, since it's the same kind of
+ *  reference and costs nothing extra to also cover) that aren't already
+ *  present in the build output, and copies each one in from wherever it
+ *  resolves in the project via resolveOutsidePublic() - the same
+ *  fallback the dev middleware below already uses, just applied once,
+ *  after the fact, to the rendered HTML instead of to live requests.
+ *  This is what actually covers a plain content-body image: unlike a
+ *  writedocs.json field, there's no fixed set of field names to read a
+ *  content image's path from ahead of time, so instead this reads
+ *  whatever `src` a page's own rendered markup ends up containing. */
+function copyReferencedContentAssets(outDir, contentDir) {
+  const attrPattern = /\b(?:src|srcset)="([^"]+)"/g;
+  for (const htmlFile of listHtmlFiles(outDir)) {
+    const html = fs.readFileSync(htmlFile, 'utf8');
+    let match;
+    while ((match = attrPattern.exec(html))) {
+      // srcset can hold a comma-separated list of "url descriptor" pairs -
+      // split it out; a plain src is already just the one URL.
+      const candidates = match[1].split(',').map((part) => part.trim().split(/\s+/)[0]).filter(Boolean);
+      for (const urlPath of candidates) copyAssetIfMissing(urlPath, outDir, contentDir);
+    }
+    // Referências em CSS dentro do próprio HTML: um bloco <style> escrito
+    // na página (o `<style>` de uma página `mode: custom`, por exemplo) ou
+    // um atributo style="...". Sem isto, uma imagem usada só como
+    // background-image nunca era copiada para o build e dava 404 em
+    // produção, embora funcionasse no dev (onde o middleware resolve
+    // qualquer caminho direto do disco).
+    for (const urlPath of cssUrlReferences(html)) copyAssetIfMissing(urlPath, outDir, contentDir);
+  }
+  // O mesmo para as folhas de estilo que o build gera (_astro/*.css): é
+  // para onde vai o .css solto na raiz do projeto, carregado automaticamente.
+  for (const cssFile of listFilesWithExtension(outDir, '.css')) {
+    for (const urlPath of cssUrlReferences(fs.readFileSync(cssFile, 'utf8'))) {
+      copyAssetIfMissing(urlPath, outDir, contentDir);
+    }
+  }
+}
+
+/** Every `url(...)` target in a chunk of CSS (or HTML containing CSS),
+ *  quoted or not. Query strings and fragments (`font.woff2?v=2`,
+ *  `icons.svg#home`) are dropped - the file on disk has neither. */
+function cssUrlReferences(text) {
+  const urls = [];
+  const urlPattern = /url\(\s*(['"]?)([^'")]+?)\1\s*\)/g;
+  let match;
+  while ((match = urlPattern.exec(text))) urls.push(match[2].trim().split(/[?#]/)[0]);
+  return urls;
+}
+
+/** Copies one root-relative asset reference into the build output from
+ *  wherever it lives in the project, unless it's already there. */
+function copyAssetIfMissing(urlPath, outDir, contentDir) {
+  if (!urlPath.startsWith('/') || urlPath.startsWith('//')) return; // only root-relative - not external, not protocol-relative
+  if (!looksLikeAssetPath(urlPath)) return;
+  const segments = urlPath.replace(/^\/+/, '').split('/');
+  const outPath = path.join(outDir, ...segments);
+  if (fs.existsSync(outPath)) return; // already present - via public/'s passthrough copy, or an earlier reference to the same file
+  const resolved = resolveOutsidePublic(urlPath, contentDir);
+  if (!resolved) return; // doesn't resolve to a real file anywhere in the project either - leave the broken reference as-is
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.copyFileSync(resolved, outPath);
+}
+
+export function stylesAssetFallback(contentDir) {
+  return {
+    name: 'writedocs-styles-asset-fallback',
+    hooks: {
+      'astro:server:setup': ({ server }) => {
+        server.middlewares.use((req, res, next) => {
+          if (!req.url) return next();
+          const urlPath = req.url.split('?')[0];
+          if (!looksLikeAssetPath(urlPath)) return next();
+          if (fs.existsSync(publicPathFor(urlPath, contentDir))) return next(); // real public/ file - Vite's own static serving already handles it, don't shadow
+          const resolved = resolveOutsidePublic(urlPath, contentDir);
+          if (!resolved) return next();
+          res.setHeader('Content-Type', mimeFor(resolved));
+          fs.createReadStream(resolved).pipe(res);
+        });
+      },
+      'astro:build:done': async ({ dir }) => {
+        const outDir = fileURLToPath(dir);
+        const config = loadDocsConfig(contentDir);
+        // Pass 1: writedocs.json's own configured fields. Kept as its own,
+        // field-name-driven pass rather than folded into pass 2 below -
+        // seo.ogImage renders into a `<meta content="...">` tag, which
+        // pass 2 never scans. (Pass 2 agora também lê `url(...)` em CSS,
+        // então background images/fontes seriam pegas pelas duas; manter
+        // o pass 1 explícito não custa nada.)
+        for (const urlPath of collectConfiguredAssetPaths(config)) {
+          const segments = urlPath.replace(/^\/+/, '').split('/');
+          const outPath = path.join(outDir, ...segments);
+          if (fs.existsSync(outPath)) continue; // already present via public/'s normal passthrough copy
+          const resolved = resolveOutsidePublic(urlPath, contentDir);
+          if (!resolved) continue; // not configured to a real file anywhere - same as today, just renders a broken <link>/<img>
+          fs.mkdirSync(path.dirname(outPath), { recursive: true });
+          fs.copyFileSync(resolved, outPath);
+        }
+        // Pass 2: arbitrary content-body assets - anything a page's own
+        // rendered HTML references by src/srcset that pass 1 didn't
+        // already account for.
+        copyReferencedContentAssets(outDir, contentDir);
+      },
+    },
+  };
+}