@wizzlethorpe/vaults 0.7.0 → 0.7.1

package/dist/build.js

@@ -1,23 +1,18 @@
-import { copyFile, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 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 { compressImage, COMPRESSIBLE_EXT_RE } from "./images.js";
+import { compressImage } from "./images.js";
+import { IMAGE_EXT_RE, PASSTHROUGH_EXT_RE, COMPRESSIBLE_EXT_RE, contentTypeForExt, } from "./render/extensions.js";
 import { buildFavicon } from "./favicon.js";
-// Any image format that can be referenced via ![[name.ext]]; superset of
-// COMPRESSIBLE_EXT_RE since SVGs/GIFs ship as-is rather than being recoded.
-const IMAGE_EXT_RE = /\.(png|jpe?g|webp|gif|svg|avif|tiff?)$/i;
-// Recognised non-image media that ride alongside the wiki: audio, video,
-// portable docs. Ship per-variant just like images (only into variants
-// whose visible pages reference them) so DM-only audio cues can't leak
-// into the public deploy. Anything outside this list is treated as
-// "unknown" and skipped by default; see the include_unknown_files setting.
-const PASSTHROUGH_EXT_RE = /\.(ogg|mp3|m4a|wav|flac|opus|aac|mp4|webm|mov|ogv|pdf|epub)$/i;
 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";
 import { buildPreview } from "./render/preview.js";
 import { resolvePageImage } from "./render/cover.js";
@@ -48,9 +43,8 @@ import { formatDuration, pMap, Progress } from "./util.js";
  *         <pages>.preview.json
  *         _search-index.json
  *
- * When there's a single role (the default `public`-only case) we collapse
- * `_variants/public/...` up to the root for backwards compatibility with
- * the current `vaults preview` and `vaults push` flow.
+ * Single-role builds (the default `public`-only case) collapse
+ * `_variants/public/...` up to the root.
  */
 export async function buildSite(opts) {
     const start = Date.now();
@@ -78,10 +72,7 @@ export async function buildSite(opts) {
     // and can override built-in names (last-registered wins). One registry
     // is built once and shared across every variant render.
     const userHandlers = await loadUserHandlers(opts.vaultPath);
-    const handlerRegistry = buildRegistry([
-        ...BUILTIN_HANDLERS,
-        ...userHandlers.map((h) => h.handler),
-    ]);
+    const handlerRegistry = buildRegistry(BUILTIN_HANDLERS, userHandlers.map((h) => h.handler));
     if (userHandlers.length > 0) {
         console.log(`  loaded ${userHandlers.length} custom handler(s) from .vaults/handlers/`);
     }
@@ -131,8 +122,15 @@ export async function buildSite(opts) {
         }
         return true;
     });
-    await rm(opts.outputDir, { recursive: true, force: true });
-    await mkdir(opts.outputDir, { recursive: true });
+    // Atomic build: write into <outputDir>.tmp and rename at the end.
+    // A failed mid-build leaves the previous deploy intact instead of
+    // serving half a website. Re-point opts.outputDir at the work dir so
+    // every downstream writeFile / mkdir lands in the right place.
+    const finalOutputDir = opts.outputDir;
+    const workOutputDir = finalOutputDir + ".tmp";
+    await rm(workOutputDir, { recursive: true, force: true });
+    await mkdir(workOutputDir, { recursive: true });
+    opts = { ...opts, outputDir: workOutputDir };
     const markdownFiles = withinLimit.filter((f) => /\.md$/i.test(f.path));
     const imageFiles = withinLimit.filter((f) => IMAGE_EXT_RE.test(f.path));
     // .base files are consumed at build time (rendered into HTML where embedded)
@@ -181,6 +179,13 @@ export async function buildSite(opts) {
         const basename = f.path.split("/").pop().replace(/\.base$/i, "");
         baseSources.set(slugify(basename), await readFile(f.absolute, "utf8"));
     });
+    // Two parses per page: the regex-based parseFrontmatter is tolerant of
+    // malformed YAML and still extracts title/role; gray-matter gives us
+    // the full property set for Bases.
+    const parsedSources = new Map();
+    for (const f of markdownFiles) {
+        parsedSources.set(f.path, parseFullFrontmatterWithContent(sources.get(f.path)));
+    }
     // Parse role + title per page. Pages with an unrecognised role fall back
     // to the default with a warning; better than silently dropping them. We
     // also stash the full frontmatter on each PageMeta so the Bases plugin
