@wizzlethorpe/vaults 0.13.2 → 0.14.0

package/dist/build.js

@@ -1,17 +1,21 @@
 import { copyFile, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
-import { relative } from "node:path";
 import { dirname, join } from "node:path";
 import { availableParallelism } from "node:os";
 import picomatch from "picomatch";
 import { scanVault } from "./scan.js";
+import { htmlEscape } from "./escape.js";
+import { collectDataJsonVaultRefs, copyReferencedImages, copyReferencedPassthroughs, } from "./asset-refs.js";
+import { downloadFilePaths } from "./render/handlers/builtin/download.js";
+import { foundryManifestPaths, manifestDownloadPath } from "./render/handlers/builtin/foundry-manifest.js";
+import { buildManifest } from "./manifest.js";
+import { collectBodyMeta, warnFoundryDocCollisions } from "./foundry-meta.js";
 import { compressImage } from "./images.js";
-import { IMAGE_EXT_RE, PASSTHROUGH_EXT_RE, COMPRESSIBLE_EXT_RE, contentTypeForExt, } from "./render/extensions.js";
+import { IMAGE_EXT_RE, PASSTHROUGH_EXT_RE, COMPRESSIBLE_EXT_RE, } from "./render/extensions.js";
 import { buildFavicon } from "./favicon.js";
 import { renderMarkdown } from "./render/pipeline.js";
 import { extractH1 } from "./render/frontmatter.js";
-import { CLI_VERSION, MANIFEST_VERSION, ID_SCHEME } from "./version.js";
 import { renderLayout, render404 } from "./render/layout.js";
 import { writeFoundryImporter } from "./foundry-importer.js";
 import { slugify } from "./render/slug.js";
@@ -21,12 +25,11 @@ import { DEFAULT_CSS, renderThemeOverride } from "./render/styles.js";
 import { loadObsidianSnippets } from "./obsidian.js";
 import { loadSettings, writeSettings, SETTINGS_FILE } from "./settings.js";
 import { loadConfig } from "./config.js";
+import { applyFrontmatterDefaults, compileFrontmatterRules } from "./frontmatter-defaults.js";
 import matter from "gray-matter";
-import { renderAuthMiddleware, LOGIN_HTML } from "./render/auth-template.js";
-import { htmlAttr } from "./escape.js";
+import { renderAuthMiddleware, renderLoginPage } from "./render/auth-template.js";
 import { renderFooterHtml } from "./render/footer.js";
 import { buildRegistry } from "./render/handlers/types.js";
-import { battlemapLayerPaths } from "./render/handlers/builtin/battlemap.js";
 import { loadUserHandlers } from "./render/handlers/loader.js";
 import { BUILTIN_HANDLERS } from "./render/handlers/builtin/index.js";
 import { bundleHandlerAssets } from "./render/handlers/assets.js";
@@ -49,26 +52,110 @@ import { formatDuration, pMap, Progress } from "./util.js";
  * Single-role builds (the default `public`-only case) collapse
  * `_variants/public/...` up to the root.
  */
-export async function buildSite(opts) {
+/**
+ * Add basename-slug keys to an asset index, first-write-wins in the vault's
+ * sorted path order.
+ *
+ * Obsidian resolves `![[map.png]]` by basename, so two files with the same
+ * name in different folders compete for one key. Writing the key from inside
+ * the concurrent staging pass meant whichever finished second won, and that
+ * varied between builds on identical input — a page could silently get a
+ * different image run to run. Doing it here, sequentially over the sorted
+ * list, makes the winner deterministic and lets us say which files collided.
+ * (Full-path keys stay in the staging pass; those are unique by definition.)
+ */
+function addBasenameKeys(index, files, label) {
+    const claimed = new Map(); // slug → winning source path
+    for (const f of files) {
+        const entry = index.get(f.path);
+        if (!entry)
+            continue; // staging failed for this file; nothing to point at
+        const slug = slugify(f.path.split("/").pop());
+        const winner = claimed.get(slug);
+        if (winner === undefined) {
+            claimed.set(slug, f.path);
+            index.set(slug, entry);
+            continue;
+        }
+        console.warn(`  ${label} name collision: '${f.path}' and '${winner}' share a filename. `
+            + `Bare references like the basename resolve to '${winner}'; `
+            + `use the folder path to reach the other.`);
+    }
+}
+/**
+ * Emit `sitemap.xml` and `robots.txt` at the deploy root.
+ *
+ * **Only the default role's pages are listed.** A sitemap naming gated pages
+ * would advertise that they exist, and their URLs, to anyone who fetches it —
+ * the middleware would still refuse the content, but the leak is the point of
+ * a sitemap, so it must never see above the lowest tier.
+ *
+ * Both files are written only when `site_url` is set, because a sitemap needs
+ * absolute URLs and nothing else in the build knows the deploy's public
+ * hostname (a Pages project can answer on several).
+ */
+async function writeSitemap(outputDir, siteUrl, pagePaths) {
+    const base = siteUrl.replace(/\/+$/, "");
+    const urls = pagePaths
+        .map((p) => p.replace(/\.md$/i, ""))
+        .map((p) => (p === "index" ? "" : p.replace(/\/index$/i, "")))
+        .sort()
+        .map((p) => `${base}/${p.split("/").map(encodeURIComponent).join("/")}`)
+        // index.md becomes the bare base URL rather than "<base>/".
+        .map((u) => u.replace(/\/$/, ""));
+    const body = [...new Set(urls)]
+        .map((u) => `  <url><loc>${htmlEscape(u)}</loc></url>`)
+        .join("\n");
+    await writeFile(join(outputDir, "sitemap.xml"), `<?xml version="1.0" encoding="UTF-8"?>\n`
+        + `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${body}\n</urlset>\n`);
+    await writeFile(join(outputDir, "robots.txt"), `User-agent: *\nAllow: /\nSitemap: ${base}/sitemap.xml\n`);
+}
+/**
+ * Warn about a `default_frontmatter` rule assigning a role the vault has not
+ * configured.
+ *
+ * `default_role` validated itself and said so when it was wrong. Moving the
+ * job into a rule would have dropped that: a typo would silently supply a role
+ * nothing recognises, and every page it matched would fall back to the lowest
+ * tier — publishing a vault meant to be private, quietly.
+ */
+function warnUnknownRoles(rules, known, roles) {
+    for (const rule of rules) {
+        const role = rule.data?.["role"];
+        if (typeof role === "string" && role && !known.has(role)) {
+            console.warn(`  settings.md: default_frontmatter rule '${rule.match}' assigns role `
+                + `"${role}", which is not one of [${roles.join(", ")}]. Pages matching it `
+                + `fall back to "${roles[0]}".`);
+        }
+    }
+}
+export async function buildSite(input) {
     const start = Date.now();
     const concurrency = Math.max(2, availableParallelism());
     // Run any pending schema / layout migrations before reading anything
     // else. The framework is idempotent: already-migrated vaults pay only
     // the cost of a few stat() calls. See cli/src/migrate/.
-    await runMigrations(opts.vaultPath);
+    await runMigrations(input.vaultPath);
     // ── Settings (user-editable) ─────────────────────────────────────────────
-    const settings = await loadSettings(opts.vaultPath);
+    const settings = await loadSettings(input.vaultPath);
     for (const w of settings.warnings)
         console.warn(`  ${w}`);
     if (settings.exists && settings.changed) {
-        await writeSettings(opts.vaultPath, settings.values);
+        await writeSettings(input.vaultPath, settings.values);
         console.log(`  rewrote ${SETTINGS_FILE} to canonical format`);
     }
-    opts = {
-        ...opts,
-        vaultName: opts.vaultName === "Vault" ? settings.values.vault_name : opts.vaultName,
-        imageQuality: opts.imageQuality === 85 ? settings.values.image_quality : opts.imageQuality,
-        maxFileBytes: opts.maxFileBytes === 25 * 1024 * 1024 ? settings.values.max_file_bytes : opts.maxFileBytes,
+    // settings.md is the single source of truth for vault properties (see the
+    // SCHEMA in settings.ts). These used to also be CLI flags, with "was the
+    // flag passed?" inferred by comparing against the flag's default — and the
+    // defaults matched the schema's, so `build -q 85` against an
+    // `image_quality: 40` vault silently produced 40. The flags are gone; the
+    // vault decides.
+    let opts = {
+        ...input,
+        siteUrl: settings.values.site_url,
+        vaultName: settings.values.vault_name,
+        imageQuality: settings.values.image_quality,
+        maxFileBytes: settings.values.max_file_bytes,
     };
     // ── Custom handlers ──────────────────────────────────────────────────────
     // Built-ins ship with the CLI; user handlers live in `.vaults/handlers/`
@@ -94,20 +181,13 @@ export async function buildSite(opts) {
     const cfg = await loadConfig(opts.vaultPath, {});
     const roles = cfg.roles.length > 0 ? cfg.roles : ["public"];
     const allRoleSet = new Set(roles);
-    // Pages without a 'role:' frontmatter fall back to settings.default_role
-    // when set (and valid); otherwise the lowest-tier role. This lets a
-    // DM-by-default vault flip the polarity instead of tagging every private
-    // page individually.
-    let defaultRole = roles[0];
-    if (settings.values.default_role) {
-        if (allRoleSet.has(settings.values.default_role)) {
-            defaultRole = settings.values.default_role;
-        }
-        else {
-            console.warn(`  settings.md: default_role "${settings.values.default_role}" `
-                + `not in configured roles [${roles.join(", ")}], using "${defaultRole}"`);
-        }
-    }
+    // A page's role comes from its frontmatter, and `default_frontmatter` is
+    // what supplies one to pages that state none — a DM-by-default vault sets
+    // `role: dm` in a rule matching `**`. This is the floor for anything that
+    // reaches here without a role at all, which means a vault whose rules do not
+    // cover it.
+    const defaultRole = roles[0];
+    warnUnknownRoles(settings.values.default_frontmatter, allRoleSet, roles);
     // ── Scan + filter ────────────────────────────────────────────────────────
     console.log(`Scanning ${opts.vaultPath}...`);
     const scanStart = Date.now();
@@ -151,9 +231,45 @@ export async function buildSite(opts) {
     // the passthrough pool (still reference-gated). The user-facing
     // warning lists exactly which paths got dropped so unintentional
     // omissions surface immediately.
+    // Read the ```download blocks first: a file named by one is shipped whatever
+    // its extension, so it must not also be reported as skipped. Warning about a
+    // file that then gets staged sends the reader off to set
+    // include_unknown_files for no reason.
+    const downloadPaths = new Set();
+    const manifestPaths = new Set();
+    const manifestDownloads = new Map();
+    for (const f of markdownFiles) {
+        const source = await readFile(f.absolute, "utf8");
+        for (const path of downloadFilePaths(source))
+            downloadPaths.add(path);
+        for (const path of foundryManifestPaths(source))
+            manifestPaths.add(path);
+    }
+    // A foundry-manifest block names only the manifest. The zip is whatever the
+    // manifest's own download field says, so read it and ship that too — the
+    // author should not have to repeat a path the manifest already states, and
+    // an install needs both halves present or it fails on the second fetch.
+    for (const rel of manifestPaths) {
+        downloadPaths.add(rel);
+        const file = withinLimit.find((f) => f.path === rel);
+        if (!file)
+            continue;
+        const { path, absolute } = manifestDownloadPath(await readFile(file.absolute, "utf8"), settings.values.site_url);
+        if (absolute) {
+            console.warn(`  ${rel}: "download" points outside this vault (${absolute}), so the file is not`
+                + ` staged into the deploy. If it is meant to be this vault's own file, either`
+                + ` set 'site_url' to the host it names or write the path relative and let the`
+                + ` build make it absolute.`);
+        }
+        if (path) {
+            downloadPaths.add(path);
+            manifestDownloads.set(rel, path);
+        }
+    }
     const unknownFiles = withinLimit.filter((f) => !/\.md$|\.base$/i.test(f.path)
         && !IMAGE_EXT_RE.test(f.path)
-        && !PASSTHROUGH_EXT_RE.test(f.path));
+        && !PASSTHROUGH_EXT_RE.test(f.path)
+        && !downloadPaths.has(f.path));
     const includeUnknown = settings.values.include_unknown_files;
     if (unknownFiles.length > 0) {
         if (includeUnknown) {
@@ -173,7 +289,26 @@ export async function buildSite(opts) {
     // Effective passthrough list: recognised media plus (optionally) unknowns.
     const stagedPassthroughs = includeUnknown
         ? [...passthroughFiles, ...unknownFiles]
-        : passthroughFiles;
+        : [...passthroughFiles];
+    // Files named by a ```download block join the pool whatever their
+    // extension. A download is usually a .zip or a module.json, which the
+    // passthrough list calls unknown and drops — but naming one in a block is
+    // the author asking for it by name, which is exactly the intent
+    // include_unknown_files exists to require. Role gating is untouched: these
+    // are still reference-gated, so a download on a patron page reaches the
+    // patron variant and no other.
+    if (downloadPaths.size > 0) {
+        const already = new Set(stagedPassthroughs.map((f) => f.path));
+        const promoted = withinLimit.filter((f) => downloadPaths.has(f.path) && !already.has(f.path));
+        const missing = [...downloadPaths].filter((p) => !withinLimit.some((f) => f.path === p));
+        for (const p of missing) {
+            console.warn(`  download block names '${p}', which is not in the vault; the link will 404.`);
+        }
+        if (promoted.length > 0) {
+            console.log(`  staging ${promoted.length} file(s) named by download / foundry-manifest blocks`);
+            stagedPassthroughs.push(...promoted);
+        }
+    }
     // ── Shared content (read once, reused across roles) ─────────────────────
     const sources = new Map();
     await pMap(markdownFiles, concurrency, async (f) => {
@@ -191,9 +326,17 @@ export async function buildSite(opts) {
     // normalized for Obsidian quirks first; malformed YAML throws inside
     // parsePageFrontmatter and aborts the build rather than silently dropping a
     // page's metadata (and, with it, its role gate).
+    const frontmatterRules = compileFrontmatterRules(settings.values.default_frontmatter);
     const parsedSources = new Map();
     for (const f of markdownFiles) {
-        parsedSources.set(f.path, parsePageFrontmatter(sources.get(f.path), f.path));
+        const parsed = parsePageFrontmatter(sources.get(f.path), f.path);
+        // Applied here, at the one place a page's frontmatter is read, so that
+        // roles, the rendered wiki, the manifest the Foundry client syncs from and
+        // the module compiler all see the same page. A default that only some of
+        // them honoured would be a way for a synced vault and an installed module
+        // to disagree about the same file.
+        applyFrontmatterDefaults(f.path, parsed.data, frontmatterRules);
+        parsedSources.set(f.path, parsed);
     }
     // Derive role/title/aliases per page from that parse. A role that's present
     // but isn't a configured role fails the build (collected below): falling back
@@ -265,12 +408,13 @@ export async function buildSite(opts) {
             // key is what stops identically-named assets in different scene folders
             // (e.g. a shared `Water Fountain (Loop).ogg`) from colliding under one
             // basename slug and staging only one of them.
-            const entry = { sourcePath: f.path, outputPath: compressed.outputPath };
-            imageIndex.set(slugify(f.path.split("/").pop()), entry);
-            imageIndex.set(f.path, entry);
+            // Full-path key only; basename keys are added afterwards, in sorted
+            // order, so a duplicated filename resolves deterministically.
+            imageIndex.set(f.path, { sourcePath: f.path, outputPath: compressed.outputPath });
         }, (done, total) => progress.update(done, total));
         progress.done(`${imageFiles.length} processed (${cacheHits} cached, ${imageFiles.length - cacheHits} compressed)`);
     }
+    addBasenameKeys(imageIndex, imageFiles, "image");
     // ── Passthrough files (audio, video, PDF, epub) ────────────────────────
     // Staged once and copied into a variant only when a visible page in that
     // variant references the file by basename or relative path. Same gating
@@ -288,12 +432,11 @@ export async function buildSite(opts) {
             // Dual-keyed like imageIndex: basename slug for body refs, full
             // vault-relative path for `@vault/PATH` refs (ambient sounds in
             // data_json), so same-named files in different folders don't collide.
-            const entry = { sourcePath: f.path, outputPath: f.path };
-            passthroughIndex.set(slugify(f.path.split("/").pop()), entry);
-            passthroughIndex.set(f.path, entry);
+            passthroughIndex.set(f.path, { sourcePath: f.path, outputPath: f.path });
         }, (done, total) => progress.update(done, total));
         progress.done(`${stagedPassthroughs.length} staged`);
     }
+    addBasenameKeys(passthroughIndex, stagedPassthroughs, "passthrough");
     // Shared CSS bundle.
     //
     // Every file written to outputDir ROOT (rather than into _variants/<role>/)
@@ -325,15 +468,18 @@ export async function buildSite(opts) {
     // One combined hash keeps it simple; any shared-asset change busts all.
     // katex version rides in the hash so a dependency upgrade re-fetches the
     // (otherwise never-changing) /katex/katex.min.css on math pages.
-    const katexVersion = createRequire(import.meta.url)("katex/package.json").version;
+    const katexVersion = katexRequire()("katex/package.json").version;
     const assetVersion = createHash("md5")
         .update(DEFAULT_CSS + themeOverride + userCss + handlerAssets.js + handlerAssets.css + katexVersion)
         .digest("hex")
         .slice(0, 10);
     // Foundry importer bundle: one ESM file the Foundry module fetches at
-    // sync time, plus a tiny version manifest with the SHA-256 the host
-    // verifies against its trust cache.
-    await writeFoundryImporter(opts.outputDir);
+    // sync time. Skipped entirely when the vault has opted out of the Foundry
+    // integration — it is ~60KB shipped to every deploy, and a course site or
+    // research wiki will never fetch it.
+    const foundryEnabled = settings.values.foundry.package !== "none";
+    if (foundryEnabled)
+        await writeFoundryImporter(opts.outputDir);
     // Foundry-import bundles are written per-variant inside the role loop
     // below (instead of at the root) so the middleware role-gates them. A
     // public visitor can't fetch the dm-tier handler bundle even if it
@@ -379,9 +525,11 @@ export async function buildSite(opts) {
         if (cover)
             meta.coverImage = cover;
     }
+    warnFoundryDocCollisions(allPageMetas);
     // ── Per-role variant builds ─────────────────────────────────────────────
     const perRolePageCount = {};
     const collapseToRoot = roles.length === 1;
+    let defaultRolePagePaths = [];
     let katexCopied = false;
     for (const role of roles) {
         const variantDir = collapseToRoot
@@ -400,6 +548,7 @@ export async function buildSite(opts) {
             role,
             visibleRoles,
             redactRoles,
+            gated: !collapseToRoot,
             variantDir,
             vaultName: opts.vaultName,
             vaultPath: opts.vaultPath,
@@ -408,6 +557,7 @@ export async function buildSite(opts) {
             parsedSources,
             baseSources,
             imageIndex,
+            manifestDownloads,
             imageStagingDir,
             passthroughIndex,
             passthroughStagingDir: otherStagingDir,
@@ -422,6 +572,9 @@ export async function buildSite(opts) {
             allWarnings: opts.allWarnings,
         });
         perRolePageCount[role] = stats.pageCount;
+        // Only the default (lowest) role feeds the sitemap; see writeSitemap.
+        if (role === roles[0])
+            defaultRolePagePaths = stats.pagePaths;
         if (!collapseToRoot)
             console.log(`  variant '${role}': ${stats.pageCount} pages`);
         // KaTeX stylesheet + fonts, shared at the deploy root. Copied lazily on
@@ -441,7 +594,7 @@ export async function buildSite(opts) {
         // Foundry-import subset bundles. The Foundry module fetches these by
         // their canonical `/_handlers.foundry.{js,css}` paths; the middleware
         // role-gates per the requesting bearer's variant.
-        if (handlerAssets.foundry) {
+        if (foundryEnabled && handlerAssets.foundry) {
             if (handlerAssets.foundry.js.length > 0) {
                 await writeFile(join(variantDir, "_handlers.foundry.js"), handlerAssets.foundry.js);
             }
@@ -457,9 +610,9 @@ export async function buildSite(opts) {
         const manifest = await buildManifest(opts.outputDir, variantDir, stats.bodyMeta, !collapseToRoot, roles, opts.vaultName, {
             hasHandlerJs,
             hasHandlerCss,
-            hasFoundryJs: (handlerAssets.foundry?.js.length ?? 0) > 0,
-            hasFoundryCss: (handlerAssets.foundry?.css.length ?? 0) > 0,
-        });
+            hasFoundryJs: foundryEnabled && (handlerAssets.foundry?.js.length ?? 0) > 0,
+            hasFoundryCss: foundryEnabled && (handlerAssets.foundry?.css.length ?? 0) > 0,
+        }, settings.values.foundry.package, allRoleSet.has(settings.values.foundry.player_role) ? settings.values.foundry.player_role : "");
         await writeFile(join(variantDir, "_manifest.json"), JSON.stringify(manifest));
     }
     // ── Pages Functions ─────────────────────────────────────────────────────
@@ -496,30 +649,40 @@ export async function buildSite(opts) {
             : null;
         const middleware = renderAuthMiddleware({
             roles,
+            foundry: foundryEnabled,
             rolePasswords: cfg.rolePasswords,
             ...(patreonForFn ? { patreon: patreonForFn } : {}),
             ...(oidcForFn ? { oidc: oidcForFn } : {}),
         });
         await writeFile(join(fnDir, "_middleware.js"), middleware);
-        // Login page; drop in the role list (everything above the default).
+        // Login page, showing only the methods this deploy actually has. A role
+        // is reachable by password only if a hash was set for it, so a vault
+        // authenticating purely through Patreon or OIDC gets no password form
+        // and no role selector.
         const protectedRoles = roles.slice(1);
-        const opts_html = protectedRoles
-            .map((r) => `<option value="${r}">${r}</option>`)
-            .join("");
-        const patreonRolesAttr = patreonForFn
-            ? ` data-patreon-roles="${Object.keys(patreonForFn.tiers).join(",")}"`
-            : "";
-        // displayName is free text (unlike role names), so attribute-escape it.
-        const oidcAttr = oidcForFn ? ` data-oidc="${htmlAttr(oidcForFn.displayName)}"` : "";
-        await writeFile(join(opts.outputDir, "login.html"), LOGIN_HTML
-            .replace("__ROLE_OPTIONS__", opts_html)
-            .replace("__PATREON_ROLES_ATTR__", patreonRolesAttr)
-            .replace("__OIDC_ATTR__", oidcAttr));
-        const missing = protectedRoles.filter((r) => !cfg.rolePasswords[r]);
-        if (missing.length > 0) {
-            console.warn(`  WARNING: no password set for role(s): ${missing.join(", ")}. Run 'vaults password <role>' before pushing.`);
+        const passwordRoles = protectedRoles.filter((r) => cfg.rolePasswords[r]);
+        const patreonRoles = patreonForFn ? Object.keys(patreonForFn.tiers) : [];
+        const oidcRoles = oidcForFn ? Object.keys(oidcForFn.roleRules ?? {}) : [];
+        await writeFile(join(opts.outputDir, "login.html"), renderLoginPage({
+            passwordRoles,
+            patreonRoles,
+            oidcDisplayName: oidcForFn ? oidcForFn.displayName : null,
+        }));
+        // The error is a role nobody can reach, not a role without a password —
+        // password-less is the point when a provider grants the role instead.
+        const unreachable = protectedRoles.filter((r) => !cfg.rolePasswords[r] && !patreonRoles.includes(r) && !oidcRoles.includes(r));
+        if (unreachable.length > 0) {
+            console.warn(`  WARNING: no way to sign in as role(s): ${unreachable.join(", ")}. `
+                + `Set a password ('vaults password <role>'), map a Patreon tier `
+                + `('vaults patreon link <role> <tier-id>'), or add an OIDC rule `
+                + `('vaults oidc configure'). Pages at these roles will be unreachable.`);
         }
     }
+    // Search-engine files. Written from the default role's page list only, so a
+    // gated page is never named. Skipped entirely without a site_url.
+    if (opts.siteUrl) {
+        await writeSitemap(opts.outputDir, opts.siteUrl, defaultRolePagePaths);
+    }
     // Drop the staging dirs; their contents have been copied into each
     // variant that needs them, so they're no longer required for the deploy.
     await rm(imageStagingDir, { recursive: true, force: true });
@@ -532,8 +695,6 @@ export async function buildSite(opts) {
     await rename(workOutputDir, finalOutputDir);
     console.log(`Built in ${formatDuration(Date.now() - start)}.`);
     return {
-        files,
-        withinLimit,
         roles,
         perRolePageCount,
         imageCount: imageFiles.length,
@@ -596,6 +757,7 @@ async function buildVariant(a) {
         bases: a.baseSources,
         defaultImageWidth: a.settings.default_image_width,
         redactRoles: a.redactRoles,
+        gated: a.gated,
         handlers: a.handlerRegistry,
         outlinksByPath,
     };
@@ -728,16 +890,34 @@ async function buildVariant(a) {
     // contract as images: ship only into variants whose visible pages
     // reference the file. A DM-only audio cue can't ride along into the
     // public deploy because no public-tier source mentions it.
-    await copyReferencedPassthroughs(visibleSources, visibleMetas, a.passthroughIndex, a.passthroughStagingDir, a.variantDir);
-    return { pageCount: visibleMetas.length, bodyMeta, hasMath: hasMathCss };
+    await copyReferencedPassthroughs(visibleSources, visibleMetas, a.passthroughIndex, a.passthroughStagingDir, a.variantDir, a.manifestDownloads);
+    return {
+        pageCount: visibleMetas.length,
+        pagePaths: visibleMetas.map((m) => m.path),
+        bodyMeta,
+        hasMath: hasMathCss,
+    };
+}
+/**
+ * Resolve the katex package that *rehype-katex* renders with, which is not
+ * necessarily this package's own katex dependency: under pnpm's isolated
+ * node_modules, rehype-katex gets the copy matching its own range. The
+ * stylesheet has to come from that copy, because KaTeX renames its CSS
+ * classes between versions ('sizing' became 'katex-sizing' in 0.18), and a
+ * stylesheet from a different version silently stops matching the markup:
+ * subscripts render at full size instead of 0.7em.
+ */
+function katexRequire() {
+    const here = createRequire(import.meta.url);
+    return createRequire(here.resolve("rehype-katex"));
 }
 /**
- * Copy KaTeX's stylesheet and fonts (from the katex package dependency) to
+ * Copy KaTeX's stylesheet and fonts (from the katex rehype-katex uses) to
  * <outputDir>/katex/. woff2 only: the CSS lists woff2 first, so any browser
  * that supports it (all modern ones) never requests the woff/ttf fallbacks.
  */
 async function copyKatexAssets(destDir) {
-    const distDir = join(dirname(createRequire(import.meta.url).resolve("katex/package.json")), "dist");
+    const distDir = join(dirname(katexRequire().resolve("katex/package.json")), "dist");
     await mkdir(join(destDir, "fonts"), { recursive: true });
     await copyFile(join(distDir, "katex.min.css"), join(destDir, "katex.min.css"));
     for (const f of await readdir(join(distDir, "fonts"))) {
@@ -760,127 +940,6 @@ async function copyKatexAssets(destDir) {
  *     embed: false                          # default true
  *     data: { … deep-merged into the doc }
  */
-async function collectBodyMeta(p, vaultPath) {
-    const fm = p.frontmatter ?? {};
-    const out = { role: p.role };
-    const basename = p.path.split("/").pop().replace(/\.md$/i, "");
-    if (p.title && p.title !== basename)
-        out.title = p.title;
-    const fo = fm["foundry"];
-    if (fo && typeof fo === "object" && !Array.isArray(fo)) {
-        const block = {};
-        const base = fo["base"];
-        if (typeof base === "string" && base.trim().length > 0)
-            block.base = base.trim();
-        const embed = fo["embed"];
-        if (typeof embed === "boolean")
-            block.embed = embed;
-        // foundry.sync: false keeps the page out of Foundry altogether — no
-        // JournalEntryPage, no derived doc. The page still renders on the wiki.
-        // Unlike `embed`, which only suppresses the article inside a derived
-        // doc's description, this drops the page from the sync set entirely.
-        const sync = fo["sync"];
-        if (typeof sync === "boolean")
-            block.sync = sync;
-        // foundry.journal: false makes the derived doc without the JournalEntryPage
-        // that normally accompanies it. For a page that exists to carry a Scene or
-        // an Actor and has no article worth reading in the sidebar.
-        const journal = fo["journal"];
-        if (typeof journal === "boolean")
-            block.journal = journal;
-        // foundry.link: "doc" makes wikilinks to this page resolve to the document
-        // it instantiates rather than to its journal page. Implied by
-        // `journal: false`, where there is no journal page to link to.
-        const link = fo["link"];
-        if (link === "doc" || link === "journal")
-            block.link = link;
-        const data = fo["data"];
-        if (data && typeof data === "object" && !Array.isArray(data))
-            block.data = data;
-        // foundry.id: an explicit Foundry document id for this page. When set,
-        // overrides the SHA1-derived id used for both the JournalEntryPage and
-        // (if foundry.base is present) the instantiated derived doc. Lets users
-        // hardcode UUIDs that other Foundry-side code (macros, scene flags,
-        // module integrations) needs to reference. Foundry ids are 16 chars from
-        // [A-Za-z0-9]; a malformed value is dropped with a warning rather than
-        // failing the build.
-        const idVal = fo["id"];
-        if (typeof idVal === "string") {
-            const trimmed = idVal.trim();
-            if (FOUNDRY_ID_RE.test(trimmed))
-                block.id = trimmed;
-            else if (trimmed.length > 0) {
-                console.warn(`  ${p.path}: foundry.id "${trimmed}" is not a valid Foundry id (16 chars [A-Za-z0-9]); ignoring`);
-            }
-        }
-        // foundry.data_json: vault-relative path to a JSON file. Read + parse
-        // at build time and inline into the meta as `data_json`. The Foundry
-        // module deep-merges it onto the base doc BEFORE foundry.data, so a
-        // user can layer hand-tuned overrides on top of an exported sheet.
-        // Folding the parsed object into meta means the body-row hash already
-        // changes when the JSON content does — no separate change-detection.
-        const dataJsonPath = fo["data_json"];
-        if (typeof dataJsonPath === "string" && dataJsonPath.trim().length > 0) {
-            const parsed = await loadDataJson(vaultPath, dataJsonPath.trim(), p.path);
-            if (parsed !== null)
-                block.data_json = parsed;
-        }
-        if (Object.keys(block).length > 0)
-            out.foundry = block;
-    }
-    if (p.coverImage)
-        out.image = p.coverImage;
-    return out;
-}
-/** Read + parse a vault-relative JSON file referenced by `foundry.data_json`.
- *  Warns on missing / unparseable file and returns null so the page renders
- *  without the overlay rather than failing the build. */
-async function loadDataJson(vaultPath, relPath, pagePath) {
-    const abs = join(vaultPath, relPath);
-    try {
-        const raw = await readFile(abs, "utf8");
-        return JSON.parse(raw);
-    }
-    catch (err) {
-        const code = err.code;
-        if (code === "ENOENT") {
-            console.warn(`  ${pagePath}: foundry.data_json "${relPath}" not found, skipping`);
-        }
-        else {
-            console.warn(`  ${pagePath}: foundry.data_json "${relPath}" failed to parse: ${err.message}`);
-        }
-        return null;
-    }
-}
-/** Collect the `@vault/...` paths a page's foundry block references, from both
- *  `foundry.data_json` and `foundry.data`. A Scene's bulk asset refs
- *  (backgrounds, ambient sounds, tiles) live in that JSON content, and a token's
- *  ring subject lives in the inline `data` overlay; neither appears anywhere the
- *  per-variant asset scanners look, so without this they never ship and Foundry
- *  404s them. Returns vault-relative paths. */
-async function collectDataJsonVaultRefs(vaultPath, fm, pagePath) {
-    const fo = fm["foundry"];
-    if (!fo || typeof fo !== "object" || Array.isArray(fo))
-        return [];
-    const block = fo;
-    const out = [];
-    const collect = (from) => forEachString(from, (s) => {
-        const path = vaultRefPath(s);
-        if (path)
-            out.push(path);
-    });
-    const rel = block["data_json"];
-    if (typeof rel === "string" && rel.trim()) {
-        const parsed = await loadDataJson(vaultPath, rel.trim(), pagePath);
-        if (parsed !== null)
-            collect(parsed);
-    }
-    collect(block["data"]);
-    return out;
-}
-/** Foundry document ids: exactly 16 chars from [A-Za-z0-9]. Validated when
- *  authors set `foundry.id` to override the SHA1-derived default. */
-const FOUNDRY_ID_RE = /^[A-Za-z0-9]{16}$/;
 /** Coerce settings.theme to the layout's narrowed union, defaulting to
  *  "auto" for any unrecognised value rather than failing the build. */
 function themeOf(s) {
@@ -889,119 +948,6 @@ function themeOf(s) {
 function previewModeOf(s) {
     return s === "none" || s === "sticky" ? s : "normal";
 }
-const EMBED_RE = /!\[\[([^\[\]|#\n]+?)(?:\|[^\[\]#\n]*)?\]\]/g;
-// A ```gallery code block. Its body lists images by name (one per line,
-// optional `| caption`), which the gallery handler renders but the source
-// scanners would otherwise never see — so we read the block here to stage
-// the referenced images per variant, the same way `![[ ]]` embeds are staged.
-const GALLERY_BLOCK_RE = /^```gallery[^\n]*\n([\s\S]*?)^```/gm;
-/** Image basenames referenced inside a page's ```gallery blocks. */
-function galleryImageNames(source) {
-    const names = [];
-    for (const block of source.matchAll(GALLERY_BLOCK_RE)) {
-        for (const line of block[1].split("\n")) {
-            const trimmed = line.trim();
-            if (!trimmed || trimmed.startsWith("#"))
-                continue;
-            const name = (trimmed.split("|")[0] ?? "").trim();
-            if (name)
-                names.push(name);
-        }
-    }
-    return names;
-}
-async function copyReferencedImages(visibleSources, visibleMetas, imageIndex, stagingDir, variantDir) {
-    const refs = new Set();
-    for (const source of visibleSources.values()) {
-        for (const m of source.matchAll(EMBED_RE)) {
-            const name = m[1].trim();
-            if (!IMAGE_EXT_RE.test(name))
-                continue;
-            const image = imageIndex.get(slugify(name));
-            if (image)
-                refs.add(image.outputPath);
-        }
-        for (const name of galleryImageNames(source)) {
-            const image = imageIndex.get(slugify(name.split("/").pop()));
-            if (image)
-                refs.add(image.outputPath);
-        }
-        // Standard-Markdown image refs, `![alt](path/to/img.png)`. Without this
-        // only Obsidian `![[embed]]` syntax staged images, so CommonMark-syntax
-        // images rendered into HTML but 404'd on deploy. Mirrors the same MD_LINK_RE
-        // pass copyReferencedPassthroughs runs for `[label](file.pdf)` links.
-        for (const m of source.matchAll(MD_LINK_RE)) {
-            const name = m[1].trim();
-            if (/^(https?:|mailto:|#)/i.test(name))
-                continue;
-            if (!IMAGE_EXT_RE.test(name))
-                continue;
-            const image = imageIndex.get(slugify(name.split("/").pop()));
-            if (image)
-                refs.add(image.outputPath);
-        }
-        // Layers named inside ```battlemap blocks. A web-only layer (e.g. a
-        // composited tile overlay) has no other reference to stage it, so look
-        // it up by its full vault-relative path.
-        for (const path of battlemapLayerPaths(source)) {
-            const image = imageIndex.get(path);
-            if (image)
-                refs.add(image.outputPath);
-        }
-    }
-    // Pages can name their cover via `image:` frontmatter alone (no body embed);
-    // pull those in too. coverImage was resolved to the served URL upstream, so
-    // strip the leading slash + decode to get back to the staging-relative path.
-    // `@vault/PATH` references inside any frontmatter string field also gate
-    // an asset into this variant — common for Scene background.src / Playlist
-    // sound.path that point at vault-shipped media. Page-role gating still
-    // applies because we only walk visibleMetas (= pages this variant can see).
-    for (const p of visibleMetas) {
-        if (p.coverImage && !/^https?:\/\//i.test(p.coverImage)) {
-            try {
-                refs.add(decodeURIComponent(p.coverImage.replace(/^\//, "")));
-            }
-            catch { /* malformed coverImage URL — ignore */ }
-        }
-        if (p.frontmatter) {
-            forEachString(p.frontmatter, (s) => {
-                const path = vaultRefPath(s);
-                if (path && IMAGE_EXT_RE.test(path)) {
-                    const image = imageIndex.get(path);
-                    if (image)
-                        refs.add(image.outputPath);
-                }
-            });
-        }
-        // Image refs inside the page's foundry.data_json (Scene backgrounds, tiles).
-        for (const path of p.foundryAssets ?? []) {
-            if (!IMAGE_EXT_RE.test(path))
-                continue;
-            const image = imageIndex.get(path);
-            if (image)
-                refs.add(image.outputPath);
-        }
-    }
-    for (const outputPath of refs) {
-        const src = join(stagingDir, outputPath);
-        const dst = join(variantDir, outputPath);
-        await mkdir(dirname(dst), { recursive: true });
-        try {
-            await copyFile(src, dst);
-        }
-        catch (err) {
-            // Source may legitimately be missing if the file is in the index but
-            // wasn't compressed (e.g. quality=0 path). Surface but don't crash.
-            console.warn(`  warning: could not copy image ${outputPath}: ${err.message}`);
-        }
-    }
-}
-// `[label](path/to/file.ext)` style markdown link. Captures the URL part.
-// `\.[a-z0-9]+` requires an extension; we don't want to scoop up plain
-// internal page links (e.g. `(href)` without an extension).
-const MD_LINK_RE = /\[[^\]]*\]\(([^)\s]+\.[a-z0-9]+)(?:\s+["'][^"']*["'])?\)/gi;
-// `[[file.ext]]` and `![[file.ext]]` — Obsidian-flavoured wikilinks/embeds.
-const WIKI_LINK_RE = /!?\[\[([^\[\]|#\n]+\.[a-z0-9]+)(?:\|[^\[\]#\n]*)?(?:#[^\[\]\n]*)?\]\]/gi;
 // `> [!type]…` opens a callout; the rest of the contiguous blockquote (lines
 // starting with `>`, blank line ends) is its body. Used to strip role-gated
 // callouts from the source before any downstream pass sees it.
@@ -1041,98 +987,6 @@ function stripRoleGatedCallouts(source, redactRoles) {
     }
     return out.join("\n");
 }
-/**
- * Visit every string value reachable from `value` (object / array / scalar)
- * and call `fn` once per string. Used to surface `@vault/PATH` references
- * inside parsed frontmatter (e.g., a Scene's `foundry.data.background.src`
- * or a Playlist's `foundry.data.sounds[N].path`) so the per-variant asset
- * scanner can include those files alongside body-referenced ones.
- */
-function forEachString(value, fn) {
-    if (typeof value === "string")
-        return fn(value);
-    if (Array.isArray(value)) {
-        for (const v of value)
-            forEachString(v, fn);
-        return;
-    }
-    if (value && typeof value === "object") {
-        for (const v of Object.values(value))
-            forEachString(v, fn);
-    }
-}
-/** Extract a vault path from a `@vault/PATH` string, or null when the
- *  string isn't a vault reference. Trailing fragment / query stripped. */
-function vaultRefPath(s) {
-    if (!s.startsWith("@vault/"))
-        return null;
-    const rest = s.slice("@vault/".length).split("#")[0].split("?")[0];
-    return rest.length > 0 ? rest : null;
-}
-/**
- * Per-variant reference scan for passthrough files. A file lands in this
- * variant's deploy only if a visible page mentions it — same gating story
- * as images. Match patterns cover Obsidian embeds (`![[file.pdf]]`),
- * Obsidian wikilinks (`[[file.pdf]]`), and standard markdown links
- * (`[label](path/file.pdf)`). Anything not matched is dropped — that's
- * the whole point of the change; a stray DM-only audio cue stays in the
- * dm variant only.
- */
-async function copyReferencedPassthroughs(visibleSources, visibleMetas, passthroughIndex, stagingDir, variantDir) {
-    if (passthroughIndex.size === 0)
-        return;
-    const refs = new Set();
-    for (const source of visibleSources.values()) {
-        for (const m of source.matchAll(WIKI_LINK_RE)) {
-            const name = m[1].trim();
-            const entry = passthroughIndex.get(slugify(name.split("/").pop()));
-            if (entry)
-                refs.add(entry.outputPath);
-        }
-        for (const m of source.matchAll(MD_LINK_RE)) {
-            const name = m[1].trim();
-            // Skip http(s) links and anchor-only refs.
-            if (/^(https?:|mailto:|#)/i.test(name))
-                continue;
-            const entry = passthroughIndex.get(slugify(name.split("/").pop()));
-            if (entry)
-                refs.add(entry.outputPath);
-        }
-    }
-    // `@vault/PATH` references inside any frontmatter string also gate a
-    // passthrough into this variant. Same per-page-role visibility rules
-    // (only walking visibleMetas) — a dm-tier page's @vault/Audio/secret.ogg
-    // ships only to the dm variant.
-    for (const p of visibleMetas) {
-        if (!p.frontmatter)
-            continue;
-        forEachString(p.frontmatter, (s) => {
-            const path = vaultRefPath(s);
-            if (path) {
-                const entry = passthroughIndex.get(path);
-                if (entry)
-                    refs.add(entry.outputPath);
-            }
-        });
-        // Audio/video/pdf refs inside the page's foundry.data_json (ambient sounds).
-        for (const path of p.foundryAssets ?? []) {
-            const entry = passthroughIndex.get(path);
-            if (entry)
-                refs.add(entry.outputPath);
-        }
-    }
-    for (const outputPath of refs) {
-        const src = join(stagingDir, outputPath);
-        const dst = join(variantDir, outputPath);
-        await mkdir(dirname(dst), { recursive: true });
-        try {
-            await copyFile(src, dst);
-        }
-        catch (err) {
-            console.warn(`  warning: could not copy ${outputPath}: ${err.message}`);
-        }
-    }
-}
 /**
  * Build synthesised index.md for any folder (including the root) that has
  * pages but no existing index.md. When `inlineTitle` is true, the layout
@@ -1423,106 +1277,12 @@ function kindLabel(kind) {
         default: return kind;
     }
 }
-async function buildManifest(rootDir, variantDir, bodyMeta, authRequired, roles, vaultName, assets) {
-    const files = [];
-    const seen = new Set();
-    // Variant-specific files: use pathBase=variantDir so paths come out as
-    // "index.html", not "_variants/<role>/index.html". This matches the public
-    // URL the client uses; the auth middleware does the variant rewrite.
-    await walkAndIndex(variantDir, variantDir, files, seen, [], bodyMeta);
-    // Shared assets under the deploy root (attachments, css). Skip the variant
-    // tree itself and anything inside `functions/` (Function code isn't served).
-    if (rootDir !== variantDir) {
-        await walkAndIndex(rootDir, rootDir, files, seen, [
-            "_variants", "functions", ".image-staging", ".other-staging",
-        ], bodyMeta);
-    }
-    files.sort((a, b) => a.path.localeCompare(b.path));
-    // `auth.required` lets clients (Foundry, MCP) tell up-front whether the
-    // deploy has middleware. Single-role builds collapse to a pure-static
-    // deploy with no /_batch / /_connect endpoints — clients fall back to
-    // direct CDN GETs in that case. `auth.roles` ships the role order
-    // (lowest→highest) so clients can rank a page's tier against a chosen
-    // cutoff (e.g. Foundry's per-vault dmRole).
-    // `name` is the vault's display name (settings.md `vault_name`); clients
-    // like the Foundry module use it as the default label + root folder when
-    // a user adds the vault, so they get something readable instead of a
-    // host-derived slug.
-    // Asset advertisement so clients (Foundry, MCP) fetch the right paths
-    // instead of guessing well-known names — lets us move things later.
-    const assetBlock = {};
-    if (assets.hasHandlerJs || assets.hasHandlerCss) {
-        assetBlock.browser = {
-            ...(assets.hasHandlerJs ? { js: "/_handlers.js" } : {}),
-            ...(assets.hasHandlerCss ? { css: "/_handlers.css" } : {}),
-        };
-    }
-    if (assets.hasFoundryJs || assets.hasFoundryCss) {
-        assetBlock.foundry = {
-            ...(assets.hasFoundryJs ? { js: "/_handlers.foundry.js" } : {}),
-            ...(assets.hasFoundryCss ? { css: "/_handlers.foundry.css" } : {}),
-        };
-    }
-    return {
-        manifest_version: MANIFEST_VERSION,
-        cli_version: CLI_VERSION,
-        id_scheme: ID_SCHEME,
-        name: vaultName,
-        auth: { required: authRequired, roles },
-        ...(Object.keys(assetBlock).length > 0 ? { assets: assetBlock } : {}),
-        files,
-    };
-}
-async function walkAndIndex(dir, pathBase, out, seen, skipDirNames, bodyMeta) {
-    const entries = await readdir(dir, { withFileTypes: true });
-    for (const ent of entries) {
-        if (ent.name === "_manifest.json")
-            continue;
-        const abs = join(dir, ent.name);
-        if (ent.isDirectory()) {
-            if (skipDirNames.includes(ent.name))
-                continue;
-            await walkAndIndex(abs, pathBase, out, seen, skipDirNames, bodyMeta);
-            continue;
-        }
-        if (!ent.isFile())
-            continue;
-        const path = relative(pathBase, abs).split(/[/\\]/).join("/");
-        if (seen.has(path))
-            continue;
-        seen.add(path);
-        const body = await readFile(abs);
-        const info = await stat(abs);
-        const meta = bodyMeta.get(path);
-        // Fold meta JSON into the hash so meta-only edits (e.g. a foundry.base
-        // tweak with no body change) still bump the row hash and trigger sync.
-        const hasher = createHash("md5").update(body);
-        if (meta)
-            hasher.update("\x00meta:" + stableStringify(meta));
-        out.push({
-            path,
-            hash: hasher.digest("hex"),
-            size: info.size,
-            mtime: Math.floor(info.mtimeMs / 1000),
-            content_type: contentTypeForExt(ent.name),
-            ...(meta ? { meta } : {}),
-        });
-    }
-}
 /**
- * Deterministic JSON encoder. Object keys are sorted recursively so two
- * frontmatters with the same shape but different key order produce the same
- * hash; otherwise the manifest would churn on every YAML reformat.
+ * Per-page extension on .body.html manifest entries, consumed by the Foundry
+ * sync. Always carries the page's role (so the Foundry side can map roles to
+ * JournalEntry ownership against a per-vault dmRole setting); other fields
+ * are present only when the corresponding frontmatter is set.
  */
-function stableStringify(value) {
-    if (value === null || typeof value !== "object")
-        return JSON.stringify(value);
-    if (Array.isArray(value))
-        return "[" + value.map(stableStringify).join(",") + "]";
-    const obj = value;
-    const keys = Object.keys(obj).sort();
-    return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
-}
 /**
  * Strip an HTML body to plain text. Used to feed the search index from
  * the rendered article (post-wikilink, post-callout-redaction) so search