@wizzlethorpe/vaults 0.6.1 → 0.8.0

package/dist/build.js

@@ -1,32 +1,34 @@
-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";
 import { DEFAULT_CSS, renderThemeOverride } from "./render/styles.js";
 import { loadObsidianSnippets } from "./obsidian.js";
 import { loadSettings, writeSettings, SETTINGS_FILE } from "./settings.js";
-import { loadConfig, saveConfig } from "./config.js";
+import { loadConfig } from "./config.js";
 import matter from "gray-matter";
 import { renderAuthMiddleware, LOGIN_HTML } from "./render/auth-template.js";
+import { renderFooterHtml } from "./render/footer.js";
+import { buildRegistry } from "./render/handlers/types.js";
+import { loadUserHandlers } from "./render/handlers/loader.js";
+import { BUILTIN_HANDLERS } from "./render/handlers/builtin/index.js";
+import { bundleHandlerAssets } from "./render/handlers/assets.js";
+import { runMigrations } from "./migrate/run.js";
+import { cacheDir } from "./paths.js";
 import { formatDuration, pMap, Progress } from "./util.js";
 /**
  * Output layout when there are multiple roles:
@@ -41,17 +43,16 @@ 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();
     const concurrency = Math.max(2, availableParallelism());
-    // One-shot migration for vaults from before auth config moved to
-    // .vaultrc.json. If the user's settings.md still has roles/auth_type/
-    // role_passwords, copy them over before the canonicalizer strips them.
-    await migrateLegacyAuthFromSettings(opts.vaultPath);
+    // 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);
     // ── Settings (user-editable) ─────────────────────────────────────────────
     const settings = await loadSettings(opts.vaultPath);
     for (const w of settings.warnings)
@@ -66,6 +67,26 @@ export async function buildSite(opts) {
         imageQuality: opts.imageQuality === 85 ? settings.values.image_quality : opts.imageQuality,
         maxFileBytes: opts.maxFileBytes === 25 * 1024 * 1024 ? settings.values.max_file_bytes : opts.maxFileBytes,
     };
+    // ── Custom handlers ──────────────────────────────────────────────────────
+    // Built-ins ship with the CLI; user handlers live in `.vaults/handlers/`
+    // 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));
+    if (userHandlers.length > 0) {
+        console.log(`  loaded ${userHandlers.length} custom handler(s) from .vaults/handlers/`);
+    }
+    // Concatenate browser-side assets declared by built-in and user handlers
+    // into a single _handlers.js / _handlers.css emitted at the deploy root.
+    // Each unique source is included once, regardless of invocation count.
+    // Two independent flags so a deploy with only-JS or only-CSS doesn't
+    // reference a file that wasn't written.
+    const handlerAssets = await bundleHandlerAssets(userHandlers, BUILTIN_HANDLERS, opts.vaultPath);
+    const hasHandlerJs = handlerAssets.js.length > 0;
+    const hasHandlerCss = handlerAssets.css.length > 0;
+    // Footer markdown rendered once per build; the resulting HTML is
+    // embedded verbatim in every page's layout. Empty string = no footer.
+    const footerHtml = await renderFooterHtml(settings.values.footer);
     // ── CLI-managed state (auth) ─────────────────────────────────────────────
     const cfg = await loadConfig(opts.vaultPath, {});
     const roles = cfg.roles.length > 0 ? cfg.roles : ["public"];
@@ -101,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)
@@ -151,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
@@ -158,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}"`);
@@ -183,8 +218,8 @@ export async function buildSite(opts) {
     const imageStagingDir = join(opts.outputDir, ".image-staging");
     const imageIndex = new Map();
     if (imageFiles.length > 0) {
-        const cacheDir = join(opts.vaultPath, ".vault-cache", "images", `q${opts.imageQuality}`);
-        await mkdir(cacheDir, { recursive: true });
+        const cacheImageDir = join(cacheDir(opts.vaultPath), "images", `q${opts.imageQuality}`);
+        await mkdir(cacheImageDir, { recursive: true });
         let cacheHits = 0;
         const progress = new Progress("Images");
         progress.update(0, imageFiles.length);
@@ -192,7 +227,7 @@ export async function buildSite(opts) {
             // SVGs / non-compressible images pass through; everything else gets
             // recoded to webp for size. Either way they land in the staging dir.
             const compressed = opts.imageQuality > 0 && COMPRESSIBLE_EXT_RE.test(f.path)
-                ? await compressImageCached(f, opts.imageQuality, cacheDir, () => { cacheHits++; })
+                ? await compressImageCached(f, opts.imageQuality, cacheImageDir, () => { cacheHits++; })
                 : { body: await readFile(f.absolute), outputPath: f.path };
             const dest = join(imageStagingDir, compressed.outputPath);
             await mkdir(dirname(dest), { recursive: true });
@@ -234,12 +269,30 @@ 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);
     await writeFile(join(opts.outputDir, "user.css"), userCss);
     if (userCss)
         console.log(`  loaded user.css from .obsidian/snippets/`);
+    // Browser-side handler assets (built-in + user) concatenated into a
+    // single deploy-root JS and CSS file. Skipped entirely if no handler
+    // declared any assets (purely declarative handlers stay overhead-free).
+    if (hasHandlerJs)
+        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 {
@@ -259,11 +312,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;
     }
@@ -287,8 +348,10 @@ export async function buildSite(opts) {
             redactRoles,
             variantDir,
             vaultName: opts.vaultName,
+            vaultPath: opts.vaultPath,
             allPageMetas,
             sources,
+            parsedSources,
             baseSources,
             imageIndex,
             imageStagingDir,
@@ -296,18 +359,45 @@ export async function buildSite(opts) {
             passthroughStagingDir: otherStagingDir,
             settings: settings.values,
             authConfigured: roles.length > 1,
+            handlerRegistry,
+            hasHandlerJs,
+            hasHandlerCss,
+            footerHtml,
             concurrency,
             allWarnings: opts.allWarnings,
         });
         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 ─────────────────────────────────────────────────────
@@ -320,11 +410,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({
@@ -353,6 +444,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,
@@ -371,10 +468,18 @@ 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);
+    const folderIndexes = generateFolderIndexes(visibleMetas, a.role, a.settings.inline_title);
     for (const fi of folderIndexes) {
         visibleMetas.push({ path: fi.path, title: fi.title, role: a.role });
         visibleSources.set(fi.path, fi.markdown);
@@ -399,19 +504,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,
@@ -453,6 +565,10 @@ async function buildVariant(a) {
             centerImages: a.settings.center_images,
             backlinks,
             authConfigured: a.authConfigured,
+            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 } : {}),
@@ -467,7 +583,7 @@ 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);
         await writeFile(join(a.variantDir, outputBase + ".preview.json"), JSON.stringify(preview));
@@ -482,6 +598,10 @@ async function buildVariant(a) {
         defaultImageWidth: a.settings.default_image_width,
         centerImages: a.settings.center_images,
         authConfigured: a.authConfigured,
+        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
@@ -504,32 +624,101 @@ 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;
+    }
+}
+/** 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();
@@ -546,19 +735,27 @@ 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(slugify(path.split("/").pop()));
+                    if (image)
+                        refs.add(image.outputPath);
+                }
+            });
         }
-        refs.add(outputPath);
     }
     for (const outputPath of refs) {
         const src = join(stagingDir, outputPath);
@@ -580,6 +777,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
@@ -589,7 +853,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();
@@ -610,6 +874,22 @@ 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(slugify(path.split("/").pop()));
+                if (entry)
+                    refs.add(entry.outputPath);
+            }
+        });
+    }
     for (const outputPath of refs) {
         const src = join(stagingDir, outputPath);
         const dst = join(variantDir, outputPath);
@@ -624,9 +904,11 @@ async function copyReferencedPassthroughs(visibleSources, passthroughIndex, stag
 }
 /**
  * Build synthesised index.md for any folder (including the root) that has
- * pages but no existing index.md.
+ * pages but no existing index.md. When `inlineTitle` is true, the layout
+ * already injects an <h1> from the page's title, so the synthesised body
+ * skips its own `# Title` heading to avoid the duplicate.
  */