@@ -188,7 +193,7 @@ export async function buildSite(opts) {
     const allPageMetas = markdownFiles.map((f) => {
         const src = sources.get(f.path);
         const meta = parseFrontmatter(src);
-        const fullFm = parseFullFrontmatter(src);
+        const fullFm = parsedSources.get(f.path).data;
         let role = meta.role ?? defaultRole;
         if (!allRoleSet.has(role)) {
             console.warn(`  ${f.path}: role "${role}" not in settings.roles, using "${defaultRole}"`);
@@ -204,6 +209,16 @@ export async function buildSite(opts) {
             birthtime: f.birthtime,
         };
     });
+    // Stage assets referenced inside each page's foundry.data_json (Scene
+    // backgrounds / ambient sounds / tile art live in that JSON, not the page
+    // frontmatter, so the asset scanners below consult p.foundryAssets).
+    await Promise.all(allPageMetas.map(async (p) => {
+        if (!p.frontmatter)
+            return;
+        const refs = await collectDataJsonVaultRefs(opts.vaultPath, p.frontmatter, p.path);
+        if (refs.length > 0)
+            p.foundryAssets = refs;
+    }));
     // ── Image compression (staged; copied per-variant later) ────────────────
     // Compress once into a private staging dir under the deploy root. Each
     // variant's render pass copies whichever images its visible pages
@@ -227,10 +242,16 @@ export async function buildSite(opts) {
             const dest = join(imageStagingDir, compressed.outputPath);
             await mkdir(dirname(dest), { recursive: true });
             await writeFile(dest, compressed.body);
-            imageIndex.set(slugify(f.path.split("/").pop()), {
-                sourcePath: f.path,
-                outputPath: compressed.outputPath,
-            });
+            // Two keys for one entry: basename slug for body wikilinks/embeds
+            // (Obsidian resolves those by basename), and the full vault-relative
+            // path for `@vault/PATH` refs (frontmatter, data_json). Paths contain
+            // "/" and slugs don't, so the keyspaces never overlap. The full-path
+            // 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);
         }, (done, total) => progress.update(done, total));
         progress.done(`${imageFiles.length} processed (${cacheHits} cached, ${imageFiles.length - cacheHits} compressed)`);
     }
@@ -248,10 +269,12 @@ export async function buildSite(opts) {
             const dest = join(otherStagingDir, f.path);
             await mkdir(dirname(dest), { recursive: true });
             await copyFile(f.absolute, dest);
-            passthroughIndex.set(slugify(f.path.split("/").pop()), {
-                sourcePath: f.path,
-                outputPath: f.path,
-            });
+            // 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);
         }, (done, total) => progress.update(done, total));
         progress.done(`${stagedPassthroughs.length} staged`);
     }
