@wizzlethorpe/vaults 0.13.2 → 0.14.0

package/dist/foundry-importer.bundle.js

@@ -16,10 +16,15 @@ async function fetchManifest(vault) {
 var BATCH_SIZE = 100;
 var BATCH_CONCURRENCY = 4;
 var DIRECT_CONCURRENCY = 8;
-async function fetchSourceBatch(vault, paths) {
+function batchEndpoint(vault, role) {
+  const endpoint = new URL(url(vault, "/_batch"));
+  if (role) endpoint.searchParams.set("role", role);
+  return endpoint;
+}
+async function fetchSourceBatch(vault, paths, role) {
   if (paths.length === 0) return /* @__PURE__ */ new Map();
   if (vault.public) return fetchSourceDirect(vault, paths);
-  const endpoint = url(vault, "/_batch");
+  const endpoint = batchEndpoint(vault, role);
   const chunks = [];
   for (let i = 0; i < paths.length; i += BATCH_SIZE) chunks.push(paths.slice(i, i + BATCH_SIZE));
   const out = /* @__PURE__ */ new Map();
@@ -27,7 +32,7 @@ async function fetchSourceBatch(vault, paths) {
   const workers = Array.from({ length: Math.min(BATCH_CONCURRENCY, chunks.length) }, async () => {
     while (next < chunks.length) {
       const idx = next++;
-      const res = await fetch(endpoint, {
+      const res = await fetch(endpoint.toString(), {
         method: "POST",
         headers: { "Content-Type": "text/plain" },
         body: chunks[idx].join("\n")
@@ -69,6 +74,185 @@ async function fetchSourceDirect(vault, paths) {
 // ../foundry/scripts/settings.mjs
 var MODULE_ID = "vaults";
 
+// ../foundry/scripts/foundry-base.mjs
+var PACK_KEY = {
+  Actor: "actors",
+  Item: "items",
+  Scene: "scenes",
+  JournalEntry: "journal",
+  RollTable: "tables",
+  Macro: "macros",
+  Cards: "cards",
+  Playlist: "playlists"
+};
+var BLANK_DOC_TYPES = [
+  "Actor",
+  "Item",
+  "Scene",
+  "JournalEntry",
+  "RollTable",
+  "Macro",
+  "Cards",
+  "Playlist"
+];
+function canonicalType(raw) {
+  if (!raw) return null;
+  return BLANK_DOC_TYPES.find((t) => t.toLowerCase() === raw.toLowerCase()) ?? null;
+}
+function parseFoundryBase(spec) {
+  if (typeof spec !== "string" || !spec) return null;
+  if (spec.startsWith("@moulinette/")) {
+    const ref = spec.slice("@moulinette/".length);
+    return ref ? { kind: "moulinette", ref } : null;
+  }
+  if (spec.includes(".")) return { kind: "uuid", uuid: spec };
+  const [typeRaw, subtype] = spec.split(":");
+  const docName = canonicalType(typeRaw);
+  if (!docName) return null;
+  return { kind: "blank", docName, subtype: subtype || void 0 };
+}
+function docNameOf(parsed) {
+  if (!parsed) return null;
+  if (parsed.kind === "blank") return parsed.docName;
+  if (parsed.kind === "moulinette") return null;
+  const parts = parsed.uuid.split(".");
+  if (parts.length < 2) return null;
+  const raw = parts[parts.length - 2];
+  return canonicalType(raw) ?? raw ?? null;
+}
+function docNameFromBase(base) {
+  const specs = Array.isArray(base) ? base : [base];
+  for (const spec of specs) {
+    const docName = docNameOf(parseFoundryBase(spec));
+    if (docName) return docName;
+  }
+  return null;
+}
+
+// ../foundry/scripts/packs.mjs
+function packName(vault, docName) {
+  const key = docName === "Adventure" ? "adventure" : PACK_KEY[docName];
+  if (!key) return null;
+  return `${vault.id}-${key}`;
+}
+function packCollection(vault, docName) {
+  const name = packName(vault, docName);
+  return name ? `world.${name}` : null;
+}
+function isAdventure(vault) {
+  return vault.foundryPackage === "adventure";
+}
+function uuidPrefix(vault, docName) {
+  return isAdventure(vault) ? "" : `Compendium.${packCollection(vault, docName)}.`;
+}
+async function pruneStalePacks(vault) {
+  const wanted = isAdventure(vault) ? /* @__PURE__ */ new Set(["Adventure"]) : new Set(Object.keys(PACK_KEY));
+  for (const docName of [...Object.keys(PACK_KEY), "Adventure"]) {
+    if (wanted.has(docName)) continue;
+    const pack = getPack(vault, docName);
+    if (!pack) continue;
+    try {
+      await pack.deleteCompendium();
+      console.info(
+        `Vaults | ${vault.label}: removed ${pack.collection}, left over from the previous foundry_package setting.`
+      );
+    } catch (err) {
+      console.warn(`Vaults | could not remove the stale pack ${pack.collection}:`, err);
+    }
+  }
+}
+function journalPageUuid(vault, entryId2, pageId2) {
+  return uuidPrefix(vault, "JournalEntry") + `JournalEntry.${entryId2}.JournalEntryPage.${pageId2}`;
+}
+function instanceUuid(vault, docName, id) {
+  return uuidPrefix(vault, docName) + `${docName}.${id}`;
+}
+function getPack(vault, docName) {
+  const collection = packCollection(vault, docName);
+  return collection ? game.packs.get(collection) ?? null : null;
+}
+function vaultPacks(vault) {
+  return [...Object.keys(PACK_KEY), "Adventure"].map((docName) => getPack(vault, docName)).filter((pack) => pack !== null);
+}
+async function deleteVaultPacks(vaultId) {
+  for (const pack of vaultPacks({ id: vaultId })) {
+    try {
+      await pack.deleteCompendium();
+    } catch (err) {
+      console.warn(`Vaults | failed to delete pack ${pack.collection}:`, err);
+    }
+  }
+}
+var inFlight = /* @__PURE__ */ new Map();
+async function ensurePack(vault, docName) {
+  const collection = packCollection(vault, docName);
+  if (!collection) throw new Error(`No pack is defined for ${docName} documents`);
+  const existing = game.packs.get(collection);
+  if (existing) {
+    assertWritable(existing, vault);
+    await enforceOwnership(existing, vault);
+    return existing;
+  }
+  const pending = inFlight.get(collection);
+  if (pending) return pending;
+  const promise = createPack(vault, docName, collection).finally(() => inFlight.delete(collection));
+  inFlight.set(collection, promise);
+  return promise;
+}
+function ownershipFor(vault) {
+  const base = { GAMEMASTER: "OWNER", ASSISTANT: "OWNER" };
+  return vault.public ? { ...base, TRUSTED: "OBSERVER", PLAYER: "OBSERVER" } : { ...base, TRUSTED: "NONE", PLAYER: "NONE" };
+}
+async function enforceOwnership(pack, vault) {
+  const want = ownershipFor(vault);
+  const have = pack.config.ownership;
+  if (have && Object.entries(want).every(([k, v]) => have[k] === v)) return;
+  await pack.configure({ ownership: want });
+  if (!vault.public) {
+    console.info(
+      `Vaults | ${pack.collection}: restricted to GM. It was readable by ${have?.PLAYER ?? "PLAYER: OBSERVER (Foundry's default)"}, which exposes every name and image in the pack index.`
+    );
+  }
+}
+async function createPack(vault, docName, collection) {
+  const label = `${vault.label || "Vault"}: ${LABEL[docName] ?? docName}`;
+  await foundry.documents.collections.CompendiumCollection.createCompendium({
+    type: docName,
+    label,
+    name: packName(vault, docName),
+    packageType: "world"
+  });
+  const pack = game.packs.get(collection);
+  if (!pack) throw new Error(`Compendium pack ${collection} was not created`);
+  await pack.setFolder(await ensurePackFolder(vault));
+  assertWritable(pack, vault);
+  await enforceOwnership(pack, vault);
+  return pack;
+}
+function assertWritable(pack, vault) {
+  if (!pack.locked) return;
+  throw new Error(
+    `Compendium pack ${pack.collection} is locked. Unlock it in the sidebar to let ${vault.label || "this vault"} sync into it.`
+  );
+}
+async function ensurePackFolder(vault) {
+  const name = vault.rootFolder || vault.label || "Vault";
+  const existing = game.folders.find((f) => f.type === "Compendium" && f.name === name);
+  if (existing) return existing;
+  return Folder.create({ name, type: "Compendium" });
+}
+var LABEL = {
+  Adventure: "Adventure",
+  Actor: "Actors",
+  Item: "Items",
+  Scene: "Scenes",
+  JournalEntry: "Journals",
+  RollTable: "Roll Tables",
+  Macro: "Macros",
+  Cards: "Cards",
+  Playlist: "Playlists"
+};
+
 // ../foundry/scripts/util.mjs
 function escapeAttr(s) {
   return String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
@@ -83,6 +267,11 @@ async function hexDigest(algorithm, text) {
   const buf = await crypto.subtle.digest(algorithm, new TextEncoder().encode(text));
   return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+function localizeOr(host, key, fallback, args) {
+  const text = host.localize(key, args);
+  if (text && text !== key) return text;
+  return String(fallback).replace(/\{(\w+)\}/g, (whole, name) => args && name in args ? String(args[name]) : whole);
+}
 
 // ../foundry/scripts/ids.mjs
 async function det(kind, key) {
@@ -98,10 +287,65 @@ var pageId = (vaultId, path) => det("page", `${vaultId}:${path}`);
 var folderId = (vaultId, path) => det("folder", `${vaultId}:${path}`);
 var instanceId = (vaultId, path) => det("instance", `${vaultId}:${path}`);
 var subdocId = (vaultId, path, pointer) => det("subdoc", `${vaultId}:${path}:${pointer}`);
+var adventureId = (vaultId) => det("adventure", vaultId);
 
 // ../foundry/scripts/parser.mjs
 var CACHED_EXT_RE = /\.(png|jpe?g|webp|gif|svg|avif|tiff?|bmp|heic|apng|ogg|mp3|m4a|wav|flac|opus|aac|mp4|webm|mov|ogv|pdf|epub|json)$/i;
 
+// ../foundry/scripts/progress.mjs
+var bar = null;
+var vaultLabel = "";
+var phaseLabel = "";
+var done = 0;
+var total = 0;
+function paint(message) {
+  if (!bar) return;
+  const counter = total > 0 ? ` ${Math.min(done, total)}/${total}` : "";
+  const head = phaseLabel ? `${vaultLabel}: ${phaseLabel}${counter}` : vaultLabel;
+  try {
+    bar.update({
+      pct: total > 0 ? Math.min(done / total, 1) : 0,
+      message: message ? `${head} \u2014 ${message}` : head
+    });
+  } catch {
+    bar = null;
+  }
+}
+function begin(label) {
+  vaultLabel = label;
+  phaseLabel = "";
+  done = 0;
+  total = 0;
+  try {
+    const handle = ui?.notifications?.info(label, { progress: true, permanent: true });
+    bar = typeof handle?.update === "function" ? handle : null;
+  } catch {
+    bar = null;
+  }
+}
+function phase(name, count) {
+  phaseLabel = name;
+  done = 0;
+  total = count;
+  paint("");
+}
+function step(message) {
+  done++;
+  paint(message);
+}
+function note(message) {
+  paint(message);
+}
+function end() {
+  if (!bar) return;
+  try {
+    ui?.notifications?.remove?.(bar);
+  } catch {
+  }
+  bar = null;
+  phaseLabel = "";
+}
+
 // ../foundry/scripts/media.mjs
 var CACHE_DIR = "vaults-cache";
 var BATCH_SIZE2 = 25;
@@ -111,6 +355,7 @@ function isCacheable(path) {
   if (!CACHED_EXT_RE.test(path)) return false;
   if (path.startsWith("_") || path.includes("/_")) return false;
   if (/\.preview\.json$/i.test(path)) return false;
+  if (/(^|\/)module\.json$/i.test(path)) return false;
   return true;
 }
 function localFileUrl(vaultId, vaultPath) {
@@ -131,13 +376,19 @@ async function syncImages(host, vault, manifestFiles) {
   }
   const lastImageManifest = host.getVaultState(vault.id).lastImageManifest;
   const last = new Map(Object.entries(lastImageManifest || {}));
+  const baseDir = vaultCacheDir(vault.id);
+  const present = await listCached(baseDir, last.keys());
+  const vanished = [...last.keys()].filter((p) => !present.has(p));
+  for (const path of vanished) last.delete(path);
+  if (vanished.length > 0) {
+    console.info(`Vaults | ${vanished.length} cached file(s) are gone from ${baseDir}; re-fetching.`);
+  }
   const toDownload = [];
   for (const [path, hash] of remoteImages) {
     if (last.get(path) !== hash) toDownload.push(path);
   }
-  const toDelete = [...last.keys()].filter((p) => !remoteImages.has(p));
+  let toDelete = [...last.keys()].filter((p) => !remoteImages.has(p));
   if (toDownload.length === 0 && toDelete.length === 0) return { downloaded: 0, removed: 0, errors: 0 };
-  const baseDir = vaultCacheDir(vault.id);
   const worldRoot = `worlds/${game.world.id}`;
   const dirsNeeded = /* @__PURE__ */ new Set();
   const addChain = (fullPath) => {
@@ -155,6 +406,7 @@ async function syncImages(host, vault, manifestFiles) {
     if (segs.length > 0) addChain(`${baseDir}/${segs.join("/")}`);
   }
   await ensureDirs([...dirsNeeded]);
+  await writeCacheMarker(baseDir, vault);
   const sizeOf = /* @__PURE__ */ new Map();
   for (const f of manifestFiles) sizeOf.set(f.path, f.size ?? 0);
   const chunks = [];
@@ -171,6 +423,7 @@ async function syncImages(host, vault, manifestFiles) {
     chunkBytes += bytes;
   }
   if (chunk.length > 0) chunks.push(chunk);
+  phase("Images", toDownload.length);
   let next = 0;
   const downloaded = [];
   const errors = [];
@@ -187,6 +440,7 @@ async function syncImages(host, vault, manifestFiles) {
             continue;
           }
           try {
+            step(path.split("/").pop());
             await uploadToWorld(baseDir, path, blob);
             downloaded.push(path);
           } catch (err) {
@@ -203,6 +457,10 @@ async function syncImages(host, vault, manifestFiles) {
     console.warn(`Vaults | ${errors.length} image(s) failed to download:`, errors);
   }
   let removed = 0;
+  if (toDelete.length > 0 && !canDelete()) {
+    console.info(`Vaults | ${toDelete.length} cached image(s) are no longer in the vault. Foundry provides no API to delete files, so they stay in ${baseDir} until removed by hand.`);
+    toDelete = [];
+  }
   for (const path of toDelete) {
     try {
       await deleteFromWorld(baseDir, path);
@@ -302,6 +560,47 @@ async function ensureDirs(paths) {
     }
   }
 }
+async function writeCacheMarker(baseDir, vault) {
+  const body = JSON.stringify({
+    label: vault.label ?? null,
+    url: vault.url ?? null,
+    vaultId: vault.id,
+    note: "Cache for one vault. Safe to delete entirely; the next sync re-downloads it."
+  }, null, 2);
+  try {
+    await uploadToWorld(baseDir, "vault-info.json", new Blob([body], { type: "application/json" }));
+  } catch (err) {
+    console.debug(`Vaults | could not write cache marker in ${baseDir}:`, err?.message || err);
+  }
+}
+async function listCached(baseDir, paths) {
+  const byDir = /* @__PURE__ */ new Map();
+  for (const p of paths) {
+    const segs = p.split("/");
+    segs.pop();
+    const dir = segs.join("/");
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir).push(p);
+  }
+  const present = /* @__PURE__ */ new Set();
+  for (const dir of byDir.keys()) {
+    const full = dir ? `${baseDir}/${dir}` : baseDir;
+    let listing;
+    try {
+      listing = await fp().browse("data", full);
+    } catch {
+      continue;
+    }
+    for (const file of listing?.files ?? []) {
+      const name = decodeURIComponent(String(file).split("/").pop());
+      present.add(dir ? `${dir}/${name}` : name);
+    }
+  }
+  return present;
+}
+function canDelete() {
+  return typeof fp().deleteFile === "function";
+}
 async function deleteFromWorld(baseDir, path) {
   const full = `${baseDir}/${path}`;
   const impl = fp();
@@ -364,25 +663,19 @@ function buildPathIndex(manifestFiles) {
       docTargets.set(mdPath, docName);
     }
   }
-  return { paths, idOverrides, docTargets };
+  const hashes = /* @__PURE__ */ new Map();
+  for (const f of manifestFiles) if (f.hash) hashes.set(f.path, f.hash);
+  return { paths, idOverrides, docTargets, hashes };
 }
-function docNameFromBase(base) {
-  if (typeof base !== "string" || !base) return null;
-  if (base.startsWith("Compendium.")) {
-    const parts = base.split(".");
-    return parts.length >= 5 ? parts[3] : null;
-  }
-  return base.split(":")[0] || null;
-}
-async function targetUuid(vaultId, path, index) {
+async function targetUuid(vault, path, index) {
   const docName = index.docTargets?.get(path);
   if (docName) {
-    const id = index.idOverrides?.get(path) ?? await instanceId(vaultId, path);
-    return `${docName}.${id}`;
+    const id = index.idOverrides?.get(path) ?? await instanceId(vault.id, path);
+    return instanceUuid(vault, docName, id);
   }
-  const eId = await entryId(vaultId, path);
-  const pId = index.idOverrides?.get(path) ?? await pageId(vaultId, path);
-  return `JournalEntry.${eId}.JournalEntryPage.${pId}`;
+  const eId = await entryId(vault.id, path);
+  const pId = index.idOverrides?.get(path) ?? await pageId(vault.id, path);
+  return journalPageUuid(vault, eId, pId);
 }
 function logicalPathFromHref(href) {
   const decoded = decodeHtmlEntities(href);
@@ -398,9 +691,9 @@ function decodeHtmlEntities(s) {
   ta.innerHTML = s;
   return ta.value;
 }
-async function transformHtmlForFoundry(vault, html, index) {
-  html = await rewriteWikilinks(vault.id, html, index);
-  html = rewriteMediaSrcs(vault.id, html);
+async function transformHtmlForFoundry(vault, html, index, mediaRefs) {
+  html = await rewriteWikilinks(vault, html, index);
+  html = rewriteMediaSrcs(vault.id, html, index?.hashes, mediaRefs);
   html = rewritePassthroughLinks(vault.id, html);
   html = await applyDomTransforms(html, vault, index);
   return html;
@@ -411,7 +704,7 @@ async function applyDomTransforms(html, vault, index) {
   touched = stripWebOnlyWidgets(doc) || touched;
   touched = flattenBasesTabs(doc) || touched;
   touched = neutralizeEnrichersInCode(doc) || touched;
-  touched = await rewriteBasesCardLinks(doc, vault.id, index) || touched;
+  touched = await rewriteBasesCardLinks(doc, vault, index) || touched;
   touched = rewriteDiceButtons(doc) || touched;
   touched = wrapRestrictedCalloutsAsSecret(doc, vault) || touched;
   return touched ? doc.body.innerHTML : html;
@@ -465,7 +758,18 @@ function neutralizeEnrichersInCode(doc) {
   }
   return touched;
 }
-async function rewriteBasesCardLinks(doc, vaultId, index) {
+function contentLinkAttrs(uuid) {
+  return {
+    // Empty string, matching what TextEditor.createAnchor emits: the selector
+    // tests for presence, not value.
+    "data-link": "",
+    "data-uuid": uuid,
+    // Real content links are draggable, and the drag handler keys off the same
+    // attribute; without this a card cannot be dropped onto the canvas.
+    draggable: "true"
+  };
+}
+async function rewriteBasesCardLinks(doc, vault, index) {
   const cards = doc.querySelectorAll("a.bases-card[href]");
   if (cards.length === 0) return false;
   let touched = false;
@@ -475,23 +779,25 @@ async function rewriteBasesCardLinks(doc, vaultId, index) {
     const path = logicalPathFromHref(href);
     if (!index.paths.has(path)) continue;
     a.classList.add("content-link");
-    a.setAttribute("data-uuid", await targetUuid(vaultId, path, index));
+    for (const [k, v] of Object.entries(contentLinkAttrs(await targetUuid(vault, path, index)))) {
+      a.setAttribute(k, v);
+    }
     a.removeAttribute("href");
     touched = true;
   }
   return touched;
 }
 function wrapRestrictedCalloutsAsSecret(doc, vault) {
-  if (!vault?.dmRole || !Array.isArray(vault.knownRoles) || vault.knownRoles.length === 0) {
+  if (!vault?.playerRole || !Array.isArray(vault.knownRoles) || vault.knownRoles.length === 0) {
     return false;
   }
-  const dmIdx = vault.knownRoles.indexOf(vault.dmRole);
-  if (dmIdx < 0) return false;
-  const restrictedRoles = vault.knownRoles.slice(dmIdx);
+  const playerIdx = vault.knownRoles.indexOf(vault.playerRole);
+  if (playerIdx < 0) return false;
+  const restrictedRoles = vault.knownRoles.slice(playerIdx + 1);
   if (restrictedRoles.length === 0) return false;
   let touched = false;
   for (const role of restrictedRoles) {
-    for (const el of doc.querySelectorAll(".callout.callout-" + cssEscape(role))) {
+    for (const el of doc.querySelectorAll(calloutSelectorFor(role))) {
       const section = doc.createElement("section");
       section.className = "secret";
       el.parentNode.insertBefore(section, el);
@@ -501,10 +807,13 @@ function wrapRestrictedCalloutsAsSecret(doc, vault) {
   }
   return touched;
 }
+function calloutSelectorFor(role) {
+  return ".callout.callout-" + cssEscape(String(role).toLowerCase());
+}
 function cssEscape(s) {
   return String(s).replace(/[^a-zA-Z0-9_-]/g, "\\$&");
 }
-async function rewriteWikilinks(vaultId, html, index) {
+async function rewriteWikilinks(vault, html, index) {
   const matches = [];
   let m;
   ANCHOR_RE.lastIndex = 0;
@@ -525,7 +834,7 @@ async function rewriteWikilinks(vaultId, html, index) {
   }
   const uuidMatches = matches.filter((r) => r.kind === "uuid");
   const resolved = await Promise.all(
-    uuidMatches.map((r) => targetUuid(vaultId, r.path, index))
+    uuidMatches.map((r) => targetUuid(vault, r.path, index))
   );
   uuidMatches.forEach((r, i) => {
     r.uuid = resolved[i];
@@ -537,14 +846,20 @@ async function rewriteWikilinks(vaultId, html, index) {
   }
   return html;
 }
-function rewriteMediaSrcs(vaultId, html) {
+function rewriteMediaSrcs(vaultId, html, hashes, mediaRefs) {
   return html.replace(MEDIA_SRC_RE, (full, tag, before, src, after) => {
     if (!src.startsWith("/")) return full;
     const path = decodeURIComponent(src.replace(/^\//, ""));
     if (!CACHED_EXT_RE.test(path)) return full;
-    return `<${tag}${before}src="${escapeAttr(localFileUrl(vaultId, path))}"${after}>`;
+    mediaRefs?.add(path);
+    const url2 = localFileUrl(vaultId, path) + mediaVersion(hashes, path);
+    return `<${tag}${before}src="${escapeAttr(url2)}"${after}>`;
   });
 }
+function mediaVersion(hashes, path) {
+  const hash = hashes?.get(path);
+  return hash ? `?v=${encodeURIComponent(String(hash).slice(0, 12))}` : "";
+}
 function rewritePassthroughLinks(vaultId, html) {
   return html.replace(ANCHOR_RE, (full, attrs, inner) => {
     const cls = ATTR_CLASS_RE.exec(attrs)?.[1] || "";
@@ -564,46 +879,17 @@ function stripTags(s) {
 // ../foundry/scripts/importer.mjs
 var INDEX_BASENAME = "index";
 var NON_INDEX_SORT_BASE = 1e5;
-var KNOWN_INSTANCE_DOC_TYPES = [
-  "Actor",
-  "Item",
-  "Scene",
-  "JournalEntry",
-  "RollTable",
-  "Macro",
-  "Cards",
-  "Playlist"
-];
-function inferInstanceDocName(base) {
-  if (typeof base !== "string" || !base) return null;
-  const raw = base.includes(".") ? base.split(".").at(-2) : base.split(":")[0];
-  return KNOWN_INSTANCE_DOC_TYPES.find((t) => t.toLowerCase() === raw?.toLowerCase()) ?? null;
-}
-async function ensureFolderChain(vault, segments) {
-  const rootName = vault.rootFolder || vault.label || "Vault";
-  const rootKey = `${vault.id}/__root__/${rootName}`;
-  const rootFId = await folderId(vault.id, rootKey);
-  await upsertFolder(rootFId, rootName, null);
-  let parentId = rootFId;
-  let acc = rootKey;
+async function ensureFolderChain(target, vault, segments) {
+  let parentId = null;
+  let acc = `${vault.id}/__root__/${vault.rootFolder || vault.label || "Vault"}`;
   for (const seg of segments) {
     acc += "/" + seg;
     const fId = await folderId(vault.id, acc);
-    await upsertFolder(fId, seg, parentId);
+    await target.putFolder("JournalEntry", { _id: fId, name: seg, folder: parentId });
     parentId = fId;
   }
   return parentId;
 }
-async function upsertFolder(id, name, parentId) {
-  const existing = game.folders.get(id);
-  if (existing) {
-    if (existing.name !== name || existing.folder?.id !== parentId) {
-      await existing.update({ name, folder: parentId });
-    }
-    return existing;
-  }
-  return Folder.create({ _id: id, name, type: "JournalEntry", folder: parentId }, { keepId: true });
-}
 function buildFolderInfo(mdPaths) {
   const map = /* @__PURE__ */ new Map();
   const ensure = (folderPath) => {
@@ -629,8 +915,8 @@ function buildFolderInfo(mdPaths) {
 function isIndexFile(filename) {
   return filename.replace(/\.md$/i, "") === INDEX_BASENAME;
 }
-async function upsertFile(vault, path, body, index, meta, folderInfo) {
-  let html = await transformHtmlForFoundry(vault, body, index);
+async function upsertFile(target, vault, path, body, index, meta, folderInfo, mediaRefs) {
+  let html = await transformHtmlForFoundry(vault, body, index, mediaRefs);
   html = await appendInstanceDocLink(html, vault, path, meta);
   const segs = path.split("/");
   const filename = segs.pop();
@@ -638,7 +924,7 @@ async function upsertFile(vault, path, body, index, meta, folderInfo) {
   const fInfo = folderInfo?.get(folderPath);
   const leaf = !!fInfo && folderPath !== "" && !fInfo.hasSubfolders;
   const hostSegs = leaf ? segs.slice(0, -1) : segs;
-  const folderFId = await ensureFolderChain(vault, hostSegs);
+  const folderFId = await ensureFolderChain(target, vault, hostSegs);
   const entryName = folderPath === "" ? vault.rootFolder || vault.label || "Vault" : fInfo?.displayName || segs[segs.length - 1] || "";
   const pageName = meta?.title || filename.replace(/\.md$/i, "");
   const eId = await entryId(vault.id, path);
@@ -666,311 +952,555 @@ async function upsertFile(vault, path, body, index, meta, folderInfo) {
     // page in it). See reconcileOwnership below.
     ...pageOwnership !== null ? { ownership: { default: pageOwnership } } : {}
   };
-  const existing = game.journal.get(eId);
+  const existing = await target.get("JournalEntry", eId);
   if (existing) {
-    const entryPatch = {};
-    if (existing.name !== entryName) entryPatch.name = entryName;
-    if (existing.folder?.id !== folderFId) entryPatch.folder = folderFId;
-    if (Object.keys(entryPatch).length > 0) await existing.update(entryPatch);
-    const existingPage = existing.pages.get(pId);
-    if (existingPage) await existingPage.update(pageData);
-    else await existing.createEmbeddedDocuments("JournalEntryPage", [pageData], { keepId: true });
+    const pages = (existing.pages ?? []).filter((pg) => pg._id !== pId);
+    pages.push(pageData);
+    await target.put("JournalEntry", {
+      ...existing,
+      name: entryName,
+      folder: folderFId,
+      pages,
+      flags
+    });
     return "modified";
   }
-  await JournalEntry.create({
+  return target.put("JournalEntry", {
     _id: eId,
     name: entryName,
     folder: folderFId,
     pages: [pageData],
     flags,
-    // Bootstrap the entry visible at the page's tier so player-visible
-    // pages aren't hidden in the gap between create and the post-sync
-    // reconcileOwnership pass. Mixed-tier folders converge to max(pages)
-    // via reconcile.
+    // Bootstrap the entry visible at the page's tier so player-visible pages
+    // aren't hidden in the gap before reconcileEntries runs. Mixed-tier
+    // folders converge to max(pages) there.
     ...pageOwnership !== null ? { ownership: { default: pageOwnership } } : {}
-  }, { keepId: true });
-  return "added";
+  });
 }
 function pageOwnershipLevelFor(vault, pageRole) {
-  if (!vault.dmRole || !vault.knownRoles?.length) return null;
-  const dmIdx = vault.knownRoles.indexOf(vault.dmRole);
-  if (dmIdx < 0) return null;
+  if (!vault.playerRole || !vault.knownRoles?.length) return null;
+  const playerIdx = vault.knownRoles.indexOf(vault.playerRole);
+  if (playerIdx < 0) return null;
   const pageIdx = pageRole ? vault.knownRoles.indexOf(pageRole) : -1;
   const effectiveIdx = pageIdx < 0 ? 0 : pageIdx;
-  return effectiveIdx < dmIdx ? CONST.DOCUMENT_OWNERSHIP_LEVELS.OBSERVER : CONST.DOCUMENT_OWNERSHIP_LEVELS.NONE;
+  return effectiveIdx <= playerIdx ? CONST.DOCUMENT_OWNERSHIP_LEVELS.OBSERVER : CONST.DOCUMENT_OWNERSHIP_LEVELS.NONE;
 }
-async function reconcileOwnership(vault, bodyMetaIndex) {
-  if (!vault.dmRole || !vault.knownRoles?.length) return;
-  const ours = game.journal.contents.filter(
-    (j) => j.getFlag(MODULE_ID, "vaultId") === vault.id
-  );
+async function reconcileEntries(target, vault, folderInfo, bodyMetaIndex) {
+  const ours = (await target.contents("JournalEntry")).filter((j) => j.flags?.[MODULE_ID]?.vaultId === vault.id);
+  const gated = !!vault.playerRole && !!vault.knownRoles?.length;
   for (const entry of ours) {
-    let entryMax = null;
-    for (const page of entry.pages.contents) {
-      const pPath = page.getFlag(MODULE_ID, "path");
-      if (!pPath) continue;
-      const bodyPath = pPath.replace(/\.md$/i, ".body.html");
-      const meta = bodyMetaIndex.get(bodyPath);
-      if (!meta) continue;
-      const level = pageOwnershipLevelFor(vault, meta.role);
-      if (level === null) continue;
-      if (page.ownership?.default !== level) {
-        try {
-          await page.update({ ownership: { default: level } });
-        } catch (err) {
-          console.warn(`Vaults | reconcile ownership ${pPath} \u2192 ${level} failed:`, err);
-        }
-      }
-      if (entryMax === null || level > entryMax) entryMax = level;
-    }
-    if (entryMax !== null && entry.ownership?.default !== entryMax) {
+    const patched = reconcileOwnershipData(gated ? vault : null, entry, bodyMetaIndex);
+    const folder = await expectedFolder(target, vault, entry, folderInfo);
+    if (folder !== void 0 && folder !== (patched.folder ?? null)) patched.folder = folder;
+    if (JSON.stringify(patched) !== JSON.stringify(entry)) {
       try {
-        await entry.update({ ownership: { default: entryMax } });
+        await target.put("JournalEntry", patched);
       } catch (err) {
-        console.warn(`Vaults | reconcile entry ownership for ${entry.name} \u2192 ${entryMax} failed:`, err);
+        console.warn(`Vaults | reconcile failed for ${entry.name}:`, err);
       }
     }
   }
 }
-async function reconcileEntryPlacement(vault, folderInfo) {
-  const ours = game.journal.contents.filter(
-    (j) => j.getFlag(MODULE_ID, "vaultId") === vault.id
-  );
-  for (const entry of ours) {
-    const firstPage = entry.pages.contents[0];
-    const path = firstPage?.getFlag(MODULE_ID, "path");
-    if (!path) continue;
-    const segs = path.split("/");
-    segs.pop();
-    const folderPath = segs.join("/");
-    const fInfo = folderInfo?.get(folderPath);
-    const leaf = !!fInfo && folderPath !== "" && !fInfo.hasSubfolders;
-    const hostSegs = leaf ? segs.slice(0, -1) : segs;
-    const expectedFolderId = await ensureFolderChain(vault, hostSegs);
-    if (entry.folder?.id !== expectedFolderId) {
-      try {
-        await entry.update({ folder: expectedFolderId });
-      } catch (err) {
-        console.warn(`Vaults | re-place ${path} \u2192 ${expectedFolderId} failed:`, err);
-      }
-    }
-  }
+function reconcileOwnershipData(vault, entry, bodyMetaIndex) {
+  const patched = structuredClone(entry);
+  if (!vault) return patched;
+  let entryMax = null;
+  for (const page of patched.pages ?? []) {
+    const pPath = page.flags?.[MODULE_ID]?.path;
+    if (!pPath) continue;
+    const meta = bodyMetaIndex.get(pPath.replace(/\.md$/i, ".body.html"));
+    if (!meta) continue;
+    const level = pageOwnershipLevelFor(vault, meta.role);
+    if (level === null) continue;
+    page.ownership = { ...page.ownership, default: level };
+    if (entryMax === null || level > entryMax) entryMax = level;
+  }
+  if (entryMax !== null) patched.ownership = { ...patched.ownership, default: entryMax };
+  return patched;
+}
+async function expectedFolder(target, vault, entry, folderInfo) {
+  const path = entry.pages?.[0]?.flags?.[MODULE_ID]?.path;
+  if (!path) return void 0;
+  const segs = path.split("/");
+  segs.pop();
+  const folderPath = segs.join("/");
+  const fInfo = folderInfo?.get(folderPath);
+  const leaf = !!fInfo && folderPath !== "" && !fInfo.hasSubfolders;
+  return ensureFolderChain(target, vault, leaf ? segs.slice(0, -1) : segs);
 }
-async function deleteFile(vault, path) {
+async function deleteFile(target, vault, path) {
   const eId = await entryId(vault.id, path);
   const pId = await pageId(vault.id, path);
-  const entry = game.journal.get(eId);
+  const entry = await target.get("JournalEntry", eId);
   if (!entry) return;
-  const page = entry.pages.get(pId);
-  if (page) await page.delete();
-  if (entry.pages.size === 0) await entry.delete();
-}
-async function deleteVaultJournals(vaultId) {
-  const journals = game.journal.contents.filter((j) => j.getFlag(MODULE_ID, "vaultId") === vaultId);
-  for (const j of journals) await j.delete();
-  const folders = game.folders.contents.filter((f) => f.type === "JournalEntry");
-  for (const f of folders.reverse()) {
-    if (f.contents.length === 0 && f.children.length === 0) {
-      const root = await folderId(vaultId, `${vaultId}/__root__/${f.name}`);
-      if (f.id === root) await f.delete();
-    }
-  }
+  const pages = (entry.pages ?? []).filter((pg) => pg._id !== pId);
+  if (pages.length === 0) await target.remove("JournalEntry", eId);
+  else await target.put("JournalEntry", { ...entry, pages });
 }
 async function appendInstanceDocLink(html, vault, path, meta) {
   const base = meta?.foundry?.base;
-  const docName = inferInstanceDocName(base);
+  const docName = docNameFromBase(base);
   if (!docName) return html;
   const idOverride = meta?.foundry?.id;
   const docId = typeof idOverride === "string" && idOverride ? idOverride : await instanceId(vault.id, path);
   const label = meta?.title || path.split("/").pop().replace(/\.md$/i, "");
+  const uuid = instanceUuid(vault, docName, docId);
   return html + `
-<p class="vaults-instance-link"><em>Foundry document:</em> @UUID[${docName}.${docId}]{${escapeBraces(label)}}</p>`;
+<p class="vaults-instance-link"><em>Foundry document:</em> @UUID[${uuid}]{${escapeBraces(label)}}</p>`;
+}
+
+// ../foundry/scripts/moulinette.mjs
+var MOULINETTE_PREFIX = "@moulinette/";
+var CACHED_COLLECTION = "mou-cloud-cached";
+function parseMoulinetteRef(s) {
+  if (typeof s !== "string" || !s.startsWith(MOULINETTE_PREFIX)) return null;
+  const [pack, ...fileParts] = s.slice(MOULINETTE_PREFIX.length).split("/");
+  const file = fileParts.join("/");
+  if (!pack || !file) return null;
+  return { pack, file };
+}
+async function loadIndex(log) {
+  const mod = game.modules?.get("moulinette");
+  if (!mod) {
+    log("references need the Moulinette module, which is not installed");
+    return null;
+  }
+  if (!mod.active) {
+    log("references need the Moulinette module, which is installed but not enabled in this world");
+    return null;
+  }
+  const collection = mod.collections?.find((c) => c.getId?.() === CACHED_COLLECTION);
+  if (!collection?.initialize || !collection.selectAsset || !collection.downloadAsset) {
+    log("Moulinette is installed but its asset index is not where we expect; skipping");
+    return null;
+  }
+  try {
+    await collection.initialize();
+  } catch (err) {
+    log(`could not load the Moulinette index: ${err?.message ?? err}`);
+    return null;
+  }
+  const assets = mod.cache?.allAssets;
+  if (!Array.isArray(assets)) {
+    log("Moulinette's asset index is not a list; skipping");
+    return null;
+  }
+  return { mod, collection, assets };
+}
+function findAsset(ref, index, log) {
+  const match = index.assets.find(
+    (a) => String(a?.pack_id) === ref.pack && a?.url === ref.file
+  );
+  if (!match) {
+    log(`no asset ${ref.file} in pack ${ref.pack} \u2014 not subscribed, or it moved`);
+    return null;
+  }
+  return match;
+}
+async function resolveMoulinetteDocument(spec, warn) {
+  const log = (msg) => warn(msg);
+  const ref = parseMoulinetteRef(MOULINETTE_PREFIX + spec);
+  if (!ref) {
+    log(`malformed reference '${spec}' \u2014 expected <pack_ref>/<filepath>`);
+    return null;
+  }
+  const index = await loadIndex(log);
+  if (!index) return null;
+  const asset = findAsset(ref, index, log);
+  if (!asset) return null;
+  try {
+    const descriptor = await index.mod.cloudclient.apiGET(`/asset/${asset.id}`, {
+      session: index.mod.getSessionId()
+    });
+    const dl = await index.collection.downloadAsset(descriptor);
+    if (!dl?.message) {
+      log(`${ref.pack}/${ref.file} is not a document; foundry.base needs one`);
+      return null;
+    }
+    return JSON.parse(dl.message);
+  } catch (err) {
+    log(`could not read ${ref.pack}/${ref.file}: ${err?.message ?? err}`);
+    return null;
+  }
+}
+async function resolveOne(ref, index, log) {
+  const match = findAsset(ref, index, log);
+  if (!match) return null;
+  try {
+    note(`Moulinette: ${ref.file.split("/").pop()}`);
+    const path = await index.collection.selectAsset(match);
+    if (!path) {
+      log(`${ref.pack}/${ref.file} is not a media asset; only files can be referenced`);
+      return null;
+    }
+    return path;
+  } catch (err) {
+    log(`download failed for ${ref.pack}/${ref.file}: ${err?.message ?? err}`);
+    return null;
+  }
+}
+async function resolveMoulinetteRefs(value, warn) {
+  const cache = /* @__PURE__ */ new Map();
+  const stats = { resolved: 0, unresolved: 0 };
+  const seenWarnings = /* @__PURE__ */ new Set();
+  const log = (msg) => {
+    if (seenWarnings.has(msg)) return;
+    seenWarnings.add(msg);
+    warn(msg);
+  };
+  let index;
+  const lookup = async (s) => {
+    if (cache.has(s)) return cache.get(s);
+    const ref = parseMoulinetteRef(s);
+    let path = null;
+    if (!ref) {
+      log(`malformed reference '${s}' \u2014 expected @moulinette/<pack_ref>/<filepath>`);
+    } else {
+      if (index === void 0) index = await loadIndex(log);
+      if (index) path = await resolveOne(ref, index, log);
+    }
+    cache.set(s, path);
+    if (path) stats.resolved++;
+    else stats.unresolved++;
+    return path;
+  };
+  const walk = async (node) => {
+    if (Array.isArray(node)) {
+      const kept = [];
+      for (const item of node) {
+        if (typeof item === "string" && item.startsWith(MOULINETTE_PREFIX)) {
+          const path = await lookup(item);
+          if (path) kept.push(path);
+          continue;
+        }
+        if (await walk(item)) kept.push(item);
+      }
+      node.length = 0;
+      node.push(...kept);
+      return true;
+    }
+    if (node && typeof node === "object") {
+      let viable = true;
+      for (const key of Object.keys(node)) {
+        const v = node[key];
+        if (typeof v === "string" && v.startsWith(MOULINETTE_PREFIX)) {
+          const path = await lookup(v);
+          if (path) node[key] = path;
+          else {
+            delete node[key];
+            viable = false;
+          }
+          continue;
+        }
+        if (!await walk(v)) delete node[key];
+      }
+      return viable;
+    }
+    return true;
+  };
+  await walk(value);
+  return stats;
 }
 
 // ../foundry/scripts/instance.mjs
+var CORE_DESCRIPTION_FIELDS = {
+  RollTable: "description",
+  Playlist: "description"
+};
+function descriptionPathFor(docName, systemId) {
+  return CORE_DESCRIPTION_FIELDS[docName] ?? DESCRIPTION_FIELDS[systemId]?.[docName];
+}
 var DESCRIPTION_FIELDS = {
   dnd5e: {
     Actor: "system.details.biography.value",
     Item: "system.description.value"
   }
 };
-var CLONE_SUPPORTED_DOCS = /* @__PURE__ */ new Set(["Actor", "Item"]);
-var BLANK_DOC_TYPES = /* @__PURE__ */ new Set([
-  "Actor",
-  "Item",
-  "Scene",
-  "JournalEntry",
-  "RollTable",
-  "Macro",
-  "Cards",
-  "Playlist"
-]);
-var COLLECTION_FOR = {
-  Actor: () => game.actors,
-  Item: () => game.items,
-  Scene: () => game.scenes,
-  JournalEntry: () => game.journal,
-  RollTable: () => game.tables,
-  Macro: () => game.macros,
-  Cards: () => game.cards,
-  Playlist: () => game.playlists
-};
-async function applyInstance(vault, vaultPath, meta) {
+function sceneBackgroundSrc(data) {
+  const levels = Array.isArray(data?.levels) ? data.levels : [];
+  const initial = levels.find((l) => l._id === data.initialLevel) ?? levels[0];
+  return initial?.background?.src || data?.background?.src || null;
+}
+async function attachSceneThumb(data, docName, vaultPath) {
+  if (docName !== "Scene" || data.thumb) return;
+  const src = sceneBackgroundSrc(data);
+  if (!src) return;
+  try {
+    const { thumb } = await foundry.helpers.media.ImageHelper.createThumbnail(
+      src,
+      { width: 300, height: 100 }
+    );
+    if (thumb) data.thumb = thumb;
+  } catch (err) {
+    console.warn(`Vaults | could not make a scene thumbnail for ${vaultPath}:`, err);
+  }
+}
+function wantsJournalNote(docName, fm) {
+  return docName === "Scene" && fm?.journal !== false;
+}
+async function applyInstance(target, vault, vaultPath, meta, { forceFull = false } = {}) {
   const fm = meta?.foundry;
-  if (!fm || typeof fm !== "object") return;
-  const parsed = parseFoundryBase(fm.base);
-  if (!parsed) return;
-  let docName;
-  let baseData;
-  if (parsed.kind === "uuid") {
-    const template = await safeFromUuid(parsed.uuid);
-    if (!template) {
-      console.warn(`Vaults | foundry.base: ${vaultPath} \u2192 ${parsed.uuid} did not resolve; skipping.`);
-      return;
-    }
-    docName = template.documentName;
-    if (!CLONE_SUPPORTED_DOCS.has(docName)) {
-      console.warn(
-        `Vaults | foundry.base: ${vaultPath} \u2192 ${parsed.uuid} is a ${docName}; clone-from-UUID only supports ${[...CLONE_SUPPORTED_DOCS].join(", ")}.`
-      );
-      return;
-    }
-    try {
-      baseData = template.toObject();
-    } catch (err) {
-      console.warn(`Vaults | foundry.base: could not read template ${parsed.uuid}:`, err);
-      return;
-    }
-    delete baseData._id;
-  } else {
-    docName = parsed.docName;
-    baseData = parsed.subtype ? { type: parsed.subtype } : {};
-  }
-  const collection = COLLECTION_FOR[docName]?.();
-  if (!collection) {
-    console.warn(`Vaults | foundry.base: no world collection for ${docName}; skipping ${vaultPath}.`);
-    return;
+  if (!fm || typeof fm !== "object") return null;
+  if (fm.base === void 0 || fm.base === null) return null;
+  const specs = Array.isArray(fm.base) ? fm.base : [fm.base];
+  const candidates = specs.map(parseFoundryBase);
+  if (candidates.length === 0 || candidates.some((c) => !c)) {
+    console.warn(
+      `Vaults | foundry.base: ${vaultPath} \u2192 unrecognised base ${JSON.stringify(fm.base)}; expected a UUID ("Compendium.<pkg>.<pack>.Actor.<id>") or a type ("Actor:npc"), or a list of those. Skipping.`
+    );
+    return { ok: false, reason: "unparseable" };
+  }
+  const docNames = new Set(candidates.map(docNameOf).filter(Boolean));
+  const docName = [...docNames][0] ?? null;
+  if (!docName) {
+    console.warn(`Vaults | foundry.base: ${vaultPath} \u2192 could not read a document type from ${JSON.stringify(fm.base)}. Skipping.`);
+    return { ok: false, reason: "unparseable" };
+  }
+  if (docNames.size > 1) {
+    console.warn(
+      `Vaults | foundry.base: ${vaultPath} \u2192 every entry must name the same document type, got ${[...docNames].join(", ")}. Skipping.`
+    );
+    return { ok: false, reason: "mixed-types" };
+  }
+  if (!CONFIG[docName]) {
+    console.warn(`Vaults | foundry.base: this world has no ${docName} documents; skipping ${vaultPath}.`);
+    return { ok: false, reason: "no-collection" };
   }
-  const docClass = CONFIG[docName].documentClass;
   const id = typeof fm.id === "string" && fm.id ? fm.id : await instanceId(vault.id, vaultPath);
   const dataJson = fm.data_json && typeof fm.data_json === "object" && !Array.isArray(fm.data_json) ? rewriteVaultPaths(structuredClone(fm.data_json), vault.id) : null;
-  if (dataJson) await ensureEmbeddedIds(dataJson, vault.id, vaultPath);
+  const moulinetteWarn = (msg) => console.warn(`Vaults | moulinette: ${vaultPath}: ${msg}`);
+  if (dataJson) await resolveMoulinetteRefs(dataJson, moulinetteWarn);
+  if (dataJson) {
+    await resolveItemUuids(dataJson, vaultPath);
+    await ensureEmbeddedIds(dataJson, vault.id, vaultPath);
+  }
   const derived = {};
-  const overlay = await buildOverlay(vault, vaultPath, meta, docName, derived);
+  const overlay = await buildOverlay(target, vault, vaultPath, meta, docName, derived);
   const tokenFloor = derived.tokenTexture && !dataJson?.prototypeToken?.texture?.src && !fm?.data?.prototypeToken?.texture?.src ? { prototypeToken: { texture: { src: derived.tokenTexture } } } : null;
-  const existing = collection.get(id);
+  const existing = await target.get(docName, id);
   if (existing) {
     const base = tokenFloor ? deepMerge(structuredClone(tokenFloor), dataJson ?? {}) : dataJson;
     const updatePatch = base ? deepMerge(structuredClone(base), overlay) : overlay;
+    if (wantsJournalNote(docName, fm)) {
+      await attachJournalNote(updatePatch, {
+        width: updatePatch.width ?? existing.width,
+        height: updatePatch.height ?? existing.height,
+        padding: updatePatch.padding ?? existing.padding,
+        grid: updatePatch.grid ?? { size: existing.grid?.size }
+      }, vault, vaultPath, meta);
+    }
+    if (!forceFull) delete updatePatch.folder;
     try {
-      await existing.update(updatePatch);
+      const merged = deepMerge(structuredClone(existing), updatePatch);
+      if (sceneBackgroundSrc(merged) !== sceneBackgroundSrc(existing) || !existing.thumb) {
+        await attachSceneThumb(merged, docName, vaultPath);
+      }
+      await target.put(docName, merged);
     } catch (err) {
       console.warn(`Vaults | foundry.base update failed for ${vaultPath}:`, err);
+      return { ok: false, reason: "update-failed" };
     }
-    return;
+    return { ok: true, action: "updated" };
   }
+  const resolved = await resolveBase(candidates, vaultPath);
+  if (!resolved) return { ok: false, reason: "unresolved" };
+  const baseData = resolved.data;
+  const baseItems = Array.isArray(baseData.items) ? baseData.items : null;
   if (tokenFloor) deepMerge(baseData, tokenFloor);
   if (dataJson) deepMerge(baseData, dataJson);
   baseData._id = id;
   deepMerge(baseData, overlay);
+  if (wantsJournalNote(docName, fm)) {
+    await attachJournalNote(baseData, baseData, vault, vaultPath, meta);
+  }
+  if (baseItems && baseData.items !== baseItems) {
+    baseData.items = mergeItemsById(baseItems, baseData.items);
+  }
   try {
-    await docClass.create(baseData, { keepId: true, keepEmbeddedIds: true });
+    await attachSceneThumb(baseData, docName, vaultPath);
+    await target.put(docName, baseData);
   } catch (err) {
     console.warn(`Vaults | foundry.base create failed for ${vaultPath}:`, err);
-    return;
+    return { ok: false, reason: "create-failed" };
   }
-  if (docName === "Scene") {
-    const created = collection.get(id);
-    if (created && !created.thumb) {
-      try {
-        const { thumb } = await created.createThumbnail();
-        if (thumb) await created.update({ thumb });
-      } catch (err) {
-        console.warn(`Vaults | scene thumbnail generation failed for ${vaultPath}:`, err);
+  const created = await target.get(docName, id);
+  if (!created) {
+    console.warn(
+      `Vaults | foundry.base: ${vaultPath} \u2192 ${docName} ${id} was rejected on create; no document exists. Foundry logged the validation error separately (look for "DataModelValidationError" above).`
+    );
+    return { ok: false, reason: "create-rejected" };
+  }
+  if (docName === "Scene" && (!created.thumb || resolved.from)) {
+    try {
+      const { thumb } = await created.createThumbnail();
+      if (thumb) await created.update({ thumb });
+      else console.warn(`Vaults | scene thumbnail came back empty for ${vaultPath}`);
+    } catch (err) {
+      console.warn(`Vaults | scene thumbnail generation failed for ${vaultPath}:`, err);
+    }
+  }
+  return { ok: true, action: "created", skew: resolved.skew ?? null };
+}
+function generationSkew(data, ref) {
+  const exported = Number.parseInt(String(data?._stats?.coreVersion ?? ""), 10);
+  const world = Number(game.release?.generation);
+  if (!Number.isFinite(exported) || !Number.isFinite(world) || exported === world) return null;
+  return { ref, exported: data._stats.coreVersion, world: game.release.generation };
+}
+async function resolveBase(candidates, vaultPath) {
+  const tried = [];
+  for (const parsed of candidates) {
+    if (parsed.kind === "blank") {
+      if (tried.length > 0) {
+        console.info(
+          `Vaults | foundry.base: ${vaultPath} \u2192 fell back to blank ${parsed.docName}${parsed.subtype ? `:${parsed.subtype}` : ""} after ${tried.length} earlier candidate(s) did not resolve.`
+        );
       }
+      return { data: parsed.subtype ? { type: parsed.subtype } : {}, from: null };
     }
+    if (parsed.kind === "moulinette") {
+      const data2 = await resolveMoulinetteDocument(
+        parsed.ref,
+        (msg) => console.warn(`Vaults | moulinette: ${vaultPath}: ${msg}`)
+      );
+      if (!data2) {
+        tried.push(`@moulinette/${parsed.ref} \u2014 did not resolve`);
+        continue;
+      }
+      const skew = generationSkew(data2, parsed.ref);
+      delete data2._id;
+      if (tried.length > 0) {
+        console.info(
+          `Vaults | foundry.base: ${vaultPath} \u2192 using @moulinette/${parsed.ref}; earlier candidate(s) skipped:
+  ` + tried.join("\n  ")
+        );
+      }
+      return { data: data2, from: `@moulinette/${parsed.ref}`, skew };
+    }
+    const template = await safeFromUuid(parsed.uuid);
+    if (!template) {
+      tried.push(`${parsed.uuid} \u2014 did not resolve`);
+      continue;
+    }
+    if (!BLANK_DOC_TYPES.includes(template.documentName)) {
+      tried.push(`${parsed.uuid} \u2014 is a ${template.documentName}; vaults can instantiate ${BLANK_DOC_TYPES.join(", ")}`);
+      continue;
+    }
+    let data;
+    try {
+      data = template.toObject();
+    } catch (err) {
+      tried.push(`${parsed.uuid} \u2014 unreadable: ${err.message}`);
+      continue;
+    }
+    delete data._id;
+    const sourceUuid = template.uuid ?? parsed.uuid;
+    if (sourceUuid.startsWith("Compendium.")) {
+      data._stats = { ...data._stats, compendiumSource: sourceUuid };
+    }
+    const via = sourceUuid === parsed.uuid ? "" : ` (redirected to ${sourceUuid})`;
+    if (tried.length > 0) {
+      console.info(
+        `Vaults | foundry.base: ${vaultPath} \u2192 using ${parsed.uuid}${via}; earlier candidate(s) skipped:
+  ` + tried.join("\n  ")
+      );
+    }
+    return { data, from: sourceUuid };
   }
+  console.warn(
+    `Vaults | foundry.base: ${vaultPath} \u2192 no candidate resolved:
+  ` + tried.join("\n  ") + `
+  Add a blank-document entry (e.g. "Actor:npc") as the last item so this can't fail.`
+  );
+  return null;
+}
+async function missingBasePackages(metas) {
+  const pageSpecs = [];
+  for (const meta of metas) {
+    const base = meta?.foundry?.base;
+    if (base === void 0 || base === null) continue;
+    const specs = (Array.isArray(base) ? base : [base]).filter((s) => typeof s === "string");
+    if (specs.length === 0) continue;
+    if (specs.some((s) => !s.includes("."))) continue;
+    if (specs.some((s) => !s.startsWith("Compendium."))) continue;
+    if (specs.some((s) => s.split(".")[1] === "world")) continue;
+    pageSpecs.push(specs);
+  }
+  if (pageSpecs.length === 0) return /* @__PURE__ */ new Map();
+  const PROBES_PER_PACK = 3;
+  const packOf = (spec) => spec.split(".").slice(1, 3).join(".");
+  const probes = /* @__PURE__ */ new Map();
+  for (const specs of pageSpecs) {
+    for (const spec of specs) {
+      const pack = packOf(spec);
+      const chosen = probes.get(pack) ?? [];
+      if (chosen.length < PROBES_PER_PACK && !chosen.includes(spec)) chosen.push(spec);
+      probes.set(pack, chosen);
+    }
+  }
+  const reachable = /* @__PURE__ */ new Map();
+  for (const [pack, specs] of probes) {
+    let ok = false;
+    for (const spec of specs) if (await safeFromUuid(spec)) {
+      ok = true;
+      break;
+    }
+    reachable.set(pack, ok);
+  }
+  const missing = /* @__PURE__ */ new Map();
+  for (const specs of pageSpecs) {
+    if (specs.some((s) => reachable.get(packOf(s)))) continue;
+    for (const pkg of new Set(specs.map((s) => s.split(".")[1]).filter(Boolean))) {
+      missing.set(pkg, (missing.get(pkg) ?? 0) + 1);
+    }
+  }
+  return missing;
 }
-function parseFoundryBase(spec) {
-  if (typeof spec !== "string" || !spec) return null;
-  if (spec.includes(".")) return { kind: "uuid", uuid: spec };
-  const [typeRaw, subtype] = spec.split(":");
-  const docName = [...BLANK_DOC_TYPES].find((t) => t.toLowerCase() === typeRaw.toLowerCase());
-  if (!docName) return null;
-  return { kind: "blank", docName, subtype: subtype || void 0 };
-}
-async function deleteInstance(vault, vaultPath) {
+async function deleteInstance(target, vault, vaultPath) {
   const id = await instanceId(vault.id, vaultPath);
-  for (const getCollection of Object.values(COLLECTION_FOR)) {
-    const collection = getCollection();
-    const doc = collection?.get(id);
+  for (const docName of BLANK_DOC_TYPES) {
+    const doc = await target.get(docName, id);
     if (!doc) continue;
-    if (doc.getFlag(MODULE_ID, "vaultId") !== vault.id) continue;
+    if (doc.flags?.[MODULE_ID]?.vaultId !== vault.id) continue;
     try {
-      await doc.delete();
+      await target.remove(docName, id);
     } catch (err) {
-      console.warn(`Vaults | failed to delete ${doc.documentName} for ${vaultPath}:`, err);
+      console.warn(`Vaults | failed to delete ${docName} for ${vaultPath}:`, err);
     }
   }
 }
-async function deleteVaultInstances(vaultId) {
-  for (const [docName, getCollection] of Object.entries(COLLECTION_FOR)) {
-    const collection = getCollection();
-    if (!collection) continue;
-    const ours = collection.contents.filter((d) => d.getFlag(MODULE_ID, "vaultId") === vaultId);
-    for (const doc of ours) {
-      try {
-        await doc.delete();
-      } catch (err) {
-        console.warn(`Vaults | failed to delete ${docName} ${doc.id}:`, err);
-      }
-    }
-  }
-  for (const docName of BLANK_DOC_TYPES) {
-    const fId = await instanceFolderId(vaultId, docName);
-    const folder = game.folders.get(fId);
-    if (!folder || folder.type !== docName) continue;
-    if (folder.contents.length > 0 || folder.children.length > 0) continue;
+async function ensureInstanceFolder(target, vault, docName, subPath = "") {
+  let parentId = null;
+  let key = `${vault.id}/__instance__/${docName}`;
+  for (const segment of splitFolderPath(subPath)) {
+    key += `/${segment}`;
+    const fId = await folderId(vault.id, key);
     try {
-      await folder.delete();
+      await target.putFolder(docName, { _id: fId, name: segment, folder: parentId });
     } catch (err) {
-      console.warn(`Vaults | failed to delete ${docName} folder:`, err);
+      console.warn(`Vaults | could not create ${docName} folder for ${vault.label}:`, err);
+      return parentId;
     }
+    parentId = fId;
   }
+  return parentId;
 }
-async function instanceFolderId(vaultId, docName) {
-  return folderId(vaultId, `${vaultId}/__instance__/${docName}`);
+function splitFolderPath(subPath) {
+  return typeof subPath === "string" ? subPath.split("/").map((s) => s.trim()).filter(Boolean) : [];
 }
-async function ensureInstanceFolder(vault, docName) {
-  const fId = await instanceFolderId(vault.id, docName);
-  const existing = game.folders.get(fId);
-  const name = vault.rootFolder || vault.label || "Vault";
-  if (existing) {
-    if (existing.name !== name) {
-      try {
-        await existing.update({ name });
-      } catch (err) {
-        console.warn(`Vaults | could not rename ${docName} folder for ${vault.label}:`, err);
-      }
-    }
-    return fId;
-  }
-  try {
-    await Folder.create({ _id: fId, name, type: docName, folder: null }, { keepId: true });
-    return fId;
-  } catch (err) {
-    console.warn(`Vaults | could not create ${docName} folder for ${vault.label}:`, err);
-    return null;
-  }
+function instanceSubPath(vaultPath, meta) {
+  const override = meta?.foundry?.folder;
+  if (typeof override === "string" && override.trim()) return override;
+  return folderOfPath(vaultPath);
 }
-async function buildOverlay(vault, vaultPath, meta, docName, derived = {}) {
+async function buildOverlay(target, vault, vaultPath, meta, docName, derived = {}) {
   const overlay = {
     // Prefer the page's frontmatter `title:` over the filename — the wiki
     // already treats title as the page's display name, and a doc named
     // "Potion of Healing (Mossfoot Brew)" reads better in the Foundry
     // sidebar than "Healing Potion".
     name: meta.title || baseName(vaultPath),
-    folder: await ensureInstanceFolder(vault, docName),
+    folder: await ensureInstanceFolder(target, vault, docName, instanceSubPath(vaultPath, meta)),
     flags: { [MODULE_ID]: { vaultId: vault.id, path: vaultPath } }
   };
   if (meta.image) {
@@ -981,42 +1511,45 @@ async function buildOverlay(vault, vaultPath, meta, docName, derived = {}) {
     }
   }
   const fm = meta?.foundry;
-  const descPath = DESCRIPTION_FIELDS[game.system.id]?.[docName];
+  const descPath = descriptionPathFor(docName, game.system.id);
   const embedAuto = fm?.embed !== false && fm?.journal !== false;
   if (descPath && embedAuto) {
     const eId = await entryId(vault.id, vaultPath);
     const pId = await pageId(vault.id, vaultPath);
-    setPath(overlay, descPath, `<p>@Embed[JournalEntry.${eId}.JournalEntryPage.${pId} inline]</p>`);
+    setPath(overlay, descPath, `<p>@Embed[${journalPageUuid(vault, eId, pId)} inline]</p>`);
   }
   if (fm?.data && typeof fm.data === "object") {
     const cloned = rewriteVaultPaths(structuredClone(fm.data), vault.id);
+    await resolveMoulinetteRefs(cloned, (msg) => console.warn(`Vaults | moulinette: ${vaultPath}: ${msg}`));
+    await resolveItemUuids(cloned, vaultPath);
     await ensureEmbeddedIds(cloned, vault.id, vaultPath);
     deepMerge(overlay, cloned);
   }
-  if (docName === "Scene") {
-    const note = await buildJournalNote(vault, vaultPath, meta);
-    if (note) overlay.notes = [...overlay.notes ?? [], note];
-  }
   return overlay;
 }
-async function buildJournalNote(vault, vaultPath, meta) {
-  const fm = meta?.foundry ?? {};
-  const cfg = { ...fm.data_json ?? {}, ...fm.data ?? {} };
-  const width = Number(cfg.width) || 4e3;
-  const height = Number(cfg.height) || 3e3;
-  const padding = Number(cfg.padding ?? 0.25);
-  const gridSize = Number(cfg.grid?.size) || 100;
-  const iconSize = gridSize;
+function notePosition(geom) {
+  const width = Number(geom.width) || 4e3;
+  const height = Number(geom.height) || 3e3;
+  const padding = Number(geom.padding ?? 0.25);
+  const gridSize = Number(geom.grid?.size) || 100;
+  return {
+    x: gridSize * (Math.ceil(width / gridSize * padding) - 0.5),
+    y: gridSize * (Math.ceil(height / gridSize * padding) + 0.5)
+  };
+}
+async function attachJournalNote(sceneData, geom, vault, vaultPath, meta) {
+  const gridSize = Number(geom.grid?.size) || 100;
+  const { x, y } = notePosition(geom);
   const eId = await entryId(vault.id, vaultPath);
   const idOverride = meta?.foundry?.id;
   const pId = typeof idOverride === "string" && idOverride ? idOverride : await pageId(vault.id, vaultPath);
-  return {
+  const note2 = {
     _id: await subdocId(vault.id, vaultPath, "/notes/__journalLink__"),
     entryId: eId,
     pageId: pId,
-    x: gridSize * (Math.ceil(width / gridSize * padding) - 0.5),
-    y: gridSize * (Math.ceil(height / gridSize * padding) + 0.5),
-    iconSize,
+    x,
+    y,
+    iconSize: gridSize,
     texture: {
       src: "icons/svg/book.svg",
       anchorX: 0.5,
@@ -1026,8 +1559,48 @@ async function buildJournalNote(vault, vaultPath, meta) {
     },
     text: ""
   };
+  sceneData.notes = [...sceneData.notes ?? [], note2];
 }
 var VALID_SUBDOC_ID = /^[A-Za-z0-9]{16}$/;
+function mergeItemsById(baseItems, pageItems) {
+  if (!Array.isArray(pageItems)) return baseItems;
+  if (!baseItems.length) return pageItems;
+  const merged = baseItems.map((item) => structuredClone(item));
+  const positionOf = new Map(merged.map((item, i) => [item?._id, i]));
+  for (const item of pageItems) {
+    const at = item && item._id !== void 0 ? positionOf.get(item._id) : void 0;
+    if (at === void 0) merged.push(item);
+    else deepMerge(merged[at], item);
+  }
+  return merged;
+}
+async function resolveItemUuids(data, vaultPath) {
+  if (!Array.isArray(data?.items)) return;
+  const resolved = [];
+  for (const entry of data.items) {
+    if (!entry || typeof entry !== "object" || typeof entry.uuid !== "string") {
+      resolved.push(entry);
+      continue;
+    }
+    const { uuid, ...overrides } = entry;
+    const source = await safeFromUuid(uuid);
+    if (!source) {
+      console.warn(`Vaults | foundry item uuid: ${vaultPath} \u2192 ${uuid} did not resolve; skipping that item.`);
+      continue;
+    }
+    if (source.documentName !== "Item") {
+      console.warn(`Vaults | foundry item uuid: ${vaultPath} \u2192 ${uuid} is a ${source.documentName}, not an Item; skipping that item.`);
+      continue;
+    }
+    const itemData = source.toObject();
+    delete itemData._id;
+    if (uuid.startsWith("Compendium.")) {
+      itemData._stats = { ...itemData._stats, compendiumSource: uuid };
+    }
+    resolved.push(deepMerge(itemData, overrides));
+  }
+  data.items = resolved;
+}
 async function ensureEmbeddedIds(value, vaultId, pagePath, ptr = "") {
   if (Array.isArray(value)) {
     for (let i = 0; i < value.length; i++) {
@@ -1101,6 +1674,37 @@ function deepMerge(target, source) {
   }
   return target;
 }
+async function findMissingDocuments(target, vault, entries) {
+  const out = [];
+  const journalPages = /* @__PURE__ */ new Set();
+  for (const entry of await target.contents("JournalEntry")) {
+    for (const page of entry.pages ?? []) journalPages.add(`${entry._id}.${page._id}`);
+  }
+  const idsByType = /* @__PURE__ */ new Map();
+  const packIds = async (docName) => {
+    if (!idsByType.has(docName)) idsByType.set(docName, await target.ids(docName));
+    return idsByType.get(docName);
+  };
+  for (const { logicalPath, meta } of entries) {
+    const fm = meta?.foundry;
+    const missing = [];
+    if (fm?.journal !== false) {
+      const eId = await entryId(vault.id, logicalPath);
+      const pId = typeof fm?.id === "string" && fm.id ? fm.id : await pageId(vault.id, logicalPath);
+      if (!journalPages.has(`${eId}.${pId}`)) missing.push("journal");
+    }
+    if (fm?.base !== void 0 && fm?.base !== null) {
+      const specs = Array.isArray(fm.base) ? fm.base : [fm.base];
+      const docName = docNameOf(parseFoundryBase(specs[0]));
+      if (docName) {
+        const id = typeof fm.id === "string" && fm.id ? fm.id : await instanceId(vault.id, logicalPath);
+        if (!(await packIds(docName)).has(id)) missing.push("document");
+      }
+    }
+    if (missing.length > 0) out.push({ path: logicalPath, missing: missing.join(" + ") });
+  }
+  return out;
+}
 
 // ../foundry/scripts/auth.mjs
 function tokenInfo(token) {
@@ -1114,8 +1718,187 @@ function tokenInfo(token) {
   };
 }
 
+// ../foundry/scripts/target.mjs
+async function openTarget(vault) {
+  return isAdventure(vault) ? openAdventure(vault) : openCompendium(vault);
+}
+async function openCompendium(vault) {
+  return {
+    vault,
+    adventure: false,
+    async get(docName, id) {
+      const pack = await ensurePack(vault, docName);
+      const doc = await pack.getDocument(id);
+      return doc ? doc.toObject() : null;
+    },
+    async put(docName, data) {
+      const pack = await ensurePack(vault, docName);
+      const existing = await pack.getDocument(data._id);
+      if (existing) {
+        await existing.update(data);
+        return "modified";
+      }
+      const cls = CONFIG[docName].documentClass;
+      await cls.create(data, { pack: pack.collection, keepId: true, keepEmbeddedIds: true });
+      if (!await pack.getDocument(data._id)) {
+        throw new Error(`${docName} ${data._id} was rejected on create`);
+      }
+      return "added";
+    },
+    async remove(docName, id) {
+      const pack = getPack(vault, docName);
+      const doc = pack && await pack.getDocument(id);
+      if (doc) await doc.delete();
+    },
+    async putFolder(docName, folder) {
+      const pack = await ensurePack(vault, docName);
+      const existing = pack.folders.get(folder._id);
+      if (existing) {
+        if (existing.name !== folder.name || (existing.folder?.id ?? null) !== (folder.folder ?? null)) {
+          await existing.update({ name: folder.name, folder: folder.folder ?? null });
+        }
+        return;
+      }
+      await Folder.create(
+        { ...folder, type: docName },
+        { pack: pack.collection, keepId: true }
+      );
+      if (!pack.folders.get(folder._id)) {
+        throw new Error(`Folder ${folder._id} ("${folder.name}") was rejected on create`);
+      }
+    },
+    /** Every document of a type this vault owns. One request, not one per id. */
+    async contents(docName) {
+      const pack = getPack(vault, docName);
+      return pack ? (await pack.getDocuments()).map((d) => d.toObject()) : [];
+    },
+    async ids(docName) {
+      const pack = getPack(vault, docName);
+      return new Set(pack ? (await pack.getIndex()).map((e) => e._id) : []);
+    },
+    // Each write already landed.
+    async commit() {
+    }
+  };
+}
+var FIELD = {
+  Actor: "actors",
+  Item: "items",
+  Scene: "scenes",
+  JournalEntry: "journal",
+  RollTable: "tables",
+  Macro: "macros",
+  Cards: "cards",
+  Playlist: "playlists"
+};
+async function openAdventure(vault) {
+  const pack = await ensurePack(vault, "Adventure");
+  const id = await adventureId(vault.id);
+  const existing = await pack.getDocument(id);
+  const source = existing ? existing.toObject() : null;
+  const docs = /* @__PURE__ */ new Map();
+  for (const [docName, field] of Object.entries(FIELD)) {
+    docs.set(docName, new Map((source?.[field] ?? []).map((d) => [d._id, d])));
+  }
+  const folders = new Map((source?.folders ?? []).map((f) => [f._id, f]));
+  let dirty = false;
+  return {
+    vault,
+    adventure: true,
+    async get(docName, docId) {
+      return docs.get(docName)?.get(docId) ?? null;
+    },
+    async put(docName, data) {
+      const byId = docs.get(docName);
+      if (!byId) throw new Error(`An Adventure cannot hold a ${docName}`);
+      const had = byId.has(data._id);
+      byId.set(data._id, data);
+      dirty = true;
+      return had ? "modified" : "added";
+    },
+    async remove(docName, docId) {
+      if (docs.get(docName)?.delete(docId)) dirty = true;
+    },
+    async putFolder(docName, folder) {
+      const want = { ...folder, type: docName, folder: folder.folder ?? null };
+      const have = folders.get(folder._id);
+      if (have && have.name === want.name && have.folder === want.folder) return;
+      folders.set(folder._id, want);
+      dirty = true;
+    },
+    async contents(docName) {
+      return [...docs.get(docName)?.values() ?? []];
+    },
+    async ids(docName) {
+      return new Set(docs.get(docName)?.keys() ?? []);
+    },
+    async commit() {
+      if (!dirty && existing) return;
+      const data = {
+        _id: id,
+        name: vault.label || "Vault",
+        // The sheet shows these before import, and they are the only
+        // description a GM gets of what they are about to bring in.
+        caption: `Synced from ${vault.url}`,
+        description: `<p>Every page, document and folder from the <strong>${vault.label || "vault"}</strong> vault. Importing creates them in this world; importing again updates what is already here rather than duplicating it.</p>`,
+        folders: [...folders.values()],
+        flags: { [MODULE_ID]: { vaultId: vault.id } }
+      };
+      for (const [docName, field] of Object.entries(FIELD)) {
+        data[field] = [...docs.get(docName).values()];
+      }
+      if (existing) await existing.update(data);
+      else {
+        await Adventure.create(data, { pack: pack.collection, keepId: true, keepEmbeddedIds: true });
+        if (!await pack.getDocument(id)) {
+          throw new Error(`Adventure ${id} was rejected on create`);
+        }
+      }
+    }
+  };
+}
+
 // ../foundry/scripts/sync.mjs
-async function sync(host, vault, { forceFull = false } = {}) {
+async function orderByBaseDeps(vault, paths, bodyMetaIndex) {
+  const ownerOf = /* @__PURE__ */ new Map();
+  for (const p of paths) {
+    const fm = bodyMetaIndex.get(p)?.foundry;
+    if (!fm?.base) continue;
+    const id = typeof fm.id === "string" && fm.id ? fm.id : await instanceId(vault.id, p.replace(/\.body\.html$/i, ".md"));
+    ownerOf.set(id, p);
+  }
+  if (!ownerOf.size) return paths;
+  const dependsOn = /* @__PURE__ */ new Map();
+  for (const p of paths) {
+    const base = bodyMetaIndex.get(p)?.foundry?.base;
+    const match = typeof base === "string" && base.match(/^(?:Actor|Item)\.([A-Za-z0-9]{16})$/);
+    const from = match && ownerOf.get(match[1]);
+    if (from && from !== p) dependsOn.set(p, from);
+  }
+  if (!dependsOn.size) return paths;
+  const ordered = [];
+  const placed = /* @__PURE__ */ new Set();
+  const visit = (p, chain) => {
+    if (placed.has(p) || chain.has(p)) return;
+    chain.add(p);
+    const from = dependsOn.get(p);
+    if (from) visit(from, chain);
+    if (!placed.has(p)) {
+      placed.add(p);
+      ordered.push(p);
+    }
+  };
+  for (const p of paths) visit(p, /* @__PURE__ */ new Set());
+  return ordered;
+}
+async function sync(host, vault, opts = {}) {
+  try {
+    return await runSync(host, vault, opts);
+  } finally {
+    end();
+  }
+}
+async function runSync(host, vault, { forceFull = false } = {}) {
   if (!vault?.url) {
     host.notify("error", host.localize("VAULTS.Sync.NoUrl"));
     return { ok: false, refreshHandlerAssets: false };
@@ -1131,6 +1914,7 @@ async function sync(host, vault, { forceFull = false } = {}) {
   }
   const start = Date.now();
   host.notify("info", host.localize("VAULTS.Sync.StartingNamed", { name: vault.label }));
+  begin(vault.label);
   let manifest;
   try {
     manifest = await fetchManifest(vault);
@@ -1149,6 +1933,8 @@ async function sync(host, vault, { forceFull = false } = {}) {
   const knownRoles = Array.isArray(manifest.auth?.roles) ? manifest.auth.roles : [];
   const patch = {};
   if (vault.public !== isPublic) patch.public = isPublic;
+  const foundryPackage = manifest.foundry_package || "compendium";
+  if (vault.foundryPackage !== foundryPackage) patch.foundryPackage = foundryPackage;
   if (!arraysEqual(vault.knownRoles, knownRoles)) patch.knownRoles = knownRoles;
   const remoteAssets = manifest.assets?.foundry || {};
   const newAssetPaths = {
@@ -1158,7 +1944,8 @@ async function sync(host, vault, { forceFull = false } = {}) {
   if (JSON.stringify(vault.handlerAssetPaths || {}) !== JSON.stringify(newAssetPaths)) {
     patch.handlerAssetPaths = newAssetPaths;
   }
-  if (vault.dmRole && !knownRoles.includes(vault.dmRole)) patch.dmRole = "";
+  const playerRole = typeof manifest.foundry_player_role === "string" ? manifest.foundry_player_role : "";
+  if (vault.playerRole !== playerRole) patch.playerRole = playerRole;
   if (Object.keys(patch).length > 0) {
     await host.updateVaultEntry(vault.id, patch);
     Object.assign(vault, patch);
@@ -1168,7 +1955,15 @@ async function sync(host, vault, { forceFull = false } = {}) {
   );
   const remote = new Map(files.map((f) => [f.path, f.hash]));
   const lastSync = host.getVaultState(vault.id);
-  const local = forceFull ? /* @__PURE__ */ new Map() : new Map(Object.entries(lastSync.lastManifest || {}));
+  const remoteIdScheme = manifest.id_scheme || "v1";
+  const schemeChanged = !!lastSync.lastIdScheme && lastSync.lastIdScheme !== remoteIdScheme;
+  if (schemeChanged) {
+    console.warn(
+      `Vaults | ${vault.label}: document id scheme changed (${lastSync.lastIdScheme} \u2192 ${remoteIdScheme}); forcing a full re-sync so existing documents are re-derived rather than duplicated.`
+    );
+  }
+  const fullPass = forceFull || schemeChanged;
+  const local = fullPass ? /* @__PURE__ */ new Map() : new Map(Object.entries(lastSync.lastManifest || {}));
   const bodyPaths = files.filter((f) => f.path.endsWith(".body.html")).map((f) => f.path);
   const pathIndex = buildPathIndex(files);
   const allMdPaths = bodyPaths.map((p) => p.replace(/\.body\.html$/i, ".md"));
@@ -1177,7 +1972,19 @@ async function sync(host, vault, { forceFull = false } = {}) {
   for (const f of files) {
     if (f.meta && f.path.endsWith(".body.html")) bodyMetaIndex.set(f.path, f.meta);
   }
-  const toUpsert = bodyPaths.filter((p) => remote.get(p) !== local.get(p));
+  const missingPackages = await missingBasePackages(bodyMetaIndex.values());
+  if (missingPackages.size > 0) {
+    const summary = [...missingPackages].map(([pkg, n]) => `${pkg} (${n})`).join(", ");
+    host.notify("warn", host.localize("VAULTS.Sync.MissingPackages", { packages: summary }));
+    console.warn(
+      `Vaults | ${vault.label}: foundry.base points into package(s) this world can't read: ${summary}. Those pages will sync as journals but instantiate no document.`
+    );
+  }
+  const prevImages = forceFull ? /* @__PURE__ */ new Map() : new Map(Object.entries(lastSync.lastImageManifest || {}));
+  const lastMediaRefs = lastSync.lastMediaRefs || {};
+  const mediaStale = (bodyPath) => (lastMediaRefs[bodyPath] || []).some((m) => remote.get(m) !== prevImages.get(m));
+  const changed = bodyPaths.filter((p) => remote.get(p) !== local.get(p) || mediaStale(p));
+  const toUpsert = await orderByBaseDeps(vault, changed, bodyMetaIndex);
   const toDelete = [...local.keys()].filter((p) => p.endsWith(".body.html") && !remote.has(p));
   if (forceFull) await host.setVaultState(vault.id, { lastImageManifest: {} });
   let imageStats = { downloaded: 0, removed: 0, errors: 0 };
@@ -1186,8 +1993,25 @@ async function sync(host, vault, { forceFull = false } = {}) {
   } catch (err) {
     console.warn(`Vaults | image sync failed for ${vault.label}:`, err);
   }
+  const untouched = new Set(bodyPaths);
+  for (const p of toUpsert) untouched.delete(p);
+  for (const p of toDelete) untouched.delete(p);
+  const target = await openTarget(vault);
+  const missingDocs = await findMissingDocuments(target, vault, [...untouched].map((bodyPath) => ({
+    logicalPath: bodyPath.replace(/\.body\.html$/i, ".md"),
+    meta: bodyMetaIndex.get(bodyPath)
+  })));
+  const reportMissingDocs = () => {
+    if (missingDocs.length === 0) return;
+    host.notify("warn", host.localize("VAULTS.Sync.MissingDocuments", { count: missingDocs.length }));
+    console.warn(
+      `Vaults | ${vault.label}: ${missingDocs.length} page(s) have no document in this world. An incremental sync will not notice them again \u2014 use Force Sync to restore:`,
+      missingDocs
+    );
+  };
   if (toUpsert.length === 0 && toDelete.length === 0 && imageStats.downloaded === 0 && imageStats.removed === 0) {
     host.notify("info", host.localize("VAULTS.Sync.NothingToDo"));
+    reportMissingDocs();
     return {
       ok: true,
       refreshHandlerAssets: false,
@@ -1195,12 +2019,18 @@ async function sync(host, vault, { forceFull = false } = {}) {
       modified: 0,
       removed: 0,
       imageStats,
-      instances: 0
+      instances: 0,
+      skipped: [],
+      failed: [],
+      // The drift list is computed above this return, so report it here too —
+      // an up-to-date sync with missing documents is exactly the case a caller
+      // most wants to see.
+      missingDocuments: missingDocs
     };
   }
   host.notify(
     "info",
-    forceFull ? host.localize("VAULTS.Sync.Initial", { count: toUpsert.length }) : host.localize("VAULTS.Sync.Incremental", {
+    fullPass ? host.localize("VAULTS.Sync.Initial", { count: toUpsert.length }) : host.localize("VAULTS.Sync.Incremental", {
       add: toUpsert.length,
       mod: 0,
       del: toDelete.length
@@ -1208,65 +2038,134 @@ async function sync(host, vault, { forceFull = false } = {}) {
   );
   let bodies;
   try {
-    bodies = await fetchSourceBatch(vault, toUpsert);
+    const byRole = /* @__PURE__ */ new Map();
+    for (const bodyPath of toUpsert) {
+      const pageRole = bodyMetaIndex.get(bodyPath)?.role;
+      const key = pageRole || "";
+      if (!byRole.has(key)) byRole.set(key, []);
+      byRole.get(key).push(bodyPath);
+    }
+    bodies = /* @__PURE__ */ new Map();
+    for (const [pageRole, group] of byRole) {
+      const fetched = await fetchSourceBatch(vault, group, pageRole || void 0);
+      for (const [k, v] of fetched) bodies.set(k, v);
+    }
   } catch (err) {
     console.error(`Vaults | batch fetch failed for ${vault.label}:`, err);
     host.notify("error", host.localize("VAULTS.Sync.Error", { message: err.message }));
     return { ok: false, refreshHandlerAssets: false };
   }
   let added = 0, modified = 0, instances = 0;
+  const skipped = [];
+  const versionSkew = [];
+  const failedPages = /* @__PURE__ */ new Map();
+  const mediaRefs = {};
+  for (const p of bodyPaths) if (lastMediaRefs[p]) mediaRefs[p] = lastMediaRefs[p];
+  phase("Pages", toUpsert.length);
   for (const bodyPath of toUpsert) {
+    step(bodyPath.replace(/\.body\.html$/i, "").split("/").pop());
     const html = bodies.get(bodyPath);
     if (html == null) {
       console.warn(`Vaults | server returned no content for ${bodyPath}`);
+      failedPages.set(bodyPath, "no content returned");
       continue;
     }
     const logicalPath = bodyPath.replace(/\.body\.html$/i, ".md");
     const pageMeta = bodyMetaIndex.get(bodyPath);
     try {
       if (pageMeta?.foundry?.journal === false) {
-        await deleteFile(vault, logicalPath);
+        await deleteFile(target, vault, logicalPath);
       } else {
-        const result = await upsertFile(vault, logicalPath, html, pathIndex, pageMeta, folderInfo);
+        const refs = /* @__PURE__ */ new Set();
+        const result = await upsertFile(target, vault, logicalPath, html, pathIndex, pageMeta, folderInfo, refs);
+        mediaRefs[bodyPath] = [...refs];
         if (result === "added") added++;
         else modified++;
       }
       if (pageMeta?.foundry?.base) {
         try {
-          await applyInstance(vault, logicalPath, pageMeta);
-          instances++;
+          const outcome = await applyInstance(target, vault, logicalPath, pageMeta, { forceFull: fullPass });
+          if (outcome?.ok) {
+            instances++;
+            if (outcome.skew) versionSkew.push({ path: logicalPath, ...outcome.skew });
+          } else if (outcome) skipped.push({ path: logicalPath, reason: outcome.reason });
         } catch (err) {
           console.warn(`Vaults | foundry instantiation failed for ${logicalPath}:`, err);
+          skipped.push({ path: logicalPath, reason: "threw" });
         }
       }
     } catch (err) {
       console.warn(`Vaults | upsert failed for ${logicalPath}:`, err);
+      failedPages.set(bodyPath, err?.message || "upsert threw");
     }
   }
   let removed = 0;
+  const failedDeletes = /* @__PURE__ */ new Set();
+  if (toDelete.length > 0) phase("Removing", toDelete.length);
   for (const bodyPath of toDelete) {
     const logicalPath = bodyPath.replace(/\.body\.html$/i, ".md");
+    step(logicalPath.split("/").pop());
     try {
-      await deleteFile(vault, logicalPath);
+      await deleteFile(target, vault, logicalPath);
       removed++;
     } catch (err) {
       console.warn(`Vaults | delete failed for ${logicalPath}:`, err);
+      failedDeletes.add(bodyPath);
     }
     try {
-      await deleteInstance(vault, logicalPath);
+      await deleteInstance(target, vault, logicalPath);
     } catch (err) {
       console.warn(`Vaults | delete instance failed for ${logicalPath}:`, err);
     }
   }
-  await host.setVaultState(vault.id, { lastManifest: Object.fromEntries(remote) });
-  await reconcileEntryPlacement(vault, folderInfo);
-  await reconcileOwnership(vault, bodyMetaIndex);
+  const persisted = new Map(remote);
+  for (const bodyPath of failedPages.keys()) {
+    const previous = local.get(bodyPath);
+    if (previous === void 0) persisted.delete(bodyPath);
+    else persisted.set(bodyPath, previous);
+  }
+  for (const bodyPath of failedDeletes) {
+    const previous = local.get(bodyPath);
+    if (previous !== void 0) persisted.set(bodyPath, previous);
+  }
+  await host.setVaultState(vault.id, {
+    lastManifest: Object.fromEntries(persisted),
+    lastMediaRefs: mediaRefs,
+    lastIdScheme: remoteIdScheme
+  });
+  await reconcileEntries(target, vault, folderInfo, bodyMetaIndex);
+  await target.commit();
+  await pruneStalePacks(vault);
   const seconds = ((Date.now() - start) / 1e3).toFixed(1);
   host.notify("info", host.localize("VAULTS.Sync.Done", { added, modified, removed, seconds }));
+  reportMissingDocs();
   if (imageStats.downloaded > 0 || imageStats.removed > 0) {
     console.info(`Vaults | ${vault.label} images: ${imageStats.downloaded} downloaded, ${imageStats.removed} removed` + (imageStats.errors ? `, ${imageStats.errors} failed` : ""));
   }
   if (instances > 0) console.info(`Vaults | ${vault.label} instantiated ${instances} document(s) from page foundry.base.`);
+  if (versionSkew.length > 0) {
+    host.notify("warn", localizeOr(
+      host,
+      "VAULTS.Sync.VersionSkew",
+      "{count} document(s) came from a different Foundry generation and may not render correctly. See the console for which pack, and which version it targets.",
+      { count: versionSkew.length }
+    ));
+    console.warn(
+      `Vaults | ${vault.label}: ${versionSkew.length} document(s) were exported for a different Foundry generation than this world (${game.release?.generation}). They import, but parts of a stale document may not place correctly \u2014 a Foundry 13 Scene keeps its walls and lights but draws its tiles at the canvas origin. Ask the creator for a re-export, or point the base at a pack built for this generation:`,
+      versionSkew
+    );
+  }
+  if (failedPages.size > 0) {
+    host.notify("warn", host.localize("VAULTS.Sync.PagesFailed", { count: failedPages.size }));
+    console.warn(
+      `Vaults | ${vault.label} failed to sync ${failedPages.size} page(s); they stay in the diff and retry next sync:`,
+      [...failedPages].map(([path, reason]) => ({ path, reason }))
+    );
+  }
+  if (skipped.length > 0) {
+    host.notify("warn", host.localize("VAULTS.Sync.InstancesSkipped", { count: skipped.length }));
+    console.warn(`Vaults | ${vault.label} no document created for ${skipped.length} page(s):`, skipped);
+  }
   return {
     ok: true,
     refreshHandlerAssets: true,
@@ -1274,7 +2173,10 @@ async function sync(host, vault, { forceFull = false } = {}) {
     modified,
     removed,
     imageStats,
-    instances
+    instances,
+    skipped,
+    missingDocuments: missingDocs,
+    failed: [...failedPages].map(([path, reason]) => ({ path, reason }))
   };
 }
 function arraysEqual(a, b) {
@@ -1286,16 +2188,15 @@ function arraysEqual(a, b) {
 
 // ../foundry/scripts/importer-entry.mjs
 var REQUIRED_HOST_VERSION = 1;
-async function runSync(host, vault, options = {}) {
+async function runSync2(host, vault, options = {}) {
   return sync(host, vault, options);
 }
 async function runRemove(_host, vault) {
-  await deleteVaultJournals(vault.id);
+  await deleteVaultPacks(vault.id);
   await deleteVaultCache(vault.id);
-  await deleteVaultInstances(vault.id);
 }
 export {
   REQUIRED_HOST_VERSION,
   runRemove,
-  runSync
+  runSync2 as runSync
 };