-function generateFolderIndexes(existing, _role) {
+function generateFolderIndexes(existing, _role, inlineTitle) {
     const existingPaths = new Set(existing.map((p) => p.path));
     const folders = new Map();
     folders.set("", { folders: new Set(), pages: [] });
@@ -675,11 +957,28 @@ function generateFolderIndexes(existing, _role) {
             const propsBlock = propsYaml ? `properties:\n${propsYaml}\n` : "";
             sections.push(`## Pages\n\n\`\`\`base\n${filtersBlock}\n${propsBlock}views:\n  - type: table\n    name: Contents\n    order:\n${orderYaml}\n\`\`\``);
         }
-        const heading = title ? `# ${title}\n\n` : "";
-        out.push({ path: indexPath, title: title || "Home", markdown: `${heading}${sections.join("\n\n")}\n` });
+        // With inline_title on, the layout injects an <h1> from the page's
+        // title — which it learns from the markdown's title source. We can
+        // either author the title as a `# Heading` (off-mode) or as YAML
+        // frontmatter (on-mode); the latter avoids the duplicated <h1> while
+        // still letting the renderer surface the right title.
+        const displayTitle = title || "Home";
+        const heading = inlineTitle ? "" : (title ? `# ${title}\n\n` : "");
+        const frontmatter = inlineTitle ? `---\ntitle: ${yamlString(displayTitle)}\n---\n\n` : "";
+        out.push({
+            path: indexPath,
+            title: displayTitle,
+            markdown: `${frontmatter}${heading}${sections.join("\n\n")}\n`,
+        });
     }
     return out;
 }