@@ -264,6 +287,8 @@ export async function buildSite(opts) {
     const themeOverride = renderThemeOverride({
         lightAccent: settings.values.accent_color,
         lightBg: settings.values.bg_color,
+        darkAccent: settings.values.accent_color_dark,
+        darkBg: settings.values.bg_color_dark,
     });
     await writeFile(join(opts.outputDir, "styles.css"), DEFAULT_CSS + themeOverride);
     const userCss = await loadObsidianSnippets(opts.vaultPath);
@@ -277,6 +302,15 @@ export async function buildSite(opts) {
         await writeFile(join(opts.outputDir, "_handlers.js"), handlerAssets.js);
     if (hasHandlerCss)
         await writeFile(join(opts.outputDir, "_handlers.css"), handlerAssets.css);
+    // 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);
+    // 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
+    // contains different content. The path stays `/_handlers.foundry.{js,css}`
+    // — the middleware rewrites root requests to the matching variant.
     // Favicon; either user-supplied via settings.favicon, or a generated
     // default with the vault's first letter in accent on the theme background.
     try {
@@ -296,11 +330,19 @@ export async function buildSite(opts) {
     // Computed once against the final imageIndex so OG meta tags, Bases card
     // covers, hover previews, and Foundry actor/item reskin all resolve to the
     // same URL. settings.auto_image flips body-fallback discovery on/off.
+    //
+    // Pre-strip every role-typed callout from the body before discovery: the
+    // cover URL has to be the same across all variants the page is visible
+    // in, so it must not come from inside a `[!dm]` block (which would leak
+    // the image to public deploys). Frontmatter `image:` values are honoured
+    // as-is — those are explicit author intent.
+    const allRoleTypes = new Set(roles);
     for (const meta of allPageMetas) {
         const src = sources.get(meta.path);
         if (!src)
             continue;
-        const cover = resolvePageImage(src, meta.frontmatter, imageIndex, settings.values.auto_image);
+        const stripped = stripRoleGatedCallouts(src, allRoleTypes);
+        const cover = resolvePageImage(stripped, meta.frontmatter, imageIndex, settings.values.auto_image);
         if (cover)
             meta.coverImage = cover;
     }
@@ -324,8 +366,10 @@ export async function buildSite(opts) {
             redactRoles,
             variantDir,
             vaultName: opts.vaultName,
+            vaultPath: opts.vaultPath,
             allPageMetas,
             sources,
+            parsedSources,
             baseSources,
             imageIndex,
             imageStagingDir,
@@ -343,12 +387,35 @@ export async function buildSite(opts) {
         perRolePageCount[role] = stats.pageCount;
         if (!collapseToRoot)
             console.log(`  variant '${role}': ${stats.pageCount} pages`);
+        // Foundry-import opt-in bundles, emitted INSIDE the variant directory
+        // (not at the deploy root) so the auth middleware role-gates them.
+        // Single-role builds collapse variantDir to outputDir, so the file
+        // ends up at root automatically. The Foundry module fetches by the
+        // canonical `/_handlers.foundry.{js,css}` path; the middleware
+        // rewrites that to the matching `_variants/<role>/...` per the
+        // requesting bearer token's role.
+        // 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 (handlerAssets.foundry.js.length > 0) {
+                await writeFile(join(variantDir, "_handlers.foundry.js"), handlerAssets.foundry.js);
+            }
+            if (handlerAssets.foundry.css.length > 0) {
+                await writeFile(join(variantDir, "_handlers.foundry.css"), handlerAssets.foundry.css);
+            }
+        }
         // Write a per-variant _manifest.json so external clients (Foundry, MCP,
         // etc.) can do an incremental diff. Includes EVERY file that variant
         // serves; html, md, images (as relative paths into shared root), css.
         // bodyMeta carries per-page Foundry reskin metadata; folded into each
         // body row's hash so meta-only changes trigger a re-sync.
-        const manifest = await buildManifest(opts.outputDir, variantDir, stats.bodyMeta, !collapseToRoot, roles, opts.vaultName);
+        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,
+        });
         await writeFile(join(variantDir, "_manifest.json"), JSON.stringify(manifest));
     }
     // ── Pages Functions ─────────────────────────────────────────────────────
@@ -361,11 +428,12 @@ export async function buildSite(opts) {
         // mapped to a tier. clientSecret stays out of the bundle — it lives in
         // the Wrangler secret PATREON_CLIENT_SECRET, read from env in the
         // Function. The CLI uploads it on every push.
-        const patreonForFn = cfg.patreon && cfg.patreon.tiers && Object.keys(cfg.patreon.tiers).length > 0
+        const patreon = cfg.oauth?.patreon;
+        const patreonForFn = patreon && patreon.tiers && Object.keys(patreon.tiers).length > 0
             ? {
-                clientId: cfg.patreon.clientId,
-                campaignId: cfg.patreon.campaignId,
-                tiers: cfg.patreon.tiers,
+                clientId: patreon.clientId,
+                campaignId: patreon.campaignId,
+                tiers: patreon.tiers,
             }
             : null;
         const middleware = renderAuthMiddleware({
@@ -394,6 +462,12 @@ export async function buildSite(opts) {
     // variant that needs them, so they're no longer required for the deploy.
     await rm(imageStagingDir, { recursive: true, force: true });
     await rm(otherStagingDir, { recursive: true, force: true });
+    // Atomic swap: move the freshly-built tree into the final location.
+    // rm-then-rename: Node's rename refuses to overwrite a non-empty dir.
+    // A crash between rm and rename leaves the output missing, which is
+    // visibly broken rather than silently half-built.
+    await rm(finalOutputDir, { recursive: true, force: true });
+    await rename(workOutputDir, finalOutputDir);
     console.log(`Built in ${formatDuration(Date.now() - start)}.`);
     return {
         files,
@@ -412,7 +486,15 @@ async function buildVariant(a) {
         if (!a.visibleRoles.has(m.role))
             continue;
         visibleMetas.push(m);
-        visibleSources.set(m.path, a.sources.get(m.path));
+        // Strip role-gated callouts from the source BEFORE it enters any
+        // downstream pass (renderer, transclusion, asset scanner, outlinks).
+        // The renderer's calloutPlugin redacts at render time, but the source
+        // is what the asset scanner walks — without this strip, an
+        // `![[secret.webp]]` inside a `[!dm]` callout on a `role: public`
+        // page would copy the file into the public deploy and be reachable
+        // by URL even though the article hides the callout.
+        const raw = a.sources.get(m.path);
+        visibleSources.set(m.path, stripRoleGatedCallouts(raw, a.redactRoles));
     }
     // Synthesize folder indexes from the visible set only.
     const folderIndexes = generateFolderIndexes(visibleMetas, a.role, a.settings.inline_title);
@@ -440,20 +522,26 @@ async function buildVariant(a) {
         markdownContent.set(basenameSlug, visibleSources.get(p.path));
         markdownContent.set(pathSlug, visibleSources.get(p.path));
     }
+    // Pre-compute outlinks per page so the Bases plugin can answer
+    // file.hasLink() during render (Bases runs before the wikilink plugin
+    // populates the per-render outlinks list).
+    const outlinksByPath = collectOutlinksByPath(visibleMetas, visibleSources, pageIndex);
     const context = {
         pages: pageIndex,
         images: a.imageIndex,
+        passthroughs: a.passthroughIndex,
         markdownContent,
         bases: a.baseSources,
         defaultImageWidth: a.settings.default_image_width,
         redactRoles: a.redactRoles,
         handlers: a.handlerRegistry,
+        outlinksByPath,
     };
     const rendered = new Map();
     const progress = new Progress(`Pages (${a.role})`);
     progress.update(0, visibleMetas.length);
     await pMap(visibleMetas, a.concurrency, async (p) => {
-        const result = await renderMarkdown(visibleSources.get(p.path), context, basenameNoExt(p.path));
+        const result = await renderMarkdown(visibleSources.get(p.path), context, basenameNoExt(p.path), a.parsedSources.get(p.path));
         rendered.set(p.path, {
             title: result.title,
             html: result.html,
@@ -498,6 +586,7 @@ async function buildVariant(a) {
             hasHandlerJs: a.hasHandlerJs,
             hasHandlerCss: a.hasHandlerCss,
             footerHtml: a.footerHtml,
+            theme: themeOf(a.settings.theme),
             ...(p.mtime != null ? { mtime: p.mtime } : {}),
             ...(p.birthtime != null ? { birthtime: p.birthtime } : {}),
             ...(p.coverImage ? { coverImage: p.coverImage } : {}),
@@ -512,9 +601,14 @@ async function buildVariant(a) {
         // remark/rehype pipeline land in journals as-is, no client-side render.
         const bodyPath = outputBase + ".body.html";
         await writeFile(join(a.variantDir, bodyPath), r.html);
-        bodyMeta.set(bodyPath, collectBodyMeta(p));
+        bodyMeta.set(bodyPath, await collectBodyMeta(p, a.vaultPath));
         const source = visibleSources.get(p.path);
-        const preview = await buildPreview(source, r.title);
+        const preview = await buildPreview(source, r.title, {
+            frontmatter: a.parsedSources.get(p.path)?.data ?? {},
+            registry: a.handlerRegistry,
+            renderContext: context,
+            pagePath: p.path,
+        });
         await writeFile(join(a.variantDir, outputBase + ".preview.json"), JSON.stringify(preview));
     });
     progress.done(`${visibleMetas.length} rendered`);
@@ -530,6 +624,7 @@ async function buildVariant(a) {
         hasHandlerJs: a.hasHandlerJs,
         hasHandlerCss: a.hasHandlerCss,
         footerHtml: a.footerHtml,
+        theme: themeOf(a.settings.theme),
     }));
     // Per-variant search index. `text` is the page's RENDERED HTML body
     // collapsed to plain text (tags stripped, entities decoded), so search
@@ -552,32 +647,123 @@ 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, a.passthroughIndex, a.passthroughStagingDir, a.variantDir);
+    await copyReferencedPassthroughs(visibleSources, visibleMetas, a.passthroughIndex, a.passthroughStagingDir, a.variantDir);
     return { pageCount: visibleMetas.length, bodyMeta };
 }
 /**
  * Build the per-body manifest meta from a page's frontmatter + resolved
  * cover image. `role` always lands so the Foundry side can apply the
- * dmRole permission gate; the foundry_base / image fields are conditional.
+ * dmRole permission gate; the foundry / image fields are conditional.
+ *
+ * Frontmatter shape forwarded to clients:
+ *   foundry:
+ *     base: <UUID> | <Type>[:<subtype>]   # required for instantiation
+ *     embed: false                          # default true
+ *     data: { … deep-merged into the doc }
  */
-function collectBodyMeta(p) {
+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 fb = fm["foundry_base"];
-    if (typeof fb === "string" && fb.trim().length > 0) {
-        out.foundry_base = fb.trim();
-    }
     const fo = fm["foundry"];
     if (fo && typeof fo === "object" && !Array.isArray(fo)) {
-        out.foundry = 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;
+        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 referenced inside a page's foundry.data_json
+ *  file. A Scene's bulk asset refs (backgrounds, ambient sounds, tiles) live in
+ *  that JSON content rather than the page frontmatter, so the per-variant asset
+ *  scanners would otherwise never stage 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 rel = fo["data_json"];
+    if (typeof rel !== "string" || !rel.trim())
+        return [];
+    const parsed = await loadDataJson(vaultPath, rel.trim(), pagePath);
+    if (parsed === null)
+        return [];
+    const out = [];
+    forEachString(parsed, (s) => {
+        const path = vaultRefPath(s);
+        if (path)
+            out.push(path);
+    });
+    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) {
+    return s === "light" || s === "dark" ? s : "auto";
+}
 const EMBED_RE = /!\[\[([^\[\]|#\n]+?)(?:\|[^\[\]#\n]*)?\]\]/g;
 async function copyReferencedImages(visibleSources, visibleMetas, imageIndex, stagingDir, variantDir) {
     const refs = new Set();
@@ -594,19 +780,35 @@ async function copyReferencedImages(visibleSources, visibleMetas, imageIndex, st
     // 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)
-            continue;
-        if (/^https?:\/\//i.test(p.coverImage))
-            continue;
-        let outputPath;
-        try {
-            outputPath = decodeURIComponent(p.coverImage.replace(/^\//, ""));
+        if (p.coverImage && !/^https?:\/\//i.test(p.coverImage)) {
+            try {
+                refs.add(decodeURIComponent(p.coverImage.replace(/^\//, "")));
+            }
+            catch { /* malformed coverImage URL — ignore */ }
         }
-        catch {
-            continue;
+        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);
         }
-        refs.add(outputPath);
     }
     for (const outputPath of refs) {
         const src = join(stagingDir, outputPath);
@@ -628,6 +830,73 @@ async function copyReferencedImages(visibleSources, visibleMetas, imageIndex, st
 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.
+const CALLOUT_HEAD_RE = /^>\s*\[!(\w+)\]/;
+/**
+ * Drop callout blocks whose type is in `redactRoles` from the source. Walks
+ * line-by-line; on a callout-head line whose type is redacted, drops every
+ * subsequent line that is part of the same blockquote (starts with `>`).
+ * A blank line ends the blockquote per CommonMark.
+ *
+ * Approximate by markdown standards (doesn't handle lazy-continuation lines
+ * or nested blockquotes containing role-gated children), but covers every
+ * pattern the asset scanner needs to gate against. The renderer's
+ * calloutPlugin still runs as the source of truth for visual redaction;
+ * this strip is the asset-leak guard.
+ */
+function stripRoleGatedCallouts(source, redactRoles) {
+    if (redactRoles.size === 0)
+        return source;
+    const lines = source.split("\n");
+    const out = [];
+    let dropping = false;
+    for (const line of lines) {
+        if (dropping) {
+            if (line.startsWith(">"))
+                continue; // still inside the blockquote
+            dropping = false;
+            out.push(line); // blank or non-`>` line ends + keeps the line
+            continue;
+        }
+        const head = CALLOUT_HEAD_RE.exec(line);
+        if (head && redactRoles.has(head[1].toLowerCase())) {
+            dropping = true;
+            continue; // drop the head line
+        }
+        out.push(line);
+    }
+    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
@@ -637,7 +906,7 @@ const WIKI_LINK_RE = /!?\[\[([^\[\]|#\n]+\.[a-z0-9]+)(?:\|[^\[\]#\n]*)?(?:#[^\[\
  * the whole point of the change; a stray DM-only audio cue stays in the
  * dm variant only.
  */
-async function copyReferencedPassthroughs(visibleSources, passthroughIndex, stagingDir, variantDir) {
+async function copyReferencedPassthroughs(visibleSources, visibleMetas, passthroughIndex, stagingDir, variantDir) {
     if (passthroughIndex.size === 0)
         return;
     const refs = new Set();
@@ -658,6 +927,28 @@ async function copyReferencedPassthroughs(visibleSources, passthroughIndex, stag
                 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);
@@ -763,7 +1054,13 @@ function chooseColumns(pages) {
             if (["title", "role", "aliases", "tags"].includes(key))
                 continue;
             const v = fm[key];
-            if (v == null || v === "" || (Array.isArray(v) && v.length === 0))
+            if (v == null || v === "")
+                continue;
+            // Skip non-scalar values — arrays and plain objects render as
+            // "[object Object]" or comma-joined junk in a table cell. Dates
+            // are technically objects but renderValue formats them nicely,
+            // so let them through.
+            if (typeof v === "object" && !(v instanceof Date))
                 continue;
             counts.set(key, (counts.get(key) ?? 0) + 1);
         }
@@ -806,6 +1103,35 @@ async function compressImageCached(file, quality, cacheDir, onHit) {
  * spread it directly into the LayoutInput; missing frontmatter contributes
  * nothing to the layout.
  */
+// Pre-compute outgoing wikilinks per page (vault path → set of vault paths).
+// Bases needs this before render runs so file.hasLink() can answer truthfully
+// during render; the wikilink plugin's per-render outlinks list is collected
+// after Bases has already drawn the table. A regex scan over markdown source
+// (rather than rebuilding the AST) is fine: this only needs to detect link
+// targets, and an embedded ![[image.png]] resolves to no page anyway.
+const WIKILINK_SCAN_RE = /(?<!!)(?<!\[)\[\[([^\[\]|#\n]+?)(?:#[^\[\]|\n]+?)?(?:\|[^\[\]#\n]+?)?\]\]/g;
+function collectOutlinksByPath(metas, sources, pageIndex) {
+    const out = new Map();
+    for (const p of metas) {
+        const src = sources.get(p.path);
+        if (!src)
+            continue;
+        const targets = new Set();
+        for (const match of src.matchAll(WIKILINK_SCAN_RE)) {
+            const name = match[1].trim();
+            const slug = slugify(name);
+            const last = name.includes("/") ? name.split("/").pop() : "";
+            const page = pageIndex.get(slug)
+                ?? pageIndex.get(slugify(name + "/index"))
+                ?? (last ? pageIndex.get(slugify(last)) : undefined);
+            if (page && page.path !== p.path)
+                targets.add(page.path);
+        }
+        if (targets.size > 0)
+            out.set(p.path, targets);
+    }
+    return out;
+}
 function extractFrontmatterBlock(source) {
     const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source);
     if (!m || !m[1] || !m[1].trim())
@@ -826,23 +1152,26 @@ function parseFrontmatter(source) {
     };
 }
 /**
- * Full YAML frontmatter, used by the Bases plugin so any property a user
- * defines (location, status, npc-class, etc.) is queryable. We delegate
- * to gray-matter so we get real YAML rather than the regex-narrow set
- * `parseFrontmatter` extracts.
+ * Full YAML frontmatter + body content, used by the Bases plugin (frontmatter
+ * properties) and threaded through to renderMarkdown so the pipeline doesn't
+ * have to call gray-matter again. `data` is real YAML; falls back to {} on
+ * malformed YAML so the page still renders. Content matches what gray-matter
+ * would give the pipeline (frontmatter block stripped from the head).
  */
-function parseFullFrontmatter(source) {
+function parseFullFrontmatterWithContent(source) {
     if (!source.startsWith("---"))
-        return {};
+        return { data: {}, content: source };
     try {
-        const data = matter(source).data;
-        return (data && typeof data === "object" ? data : {});
+        const m = matter(source);
+        const data = (m.data && typeof m.data === "object" ? m.data : {});
+        return { data, content: m.content };
     }
     catch {
         // Malformed YAML; the existing parseFrontmatter is more forgiving for
-        // the title/role/aliases keys we actually need. Return empty here so
-        // the page still renders.
-        return {};
+        // the title/role/aliases keys we actually need. Return empty data + the
+        // body with the leading `---\n…\n---\n` stripped via regex so the rest
+        // of the pipeline still sees a clean body.
+        return { data: {}, content: source.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "") };
     }
 }
 /**
@@ -876,10 +1205,6 @@ function parseAliases(fm) {
 function unquote(s) {
     return s.replace(/^["']|["']$/g, "");
 }
-function extractH1(source) {
-    const h1 = /^#\s+(.+)$/m.exec(source);
-    return h1?.[1] ? h1[1].trim() : null;
-}
 function basenameNoExt(path) {
     return path.split("/").pop().replace(/\.md$/i, "");
 }
@@ -932,13 +1257,7 @@ function kindLabel(kind) {
         default: return kind;
     }
 }
-/**
- * Walk the variant directory and produce a manifest of every file with its MD5
- * hash + size + mtime + content type. Shared assets (anything OUTSIDE the
- * variant dir but inside the deploy root) are listed too; clients use a
- * single manifest to diff the entire site, not just the role-specific bits.
- */
-async function buildManifest(rootDir, variantDir, bodyMeta, authRequired, roles, vaultName) {
+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
@@ -963,7 +1282,30 @@ async function buildManifest(rootDir, variantDir, bodyMeta, authRequired, roles,
     // 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.
-    return { name: vaultName, auth: { required: authRequired, roles }, files };
+    // 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 });
@@ -986,7 +1328,7 @@ async function walkAndIndex(dir, pathBase, out, seen, skipDirNames, bodyMeta) {
         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
+        // 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)
@@ -1015,46 +1357,6 @@ function stableStringify(value) {
     const keys = Object.keys(obj).sort();
     return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
 }
-function contentTypeForExt(filename) {
-    const ext = filename.split(".").pop()?.toLowerCase() ?? "";
-    const map = {
-        html: "text/html; charset=utf-8",
-        md: "text/markdown; charset=utf-8",
-        json: "application/json",
-        css: "text/css; charset=utf-8",
-        js: "application/javascript; charset=utf-8",
-        png: "image/png",
-        jpg: "image/jpeg",
-        jpeg: "image/jpeg",
-        webp: "image/webp",
-        gif: "image/gif",
-        svg: "image/svg+xml",
-        avif: "image/avif",
-        pdf: "application/pdf",
-        mp3: "audio/mpeg",
-        wav: "audio/wav",
-        ogg: "audio/ogg",
-    };
-    return map[ext] ?? "application/octet-stream";
-}
-function extractPlainText(source, max) {
-    return source
-        .replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "")
-        .replace(/%%[\s\S]*?%%/g, "")
-        .replace(/```[\s\S]*?```/g, "")
-        .replace(/!\[\[[^\]]+\]\]/g, "")
-        .replace(/\[\[([^\]|#]+)(?:[#|][^\]]+)?\]\]/g, "$1")
-        .replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
-        .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
-        .replace(/`([^`]+)`/g, "$1")
-        .replace(/[*_~]+([^*_~\n]+)[*_~]+/g, "$1")
-        .replace(/^>\s?\[![^\]]+\][+-]?\s*(.*)$/gm, "$1")
-        .replace(/^>\s?/gm, "")
-        .replace(/^#{1,6}\s+/gm, "")
-        .replace(/\s+/g, " ")
-        .trim()
-        .slice(0, max);
-}
 /**
  * Strip an HTML body to plain text. Used to feed the search index from
  * the rendered article (post-wikilink, post-callout-redaction) so search