+/** YAML-quote a string only when needed (special chars or ambiguous flow). */
+function yamlString(s) {
+    if (/^[A-Za-z0-9_ .-]+$/.test(s) && !/^(true|false|null|yes|no)$/i.test(s))
+        return s;
+    return JSON.stringify(s);
+}
 /**
  * Pick a small set of columns for an auto-generated folder index based on
  * what frontmatter the pages in that folder actually have. The first
@@ -696,7 +995,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);
         }
@@ -739,6 +1044,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())
@@ -759,23 +1093,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?/, "") };
     }
 }
 /**
@@ -809,10 +1146,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, "");
 }
@@ -865,13 +1198,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
@@ -896,7 +1223,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 });
@@ -919,7 +1269,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)
@@ -948,104 +1298,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";
-}
-/**
- * Pre-canonicalisation migration. Earlier versions stored roles, auth_type,
- * and role_passwords in settings.md frontmatter; they now live in
- * .vaultrc.json. If we still see them in settings.md (legacy vault), copy
- * over what's missing in .vaultrc.json so the imminent canonicaliser doesn't
- * silently drop them.
- *
- * Idempotent: returns true and logs only if it actually moved something.
- */
-async function migrateLegacyAuthFromSettings(vaultPath) {
-    const settingsPath = join(vaultPath, SETTINGS_FILE);
-    let raw;
-    try {
-        raw = await readFile(settingsPath, "utf8");
-    }
-    catch {
-        return false;
-    }
-    const fm = (matter(raw).data ?? {});
-    const hasLegacy = "roles" in fm || "auth_type" in fm || "role_passwords" in fm;
-    if (!hasLegacy)
-        return false;
-    const cfg = await loadConfig(vaultPath, {});
-    const moved = [];
-    // roles: only migrate if cfg is still at the default ["public"].
-    if (Array.isArray(fm.roles)) {
-        const list = fm.roles.filter((r) => typeof r === "string");
-        const isDefault = cfg.roles.length === 0 || (cfg.roles.length === 1 && cfg.roles[0] === "public");
-        if (list.length > 0 && isDefault && !arraysEqual(list, ["public"])) {
-            cfg.roles = list;
-            moved.push("roles");
-        }
-    }
-    if (typeof fm.auth_type === "string" && cfg.authType === "password" && fm.auth_type !== "password") {
-        cfg.authType = fm.auth_type;
-        moved.push("auth_type");
-    }
-    if (fm.role_passwords && typeof fm.role_passwords === "object" && !Array.isArray(fm.role_passwords)
-        && Object.keys(cfg.rolePasswords).length === 0) {
-        const map = fm.role_passwords;
-        const cleaned = {};
-        for (const [k, v] of Object.entries(map))
-            if (typeof v === "string")
-                cleaned[k] = v;
-        if (Object.keys(cleaned).length > 0) {
-            cfg.rolePasswords = cleaned;
-            moved.push("role_passwords");
-        }
-    }
-    if (moved.length === 0)
-        return false;
-    await saveConfig(vaultPath, cfg);
-    console.log(`  migrated ${moved.join(", ")} from settings.md → .vaultrc.json`);
-    return true;
-}
-function arraysEqual(a, b) {
-    return a.length === b.length && a.every((x, i) => x === b[i]);
-}
-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