@dogsbay/ssg 0.2.0-beta.140 → 0.2.0-beta.142

package/dist/package/THIRD-PARTY-NOTICES.txt

@@ -1,31 +1,31 @@
 Third-party software in @dogsbay/ssg (dist/package/)
 
 ========================================================================
-@dogsbay/elements@0.2.0-beta.140 (MIT)
+@dogsbay/elements@0.2.0-beta.142 (MIT)
 https://github.com/dogsbay/dogsbay.git
 
 Licensed under MIT; the package ships no licence file.
 
 ========================================================================
-@dogsbay/primitives@0.2.0-beta.140 (MIT)
+@dogsbay/primitives@0.2.0-beta.142 (MIT)
 https://github.com/dogsbay/dogsbay.git
 
 Licensed under MIT; the package ships no licence file.
 
 ========================================================================
-@dogsbay/render-html@0.2.0-beta.140 (MIT)
+@dogsbay/render-html@0.2.0-beta.142 (MIT)
 https://github.com/dogsbay/dogsbay.git
 
 Licensed under MIT; the package ships no licence file.
 
 ========================================================================
-@dogsbay/search@0.2.0-beta.140 (MIT)
+@dogsbay/search@0.2.0-beta.142 (MIT)
 https://github.com/dogsbay/dogsbay.git
 
 Licensed under MIT; the package ships no licence file.
 
 ========================================================================
-@dogsbay/ui@0.2.0-beta.140 (MIT)
+@dogsbay/ui@0.2.0-beta.142 (MIT)
 https://github.com/dogsbay/dogsbay.git
 
 Licensed under MIT; the package ships no licence file.

package/dist/package/browser.mjs

@@ -18,7 +18,7 @@ import {
 
 // src/core/build.ts
 import { dogsbayMdToTree, splitFrontmatter as splitFrontmatter2, treeToDogsbayMd } from "@dogsbay/format-dogsbay-md/browser";
-import { buildHreflangLinks, missingTranslations, namespaceNavGroup, prefixSlug, rewriteContentRefs } from "@dogsbay/site-files";
+import { buildHreflangLinks, isMountRoot, missingTranslations, mountRefs, mountRootNote, namespaceNavGroup, placeMountedNav, prefixSlug as prefixSlug2, rewriteContentRefs } from "@dogsbay/site-files";
 
 // src/core/canonical.ts
 import { decideCanonical } from "@dogsbay/site-files";
@@ -26,7 +26,7 @@ import { declaresParams, splitFrontmatter } from "@dogsbay/format-dogsbay-md/bro
 
 // src/core/config.ts
 import { scriptUrl } from "@dogsbay/render-html";
-import { assertLeafSitemap, checkVersionSeo, isNamespaceAxisActive, namespaceSegments } from "@dogsbay/site-files";
+import { assertLeafSitemap, checkVersionSeo, isNamespaceAxisActive, namespaceSegments, parseMount } from "@dogsbay/site-files";
 
 // src/core/yaml.ts
 import { load } from "js-yaml";
@@ -67,6 +67,14 @@ function unitId(kind, v) {
   if (!/^[a-z0-9][a-z0-9._-]*$/i.test(id)) throw new ConfigError(`${kind}: id "${id.slice(0, 80)}" must be one URL segment of letters, digits, dots, dashes and underscores`);
   return id;
 }
+function sourceMount(s) {
+  const at = `content.sources[${String(s.path)}]`;
+  if (s.from !== "openapi") throw new ConfigError(`${at}: mount is only for a "from: openapi" source`);
+  if (s.name != null) throw new ConfigError(`${at} has both name and mount: a mounted source goes inside its version, so it takes no name`);
+  const parsed = parseMount(s.mount);
+  if ("error" in parsed) throw new ConfigError(`${at}: ${parsed.error}`);
+  return parsed.segments.join("/");
+}
 function sourceFrom(v, path) {
   if (v === "dogsbay-md" || v === "openapi") return v;
   throw new ConfigError(`content.sources[${path}].from must be "dogsbay-md" or "openapi"; got ${JSON.stringify(v)}`);
@@ -139,6 +147,7 @@ function parseConfig(text, overrides = {}) {
     path: sourcePath(s),
     ...s.name != null ? { name: sourceName(s.name) } : {},
     ...s.from != null ? { from: sourceFrom(s.from, String(s.path)) } : {},
+    ...s.mount != null ? { mount: sourceMount(s) } : {},
     version: s.version != null ? unitId("version", s.version) : void 0,
     locale: s.locale != null ? unitId("locale", s.locale) : void 0,
     attributes: s.attributes ?? void 0,
@@ -414,29 +423,41 @@ function buildUnits(cfg) {
       throw new ConfigError(`source "${u.source.path}" has locale "${u.locale}" which is not declared in locales`);
     }
   }
-  const namespaces = isNamespaceAxisActive(cfg.sources);
+  const namespaces = isNamespaceAxisActive(cfg.sources.filter((s) => !s.mount));
   if (namespaces && (versionAxis || localeAxis)) {
     throw new ConfigError("named sources (content.sources name:) cannot be combined with versions or locales yet (plans/openapi-sources.md)");
   }
   for (const s of cfg.sources) {
-    if (s.from === "openapi" && cfg.sources.length > 1 && !s.name) throw new ConfigError(`content.sources[${s.path}]: an OpenAPI source beside other sources needs a name:, so its pages do not land on theirs`);
+    if (s.from === "openapi" && cfg.sources.length > 1 && !s.name && !s.mount) throw new ConfigError(`content.sources[${s.path}]: an OpenAPI source beside other sources needs a name: or a mount:, so its pages do not land on theirs`);
   }
   const units = /* @__PURE__ */ new Map();
   for (const u of withDefaults2) {
     const atRoot = cfg.versions.find((v) => v.id === u.version)?.path === "";
     const prefix = [localeAxis ? u.locale : void 0, versionAxis && !atRoot ? u.version : void 0].filter(Boolean).join("/");
-    const member = { source: u.source, namespace: namespaceSegments(u.source, cfg.sources).join("/") };
+    const member = u.source.mount ? { source: u.source, namespace: "", mount: u.source.mount } : { source: u.source, namespace: namespaceSegments(u.source, cfg.sources).join("/") };
     const unit = units.get(prefix);
     if (!unit) {
       units.set(prefix, { source: u.source, members: [member], version: versionAxis ? u.version : void 0, locale: localeAxis ? u.locale : void 0, prefix });
       continue;
     }
-    if (!namespaces) throw new ConfigError(`two sources publish to the same prefix "${prefix || "/"}"`);
-    if (unit.members.some((m) => m.namespace === member.namespace)) {
-      throw new ConfigError(member.namespace ? `two sources are named "${member.namespace}"` : `two unnamed sources publish to the same prefix "${prefix || "/"}"`);
+    if (member.mount) {
+      const taken = unit.members.find((m) => m.mount === member.mount);
+      if (taken) throw new ConfigError(`two sources are mounted at "${member.mount}" in the same version and locale (${taken.source.path}, ${u.source.path})`);
+    } else if (unit.members.some((m) => !m.mount)) {
+      if (!namespaces) throw new ConfigError(`two sources publish to the same prefix "${prefix || "/"}"`);
+      if (unit.members.some((m) => !m.mount && m.namespace === member.namespace)) {
+        throw new ConfigError(member.namespace ? `two sources are named "${member.namespace}"` : `two unnamed sources publish to the same prefix "${prefix || "/"}"`);
+      }
     }
     unit.members.push(member);
-    if (!member.namespace && unit.members[0].namespace) unit.source = u.source;
+    const main = unit.members.find((m) => m.source === unit.source);
+    if (!member.namespace && !member.mount && (main.namespace || main.mount)) unit.source = u.source;
+  }
+  for (const unit of units.values()) {
+    for (const m of unit.members) {
+      const ns = m.mount && unit.members.find((o) => o.namespace && m.mount.split("/")[0] === o.namespace);
+      if (ns) throw new ConfigError(`content.sources[${m.source.path}]: mount "${m.mount}" is inside the folder of the source named "${ns.namespace}"; mount it elsewhere`);
+    }
   }
   return [...units.values()];
 }
@@ -454,8 +475,7 @@ function projectPath(unit, path) {
   for (const m of unit.members) {
     if (m.namespace && m.source.from !== "openapi" && (path === m.namespace || path.startsWith(m.namespace + "/"))) return sourceRoot(m.source) + path.slice(m.namespace.length + 1);
   }
-  const main = unit.members.find((m) => !m.namespace) ?? unit.members[0];
-  return sourceRoot(main.source) + path;
+  return sourceRoot(unit.source) + path;
 }
 var TOPIC_MAP = /\.topicmap\.ya?ml$/;
 function sourceNav(v, path, from) {
@@ -559,6 +579,209 @@ function createResolver(table, page) {
   };
 }
 
+// src/core/openapi-pages.ts
+import { mountSlug, prefixSlug } from "@dogsbay/site-files";
+
+// src/core/resolve.ts
+import { inlineText } from "@dogsbay/render-html";
+import { slugify } from "@dogsbay/render-html/html";
+import { CORE_SCHEMA, load as loadYaml2 } from "js-yaml";
+function hasPlaceholder(nodes, types) {
+  return (nodes ?? []).some((n) => types.has(n.type) || hasPlaceholder(n.children, types));
+}
+async function resolvePlaceholders(tree, resolvers, ctx) {
+  const byType = new Map(resolvers.map((r) => [r.type, r]));
+  if (!hasPlaceholder(tree, new Set(byType.keys()))) return void 0;
+  const usedIds = headingIds(tree);
+  const warnings = [];
+  const walk = async (nodes) => {
+    for (let i = 0; i < nodes.length; i++) {
+      const r = byType.get(nodes[i].type);
+      if (!r) {
+        if (nodes[i].children) await walk(nodes[i].children);
+        continue;
+      }
+      let got;
+      try {
+        got = await r.resolve(nodes[i], { ...ctx, usedIds });
+      } catch (e) {
+        got = { warning: e.message || String(e) };
+      }
+      if ("warning" in got) {
+        warnings.push(got.warning);
+        nodes.splice(i, 1, ...nodes[i].children ?? []);
+        i--;
+        continue;
+      }
+      headingIds(got.nodes, usedIds);
+      nodes.splice(i, 1, ...got.nodes);
+      i += got.nodes.length - 1;
+    }
+  };
+  await walk(tree);
+  return warnings;
+}
+function headingIds(nodes, ids = /* @__PURE__ */ new Set()) {
+  const take = (raw) => {
+    const base = RESERVED_ID.test(raw) ? `h-${raw}` : raw;
+    let id = base || "section";
+    for (let n = 2; ids.has(id); n++) id = `${base}-${n}`;
+    ids.add(id);
+  };
+  const walk = (list) => {
+    for (const n of list) {
+      if (n.type === "heading") {
+        const p = n.props ?? {};
+        take(typeof p.id === "string" ? p.id : typeof p.slug === "string" ? p.slug : slugify(inlineText(n.inline)));
+      } else if ((n.type === "prose" || n.type === "html") && typeof n.html === "string") {
+        for (const m of n.html.matchAll(/<h[1-6]\b[^>]*\sid="([^"]*)"/gi)) take(m[1]);
+      }
+      if (n.children) walk(n.children);
+    }
+  };
+  walk(nodes);
+  return ids;
+}
+var RESERVED_ID = /^(db-|tab-\d|tabpanel-\d|acc-\d|accpanel-\d|fn-|fnref-)/;
+var autodocUnresolved = {
+  type: "autodoc-ref",
+  async resolve(node) {
+    const ref = typeof node.props?.ref === "string" ? node.props.ref : "";
+    return { warning: `:::autodoc${ref ? `{ref="${ref}"}` : ""} is not resolved in this build: resolve it at migration time (dogsbay migrate-mkdocs --inline-autodoc)` };
+  }
+};
+var coreLoad;
+var loadCore = () => coreLoad ??= import("@dogsbay/format-openapi/core");
+function openApiResolver(read, maxChars = 8e6) {
+  let specs;
+  return {
+    type: "openapi-ref",
+    async resolve(node, ctx) {
+      const spec = typeof node.props?.spec === "string" ? node.props.spec : "";
+      const core = await loadCore();
+      const selected = core.directiveOperation(node.props);
+      if ("error" in selected) return { warning: `:::openapi: ${selected.error}` };
+      const slug = ctx.source.replace(/\.(md|markdown)$/i, "").replace(/(^|\/)index$/, "");
+      const found = core.findSpec(spec, slug, (p) => {
+        const at = ctx.scope ? ctx.scope(p) : p;
+        return ctx.has(at) ? { path: at } : void 0;
+      });
+      if ("error" in found) return { warning: `:::openapi: ${found.error}` };
+      specs ??= core.createSpecCache(async (p) => {
+        const text = await read(p);
+        if (text === void 0) throw new Error("not found");
+        return text;
+      }, (text) => loadYaml2(text, { schema: CORE_SCHEMA }));
+      let prepared;
+      try {
+        prepared = await specs.get(found.path);
+      } catch (e) {
+        return { warning: `:::openapi: cannot read ${spec}: ${e.message}` };
+      }
+      let tree;
+      try {
+        tree = core.embedSpec(prepared, { usedIds: ctx.usedIds, operation: selected.operation }).tree;
+      } catch (e) {
+        return { warning: `:::openapi: cannot use ${spec}: ${e.message}` };
+      }
+      const size = boundedSize(tree, maxChars);
+      if (size === "cycle") return { warning: `:::openapi: ${spec} has a cyclic example or schema, which cannot be shown` };
+      if (size === "over") return { warning: `:::openapi: ${spec} is too large to embed in one page (over ${Math.round(maxChars / 1e6)}M characters)` };
+      return { nodes: tree };
+    }
+  };
+}
+async function openApiSourcePages(read, specPath, reservedSlugs) {
+  const core = await loadCore();
+  const specs = core.createSpecCache(async (p) => {
+    const text = await read(p);
+    if (text === void 0) throw new Error("not found");
+    return text;
+  }, (text) => loadYaml2(text, { schema: CORE_SCHEMA }));
+  try {
+    return core.specToPages(await specs.get(specPath), { reservedSlugs });
+  } catch (e) {
+    return { error: `cannot read ${specPath}: ${e.message}` };
+  }
+}
+async function specFileOf(path, has, read) {
+  const p = path.replace(/^\.\//, "").replace(/\/+$/, "");
+  if (/\.(ya?ml|json)$/i.test(p)) return has(p) ? p : void 0;
+  const dir = p === "." || p === "" ? "" : p + "/";
+  const found = ["openapi", "swagger", "spec"].flatMap((b) => ["yaml", "yml", "json"].map((e) => `${dir}${b}.${e}`)).filter(has);
+  for (const f of found) {
+    const head = (await read(f))?.slice(0, 2048) ?? "";
+    if (/(?:^|[{,])\s*"?(openapi|swagger)"?\s*[:=]/m.test(head)) return f;
+  }
+  return found[0];
+}
+function boundedSize(value, max) {
+  let total = 0;
+  const path = /* @__PURE__ */ new Set();
+  const walk = (v) => {
+    if (typeof v === "string") total += v.length;
+    else if (v && typeof v === "object") {
+      if (path.has(v)) return "cycle";
+      path.add(v);
+      total += 2;
+      for (const x of Array.isArray(v) ? v : Object.values(v)) {
+        const r = walk(x);
+        if (r) return r;
+        if (total > max) return "over";
+      }
+      path.delete(v);
+    } else total += 4;
+    return total > max ? "over" : void 0;
+  };
+  return walk(value) ?? total;
+}
+
+// src/core/openapi-pages.ts
+function urlPathOf(url) {
+  if (!url) return [];
+  try {
+    return new URL(url).pathname.split("/").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+async function placeApiPages(cfg, unit, m, files, readText2) {
+  const read = async (p) => {
+    const c = files.get(p);
+    return c == null ? void 0 : readText2(c);
+  };
+  const spec = await specFileOf(m.source.path, (p) => files.has(p), read);
+  if (!spec) return { missing: true };
+  const ns = m.namespace;
+  const mount = m.mount?.split("/");
+  const segs = mount ?? (ns ? [ns] : []);
+  const first = ns || unit.prefix.split("/")[0];
+  const combined = [...urlPathOf(cfg.url), ...cfg.basePath.split("/").filter(Boolean)];
+  const taxonomies = new Set(cfg.taxonomies.map((t) => t.path.split("/")[0]).filter(Boolean));
+  const got = await openApiSourcePages(read, spec, [...first ? [first] : [], ...combined.slice(0, 1), ...taxonomies]);
+  if ("error" in got) return { spec, error: got.error };
+  const pages = got.pages.map((page) => {
+    const slug = mount ? mountSlug(mount, page.slug) : prefixSlug(segs, page.slug === "index" ? "" : page.slug);
+    const isIndex = page.slug === "index" || got.pages.some((q) => q.slug.startsWith(page.slug + "/"));
+    return { slug, out: outFileFor(slug, isIndex && slug !== ""), isIndex, page };
+  });
+  return { spec, pages, nav: got.nav, segs };
+}
+var outsCache = /* @__PURE__ */ new WeakMap();
+async function apiPageOuts(cfg, unit, m, files, readText2) {
+  let cache = outsCache.get(files);
+  if (!cache) outsCache.set(files, cache = /* @__PURE__ */ new Map());
+  const id = `${unit.prefix}\0${m.source.path}`;
+  const key = JSON.stringify([m.namespace, m.mount, cfg.url, cfg.basePath, cfg.taxonomies.map((t) => t.path)]);
+  const hit = cache.get(id);
+  const specFile = /\.(ya?ml|json)$/i.test(m.source.path) ? files.get(m.source.path.replace(/^\.\//, "")) : void 0;
+  if (hit && hit.key === key && specFile !== void 0 && hit.spec === specFile) return hit.outs;
+  const placed = await placeApiPages(cfg, unit, m, files, readText2);
+  const outs = "pages" in placed ? placed.pages.map((p) => [p.slug, p.out]) : [];
+  cache.set(id, { spec: specFile, key, outs });
+  return outs;
+}
+
 // src/core/nav.ts
 import { scriptUrl as scriptUrl2 } from "@dogsbay/render-html";
 function slugFromPath(p) {
@@ -851,7 +1074,7 @@ async function defaultTables(cfg, units, built, files, read, warn = () => {
   const tables = /* @__PURE__ */ new Map();
   if (!cfg.defaultVersion || !built.some((u) => u.version && u.version !== cfg.defaultVersion)) return tables;
   for (const unit of units.filter((u) => u.version === cfg.defaultVersion)) {
-    const t = await scan(cfg, unit, units, files, fm ?? frontMatterCache(read));
+    const t = await scan(cfg, unit, units, files, fm ?? frontMatterCache(read), read);
     if (!t.pages.size && built.some((u) => u.version !== cfg.defaultVersion && u.locale === unit.locale)) {
       warn(`[canonical] the default version "${cfg.defaultVersion}" has no pages under ${unit.source.path}, so older versions' pages keep themselves as canonical`);
     }
@@ -864,17 +1087,17 @@ async function languageTables(cfg, units, built, files, read, fm) {
   if (new Set(units.map((u) => u.locale).filter(Boolean)).size < 2) return tables;
   const versions = new Set(built.map((u) => u.version));
   const fmOf = fm ?? frontMatterCache(read);
-  for (const unit of units) if (versions.has(unit.version)) tables.set(unit.prefix, (await scan(cfg, unit, units, files, fmOf)).pages);
+  for (const unit of units) if (versions.has(unit.version)) tables.set(unit.prefix, (await scan(cfg, unit, units, files, fmOf, read)).pages);
   return tables;
 }
 async function translationTables(cfg, units, files, read, includeDrafts, fm) {
   const tables = /* @__PURE__ */ new Map();
   if (new Set(units.map((u) => u.locale).filter(Boolean)).size < 2) return tables;
   const fmOf = fm ?? frontMatterCache(read);
-  for (const unit of units) tables.set(unit.prefix, await scan(cfg, unit, units, files, fmOf, { kind: "built", includeDrafts }));
+  for (const unit of units) tables.set(unit.prefix, await scan(cfg, unit, units, files, fmOf, read, { kind: "built", includeDrafts }));
   return tables;
 }
-async function scan(cfg, unit, units, files, frontMatterOf, mode = { kind: "targets" }) {
+async function scan(cfg, unit, units, files, frontMatterOf, read, mode = { kind: "targets" }) {
   const rootOf = (u) => u.source.path === "." ? "" : u.source.path.replace(/^\.\//, "").replace(/\/+$/, "") + "/";
   const root = rootOf(unit);
   const otherRoots = units.filter((u) => u !== unit).map(rootOf).filter((r) => r && r.startsWith(root));
@@ -912,6 +1135,10 @@ async function scan(cfg, unit, units, files, frontMatterOf, mode = { kind: "targ
       for (const a of fm.aliases) if (typeof a === "string" && inUnit(a) !== void 0) setFirst(inUnit(a), detach(key(slug)));
     }
   }
+  for (const m of unit.members) {
+    if (m.source.from !== "openapi") continue;
+    for (const [slug, out] of await apiPageOuts(cfg, unit, m, files, read)) if (!pages.has(key(slug))) pages.set(detach(key(slug)), out);
+  }
   for (const r of cfg.redirects) {
     const from = sitePath(r.from, cfg.basePath);
     if (!mine(from)) continue;
@@ -1085,31 +1312,31 @@ var CLIENT_CANDIDATES = ['""', '"&"', '"\\\\$&")).join("|")})', '"\\\\$&")}"', '
 var SITE_NOTICES = `Third-party software in this site's _dogsbay/ files (dogsbay.js, site.css) and pages
 
 ========================================================================
-@dogsbay/elements@0.2.0-beta.140 (MIT)
+@dogsbay/elements@0.2.0-beta.142 (MIT)
 https://github.com/dogsbay/dogsbay.git
 
 Licensed under MIT; the package ships no licence file.
 
 ========================================================================
-@dogsbay/primitives@0.2.0-beta.140 (MIT)
+@dogsbay/primitives@0.2.0-beta.142 (MIT)
 https://github.com/dogsbay/dogsbay.git
 
 Licensed under MIT; the package ships no licence file.
 
 ========================================================================
-@dogsbay/render-html@0.2.0-beta.140 (MIT)
+@dogsbay/render-html@0.2.0-beta.142 (MIT)
 https://github.com/dogsbay/dogsbay.git
 
 Licensed under MIT; the package ships no licence file.
 
 ========================================================================
-@dogsbay/search@0.2.0-beta.140 (MIT)
+@dogsbay/search@0.2.0-beta.142 (MIT)
 https://github.com/dogsbay/dogsbay.git
 
 Licensed under MIT; the package ships no licence file.
 
 ========================================================================
-@dogsbay/ui@0.2.0-beta.140 (MIT)
+@dogsbay/ui@0.2.0-beta.142 (MIT)
 https://github.com/dogsbay/dogsbay.git
 
 Licensed under MIT; the package ships no licence file.
@@ -1560,160 +1787,6 @@ import { FAVICON_SVG } from "@dogsbay/render-html/favicon";
 import { codeRequest, createRenderContext, highlightInputs, inlineText as inlineText2, renderBlocks, scriptUrl as scriptUrl3 } from "@dogsbay/render-html";
 import { apiPageLayout } from "@dogsbay/serialize-core";
 
-// src/core/resolve.ts
-import { inlineText } from "@dogsbay/render-html";
-import { slugify } from "@dogsbay/render-html/html";
-import { CORE_SCHEMA, load as loadYaml2 } from "js-yaml";
-function hasPlaceholder(nodes, types) {
-  return (nodes ?? []).some((n) => types.has(n.type) || hasPlaceholder(n.children, types));
-}
-async function resolvePlaceholders(tree, resolvers, ctx) {
-  const byType = new Map(resolvers.map((r) => [r.type, r]));
-  if (!hasPlaceholder(tree, new Set(byType.keys()))) return void 0;
-  const usedIds = headingIds(tree);
-  const warnings = [];
-  const walk = async (nodes) => {
-    for (let i = 0; i < nodes.length; i++) {
-      const r = byType.get(nodes[i].type);
-      if (!r) {
-        if (nodes[i].children) await walk(nodes[i].children);
-        continue;
-      }
-      let got;
-      try {
-        got = await r.resolve(nodes[i], { ...ctx, usedIds });
-      } catch (e) {
-        got = { warning: e.message || String(e) };
-      }
-      if ("warning" in got) {
-        warnings.push(got.warning);
-        nodes.splice(i, 1, ...nodes[i].children ?? []);
-        i--;
-        continue;
-      }
-      headingIds(got.nodes, usedIds);
-      nodes.splice(i, 1, ...got.nodes);
-      i += got.nodes.length - 1;
-    }
-  };
-  await walk(tree);
-  return warnings;
-}
-function headingIds(nodes, ids = /* @__PURE__ */ new Set()) {
-  const take = (raw) => {
-    const base = RESERVED_ID.test(raw) ? `h-${raw}` : raw;
-    let id = base || "section";
-    for (let n = 2; ids.has(id); n++) id = `${base}-${n}`;
-    ids.add(id);
-  };
-  const walk = (list) => {
-    for (const n of list) {
-      if (n.type === "heading") {
-        const p = n.props ?? {};
-        take(typeof p.id === "string" ? p.id : typeof p.slug === "string" ? p.slug : slugify(inlineText(n.inline)));
-      } else if ((n.type === "prose" || n.type === "html") && typeof n.html === "string") {
-        for (const m of n.html.matchAll(/<h[1-6]\b[^>]*\sid="([^"]*)"/gi)) take(m[1]);
-      }
-      if (n.children) walk(n.children);
-    }
-  };
-  walk(nodes);
-  return ids;
-}
-var RESERVED_ID = /^(db-|tab-\d|tabpanel-\d|acc-\d|accpanel-\d|fn-|fnref-)/;
-var autodocUnresolved = {
-  type: "autodoc-ref",
-  async resolve(node) {
-    const ref = typeof node.props?.ref === "string" ? node.props.ref : "";
-    return { warning: `:::autodoc${ref ? `{ref="${ref}"}` : ""} is not resolved in this build: resolve it at migration time (dogsbay migrate-mkdocs --inline-autodoc)` };
-  }
-};
-var coreLoad;
-var loadCore = () => coreLoad ??= import("@dogsbay/format-openapi/core");
-function openApiResolver(read, maxChars = 8e6) {
-  let specs;
-  return {
-    type: "openapi-ref",
-    async resolve(node, ctx) {
-      const spec = typeof node.props?.spec === "string" ? node.props.spec : "";
-      const core = await loadCore();
-      const selected = core.directiveOperation(node.props);
-      if ("error" in selected) return { warning: `:::openapi: ${selected.error}` };
-      const slug = ctx.source.replace(/\.(md|markdown)$/i, "").replace(/(^|\/)index$/, "");
-      const found = core.findSpec(spec, slug, (p) => {
-        const at = ctx.scope ? ctx.scope(p) : p;
-        return ctx.has(at) ? { path: at } : void 0;
-      });
-      if ("error" in found) return { warning: `:::openapi: ${found.error}` };
-      specs ??= core.createSpecCache(async (p) => {
-        const text = await read(p);
-        if (text === void 0) throw new Error("not found");
-        return text;
-      }, (text) => loadYaml2(text, { schema: CORE_SCHEMA }));
-      let prepared;
-      try {
-        prepared = await specs.get(found.path);
-      } catch (e) {
-        return { warning: `:::openapi: cannot read ${spec}: ${e.message}` };
-      }
-      let tree;
-      try {
-        tree = core.embedSpec(prepared, { usedIds: ctx.usedIds, operation: selected.operation }).tree;
-      } catch (e) {
-        return { warning: `:::openapi: cannot use ${spec}: ${e.message}` };
-      }
-      const size = boundedSize(tree, maxChars);
-      if (size === "cycle") return { warning: `:::openapi: ${spec} has a cyclic example or schema, which cannot be shown` };
-      if (size === "over") return { warning: `:::openapi: ${spec} is too large to embed in one page (over ${Math.round(maxChars / 1e6)}M characters)` };
-      return { nodes: tree };
-    }
-  };
-}
-async function openApiSourcePages(read, specPath, reservedSlugs) {
-  const core = await loadCore();
-  const specs = core.createSpecCache(async (p) => {
-    const text = await read(p);
-    if (text === void 0) throw new Error("not found");
-    return text;
-  }, (text) => loadYaml2(text, { schema: CORE_SCHEMA }));
-  try {
-    return core.specToPages(await specs.get(specPath), { reservedSlugs });
-  } catch (e) {
-    return { error: `cannot read ${specPath}: ${e.message}` };
-  }
-}
-async function specFileOf(path, has, read) {
-  const p = path.replace(/^\.\//, "").replace(/\/+$/, "");
-  if (/\.(ya?ml|json)$/i.test(p)) return has(p) ? p : void 0;
-  const dir = p === "." || p === "" ? "" : p + "/";
-  const found = ["openapi", "swagger", "spec"].flatMap((b) => ["yaml", "yml", "json"].map((e) => `${dir}${b}.${e}`)).filter(has);
-  for (const f of found) {
-    const head = (await read(f))?.slice(0, 2048) ?? "";
-    if (/(?:^|[{,])\s*"?(openapi|swagger)"?\s*[:=]/m.test(head)) return f;
-  }
-  return found[0];
-}
-function boundedSize(value, max) {
-  let total = 0;
-  const path = /* @__PURE__ */ new Set();
-  const walk = (v) => {
-    if (typeof v === "string") total += v.length;
-    else if (v && typeof v === "object") {
-      if (path.has(v)) return "cycle";
-      path.add(v);
-      total += 2;
-      for (const x of Array.isArray(v) ? v : Object.values(v)) {
-        const r = walk(x);
-        if (r) return r;
-        if (total > max) return "over";
-      }
-      path.delete(v);
-    } else total += 4;
-    return total > max ? "over" : void 0;
-  };
-  return walk(value) ?? total;
-}
-
 // src/theme/regions.ts
 import { attrs, esc } from "@dogsbay/render-html/html";
 var svg = (body, cls, size = 16, extra = "") => `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="${cls}" aria-hidden="true" focusable="false"${extra}>${body}</svg>`;
@@ -3134,7 +3207,7 @@ async function build(input, hooks = {}) {
   phase.init = now() - t0;
   let pages = 0;
   let assets = 0;
-  const state = { redirects: [], navCache: navCache(), written: /* @__PURE__ */ new Set(), stubs: [], pageOut: /* @__PURE__ */ new Map(), sitemaps: /* @__PURE__ */ new Map(), supplied: /* @__PURE__ */ new Set(), usedMath: false, diagrams: diagramStore(input, cfg), scan: hooks.keep || hooks.lazy ? new ScanCache() : void 0, parseCache: input.parseCacheBytes === 0 ? false : new ParseCache(input.parseCacheBytes ?? DEFAULT_PARSE_CACHE_BYTES), templateBudget: templateBudget(input.untrusted === true, input.templateMs), dataCache: new DataCache(input.dataCacheBytes ?? DEFAULT_DATA_CACHE_BYTES) };
+  const state = { redirects: [], notes: /* @__PURE__ */ new Map(), navCache: navCache(), written: /* @__PURE__ */ new Set(), stubs: [], pageOut: /* @__PURE__ */ new Map(), sitemaps: /* @__PURE__ */ new Map(), supplied: /* @__PURE__ */ new Set(), usedMath: false, diagrams: diagramStore(input, cfg), scan: hooks.keep || hooks.lazy ? new ScanCache() : void 0, parseCache: input.parseCacheBytes === 0 ? false : new ParseCache(input.parseCacheBytes ?? DEFAULT_PARSE_CACHE_BYTES), templateBudget: templateBudget(input.untrusted === true, input.templateMs), dataCache: new DataCache(input.dataCacheBytes ?? DEFAULT_DATA_CACHE_BYTES) };
   for (const r of cfg.redirects) {
     const from = sitePath(r.from, cfg.basePath);
     if (!from) {
@@ -3211,6 +3284,7 @@ async function build(input, hooks = {}) {
     files: out,
     warnings,
     problems,
+    notes: [...state.notes.values()].flat(),
     config: cfg,
     stats: { pages, assets, units: units.length, ms: Math.round(now() - t0), msByPhase: roundAll(phase), highlightCache: highlighter.cacheStats(), ...state.parseCache ? { parseCache: state.parseCache.stats() } : {} }
   };
@@ -3486,6 +3560,7 @@ ${marker}${title}${marker}`, path, attributesOf(path), includesFor(path, read2),
   const diagrams = state.diagrams;
   const taxonomies = cfg.taxonomies.length ? new TaxonomyCollector(cfg.taxonomies) : void 0;
   const blog = cfg.blog ? new BlogCollector(cfg.blog) : void 0;
+  state.scanned?.(unit, "start");
   const infos = /* @__PURE__ */ new Map();
   const stubTargets = /* @__PURE__ */ new Map();
   const frontMatter = /* @__PURE__ */ new Map();
@@ -3522,7 +3597,7 @@ ${marker}${title}${marker}`, path, attributesOf(path), includesFor(path, read2),
       if (templatesOf(p).isPartial(fm, p)) continue;
       const inUnit = (s) => unit.prefix && (s === unit.prefix || s.startsWith(unit.prefix + "/")) ? s : [unit.prefix, s].filter(Boolean).join("/");
       const pageNs = named.length ? namespaceOf(p) : "";
-      const inScope = (s) => inUnit(pageNs && !(s === pageNs || s.startsWith(pageNs + "/")) ? prefixSlug([pageNs], s) : s);
+      const inScope = (s) => inUnit(pageNs && !(s === pageNs || s.startsWith(pageNs + "/")) ? prefixSlug2([pageNs], s) : s);
       const target = (raw) => isExternal(raw) ? raw : inScope(sitePath(raw, cfg.basePath));
       const isIndexFile = /(^|\/)index\.(md|markdown)$/i.test(p) && slug !== "";
       if (typeof fm.redirect === "string" && fm.redirect.trim()) {
@@ -3594,36 +3669,48 @@ ${marker}${title}${marker}`, path, attributesOf(path), includesFor(path, read2),
   if (activeFiles.length) warn("html", `content.html is sanitize, so ${activeFiles.length} HTML, XML or script file(s) are not copied: ${some(activeFiles)}`);
   if (untrustedFiles.length) report("untrusted", `[untrusted] ${untrustedFiles.length} file(s) not copied: only images, fonts, media, stylesheets, documents and data are, and no SVG that runs script or host configuration (_headers, _redirects): ${some(untrustedFiles)}`);
   const specNavs = /* @__PURE__ */ new Map();
-  const combinedPrefix = [...urlPathOf(cfg.url), ...cfg.basePath.split("/").filter(Boolean)];
+  const mountedNavs = /* @__PURE__ */ new Map();
+  const mountedSlugs = /* @__PURE__ */ new Set();
+  const notes = [];
+  state.notes.set(unit.prefix, notes);
   for (const m of unit.members) {
     if (m.source.from !== "openapi") continue;
-    const readProject = async (p) => {
-      const c = input.files.get(p);
-      return c == null ? void 0 : readText(c);
-    };
-    const spec = await specFileOf(m.source.path, (p) => input.files.has(p), readProject);
-    if (!spec) {
+    const placed = await placeApiPages(cfg, unit, m, input.files, readText);
+    if ("missing" in placed) {
       warn("openapi", `${m.source.path}: no OpenAPI spec there (a .yaml, .yml or .json file, or a folder holding openapi.*, swagger.* or spec.*)`);
       continue;
     }
-    const ns = m.namespace;
-    const segs = ns ? [ns] : [];
-    const reserved = [...segs, ...combinedPrefix.slice(0, 1), ...globalPrefixes];
-    const got = await openApiSourcePages(readProject, spec, reserved);
-    if ("error" in got) {
-      warnFile("openapi", m.source.path, spec, got.error);
+    const spec = placed.spec;
+    if ("error" in placed) {
+      warnFile("openapi", m.source.path, spec, placed.error);
       continue;
     }
+    const ns = m.namespace;
+    const mount = m.mount?.split("/");
+    const segs = placed.segs;
     const limit = input.openApiChars ?? 8e6;
-    for (const page of got.pages) {
-      const slug = prefixSlug(segs, page.slug === "index" ? "" : page.slug);
-      if (infos.has(slug)) {
+    const own = new Set(placed.pages.map((p) => p.page.slug));
+    let label2 = placed.pages.find((p) => isMountRoot(p.page.slug))?.page.title ?? m.mount ?? "";
+    for (const { slug, out, isIndex, page } of placed.pages) {
+      if (mount) {
+        const there = infos.get(slug);
+        if (there && isMountRoot(page.slug) && !there.virtual) {
+          notes.push(mountRootNote(m.mount, prefixSlug2(unit.prefix ? unit.prefix.split("/") : [], slug)));
+          label2 = there.title;
+          continue;
+        }
+        if (there) throw mountClash(slug, m.mount, srcOf(there), there.virtual ? `a page of ${srcOf(there)}` : `another page (${srcOf(there)})`);
+        mountRefs(page.tree, mount, own);
+        mountedSlugs.add(slug);
+      } else if (mountedSlugs.has(slug)) {
+        const by = unit.members.find((o) => o.mount && (slug === o.mount || slug.startsWith(o.mount + "/")))?.mount ?? "";
+        throw mountClash(slug, by, spec, `a page of ${spec}`);
+      } else if (infos.has(slug)) {
         warn("duplicate-page", `two sources map to the page "${slug || "/"}"; keeping ${srcOf(infos.get(slug))}, ignoring ${spec}'s`, { file: spec });
         continue;
       }
-      const isIndex = page.slug === "index" || got.pages.some((q) => q.slug.startsWith(page.slug + "/"));
       let tree = page.tree;
-      if (ns) rewriteContentRefs(tree, segs, globalPrefixes);
+      if (ns && !mount) rewriteContentRefs(tree, segs, globalPrefixes);
       const size = boundedSize(tree, limit);
       if (typeof size !== "number") {
         warnFile("openapi", spec, spec, `the page ${slug || "/"} ${size === "cycle" ? "has a cyclic example or schema, which cannot be shown" : `is too large to build (over ${Math.round(limit / 1e6 * 10) / 10}M characters)`}`);
@@ -3632,13 +3719,17 @@ ${marker}${title}${marker}`, path, attributesOf(path), includesFor(path, read2),
       infos.set(slug, {
         slug,
         source: isIndex ? slug ? `${slug}/index.md` : "index.md" : `${slug}.md`,
-        out: outFileFor(slug, isIndex && slug !== ""),
+        out,
         title: detach(page.title),
         draft: false,
         virtual: { tree, project: spec }
       });
     }
-    specNavs.set(ns, specNav(got.nav, segs));
+    if (mount) {
+      mountedNavs.set(m, { nav: specNav(placed.nav, segs), label: label2 });
+      continue;
+    }
+    specNavs.set(ns, specNav(placed.nav, segs));
     const strays = [...infos.values()].filter((i) => !i.virtual && ns && (i.slug === ns || i.slug.startsWith(ns + "/")));
     if (strays.length) warn("openapi", `${strays.length} page(s) are in the folder of the OpenAPI source "${ns}", and are left out of the nav: ${strays.slice(0, 5).map(srcOf).join(", ")}${strays.length > 5 ? ", \u2026" : ""}`);
   }
@@ -3646,16 +3737,16 @@ ${marker}${title}${marker}`, path, attributesOf(path), includesFor(path, read2),
   const navLoad = state.scan ? (text) => state.scan.yaml(text, loadYaml) : void 0;
   const memberNav = async (ns) => {
     const dir2 = ns ? ns + "/" : "";
-    const member = unit.members.find((m) => m.namespace === ns);
+    const member = unit.members.find((m) => m.namespace === ns && !m.mount);
     if (member?.source.nav) return ownNav(member.source, ns);
     const file = NAV_FILES.map((f) => dir2 + f).find((f) => files.has(f));
     const others = unit.members.filter((m) => m.namespace);
-    const mine = [...infos.values()].filter((i) => ns ? i.slug === ns || i.slug.startsWith(dir2) : !others.some((m) => i.slug === m.namespace || i.slug.startsWith(m.namespace + "/")));
+    const mine = [...infos.values()].filter((i) => !mountedSlugs.has(i.slug) && (ns ? i.slug === ns || i.slug.startsWith(dir2) : !others.some((m) => i.slug === m.namespace || i.slug.startsWith(m.namespace + "/"))));
     const fromPages = () => ns ? prefixNav(navFromPages(mine.map((i) => ({ ...i, slug: i.slug === ns ? "" : i.slug.slice(dir2.length) }))), ns) : navFromPages(mine);
     if (!file) return { nav: fromPages() };
     try {
       const text = await read(file);
-      return { nav: file.endsWith(".json") ? prefixNav(parseNavJson(text, (slug) => labelFor(ns ? prefixSlug([ns], slug) : slug)), ns) : parseNavYaml(text, labelFor, ns, navLoad), file, project: abs(file) };
+      return { nav: file.endsWith(".json") ? prefixNav(parseNavJson(text, (slug) => labelFor(ns ? prefixSlug2([ns], slug) : slug)), ns) : parseNavYaml(text, labelFor, ns, navLoad), file, project: abs(file) };
     } catch (e) {
       const mark = e.mark;
       warn("nav", `could not read ${file}: ${e.message}; using the directory layout`, {
@@ -3667,7 +3758,7 @@ ${marker}${title}${marker}`, path, attributesOf(path), includesFor(path, read2),
   };
   const ownNav = async (src, ns) => {
     const path = src.nav;
-    const nsLabel = (slug) => labelFor(ns ? prefixSlug([ns], slug) : slug);
+    const nsLabel = (slug) => labelFor(ns ? prefixSlug2([ns], slug) : slug);
     const map = topicMaps.get(path);
     if (map) return { nav: prefixNav(parseNavJson(JSON.stringify(map.entries), nsLabel), ns), file: path, project: path, files: map.maps };
     const c = input.files.get(path);
@@ -3678,7 +3769,13 @@ ${marker}${title}${marker}`, path, attributesOf(path), includesFor(path, read2),
   let nav = [];
   const navFiles = [];
   const navProjectFiles = [];
+  const host = unit.members.find((m) => !m.namespace && !m.mount && m.source.from !== "openapi");
   for (const m of unit.members) {
+    const placed = mountedNavs.get(m);
+    if (placed) {
+      if (!host) nav.push(...placed.nav);
+      continue;
+    }
     if (m.source.from === "openapi") {
       const items = specNavs.get(m.namespace) ?? [];
       const group2 = namespaceNavGroup(m.namespace || void 0, items);
@@ -3687,6 +3784,7 @@ ${marker}${title}${marker}`, path, attributesOf(path), includesFor(path, read2),
       continue;
     }
     const got = await memberNav(m.namespace);
+    if (m === host) for (const [mm, { nav: items, label: label2 }] of mountedNavs) got.nav = placeMounted(got.nav, items, mm.mount, label2);
     if (got.file) navFiles.push(got.file);
     if (got.project) navProjectFiles.push(got.project);
     const group = namespaceNavGroup(m.namespace || void 0, got.nav);
@@ -3782,6 +3880,7 @@ ${marker}${title}${marker}`, path, attributesOf(path), includesFor(path, read2),
   let search = cfg.search && cfg.searchEngine !== "pagefind" ? new SearchIndexBuilder({ lang: unit.locale ?? cfg.defaultLocale ?? "en" }) : void 0;
   const siteDepthPrefix = unit.prefix ? "../".repeat(unit.prefix.split("/").length) : "";
   phase.scan = (phase.scan ?? 0) + now() - t;
+  state.scanned?.(unit, "end");
   input.onUnitAssets?.(unit.prefix, assetPaths);
   if (diagrams) {
     t = now();
@@ -4594,22 +4693,28 @@ function postHeader(p, lang, t, asset) {
 function specNav(items, segs) {
   return items.map((it) => ({
     label: it.label,
-    ...it.href != null ? { slug: prefixSlug(segs, it.href.replace(/^\/+|\/+$/g, "")) } : {},
+    ...it.href != null ? { slug: prefixSlug2(segs, it.href.replace(/^\/+|\/+$/g, "")) } : {},
     children: specNav(it.children ?? [], segs)
   }));
 }
+var PageClashError = class extends Error {
+  constructor(message, file) {
+    super(message);
+    this.file = file;
+  }
+};
+function mountClash(slug, mount, file, other) {
+  return new PageClashError(`"${slug}" is both a page of the source mounted at "${mount}" and ${other}; move the page, or mount the source somewhere else`, file);
+}
+function placeMounted(host, mounted, mount, label) {
+  const to = (nodes) => nodes.map((n) => ({ label: n.label, href: n.slug != null ? `/${n.slug}` : n.href, children: to(n.children), node: n }));
+  const back = (items) => items.map((i) => i.node ? { ...i.node, children: back(i.children ?? []) } : { label: i.label, slug: i.href.replace(/^\/+|\/+$/g, ""), children: back(i.children ?? []) });
+  return back(placeMountedNav(to(host), to(mounted), `/${mount}`, label, mount).nav);
+}
 function prefixNav(nodes, ns) {
   if (!ns) return nodes;
   return nodes.map((n) => ({ ...n, ...n.slug != null ? { slug: n.slug ? `${ns}/${n.slug}` : ns } : {}, children: prefixNav(n.children, ns) }));
 }
-function urlPathOf(url) {
-  if (!url) return [];
-  try {
-    return new URL(url).pathname.split("/").filter(Boolean);
-  } catch {
-    return [];
-  }
-}
 function dropMount(tree, mounts) {
   if (!mounts.length) return tree;
   const strip = (u) => {
@@ -4879,6 +4984,14 @@ async function openDevSession(input, o = {}) {
   let buildError;
   let buildProblem;
   let diagnosed = /* @__PURE__ */ new Map();
+  let scanProblems = /* @__PURE__ */ new Map();
+  const watchScan = (c, into) => {
+    let from = 0;
+    c.state.scanned = (unit, at) => {
+      if (at === "start") from = c.problems.length;
+      else into.set(unit.prefix, c.problems.slice(from));
+    };
+  };
   const failed = (e) => {
     buildError = e.message || String(e);
     buildProblem = problemOf(e, buildError);
@@ -4887,6 +5000,7 @@ async function openDevSession(input, o = {}) {
     const next = /* @__PURE__ */ new Map();
     const nextUnits = /* @__PURE__ */ new Map();
     const nextDiagnosed = /* @__PURE__ */ new Map();
+    const nextScan = /* @__PURE__ */ new Map();
     let nextCtx;
     const sink = async (path, content) => {
       next.set(path, isStream(content) ? await joinChunks(content.chunks()) : content);
@@ -4908,7 +5022,10 @@ async function openDevSession(input, o = {}) {
         {
           keep: true,
           lazy: o.lazy,
-          context: (c) => nextCtx = c,
+          context: (c) => {
+            nextCtx = c;
+            watchScan(c, nextScan);
+          },
           diagnostics: (f, list) => nextDiagnosed.set(f, list),
           // A copy: the build keeps adding the classes of pages it renders later to its own set.
           unitBuilt: (unit, handle, classes) => nextUnits.set(unit.prefix, { unit, handle, classes: new Set(classes) })
@@ -4922,6 +5039,7 @@ async function openDevSession(input, o = {}) {
     units = nextUnits;
     ctx = nextCtx;
     diagnosed = nextDiagnosed;
+    scanProblems = nextScan;
     config = nextCtx?.cfg ?? nextConfig;
     taken = 0;
     takenProblems = 0;
@@ -5028,6 +5146,9 @@ async function openDevSession(input, o = {}) {
     sourceFor(path) {
       return unitForSitePath(path)?.handle.sourceForPage(path);
     },
+    notes() {
+      return [...ctx?.state.notes.values() ?? []].flat();
+    },
     takeWarnings() {
       const all = ctx?.warnings ?? [];
       const fresh = all.slice(taken);
@@ -5052,7 +5173,11 @@ async function openDevSession(input, o = {}) {
     get,
     async change(paths) {
       const t0 = Date.now();
-      const done = (r) => ({ ...r, ms: Date.now() - t0 });
+      const before = allFiles();
+      const done = (r, marked) => {
+        const stale2 = marked ?? /* @__PURE__ */ new Set([...before, ...allFiles()]);
+        return { ...r, stale: [...stale2].sort(), ms: Date.now() - t0 };
+      };
       try {
         if (buildError !== void 0) {
           await full();
@@ -5060,14 +5185,33 @@ async function openDevSession(input, o = {}) {
           buildProblem = void 0;
           return done({ css: true, handled: "full" });
         }
-        return done(await budgeted(() => changeParts(paths)));
+        const marked = /* @__PURE__ */ new Set();
+        const r = await budgeted(() => changeParts(paths, marked));
+        return done(r, r.handled === "full" ? void 0 : marked);
       } catch (e) {
         failed(e);
-        return done({ css: false, handled: "full" });
+        return done({ css: false, handled: "full" }, /* @__PURE__ */ new Set());
       }
     }
   };
-  async function changeParts(paths) {
+  function allFiles() {
+    const all = /* @__PURE__ */ new Set();
+    for (const u of units.values()) for (const o2 of u.handle.pageOuts) {
+      const src = u.handle.sourceForPage(o2);
+      if (src !== void 0) all.add(src);
+    }
+    for (const list of scanProblems.values()) for (const p of list) if (p.file !== void 0) all.add(p.file);
+    return all;
+  }
+  async function changeParts(paths, marked) {
+    const again = /* @__PURE__ */ new Map();
+    const markStale = (page, u = unitForSitePath(page), rebuilt = false) => {
+      stale.add(page);
+      const src = u?.handle.sourceForPage(page);
+      if (src === void 0) return;
+      marked.add(src);
+      if (!rebuilt) again.set(src, u.unit.prefix);
+    };
     const themeDir = config.themeDir ? config.themeDir.replace(/\/+$/, "") + "/" : void 0;
     const extraCss = new Set(config.css.map((c) => c.replace(/^\.\//, "")));
     const lazy = /* @__PURE__ */ new Set();
@@ -5113,7 +5257,7 @@ async function openDevSession(input, o = {}) {
           }
           x.handle.invalidateData();
           for (const page of x.handle.dataReaders(p)) {
-            stale.add(page);
+            markStale(page, x);
             mark("page");
           }
         }
@@ -5126,7 +5270,7 @@ async function openDevSession(input, o = {}) {
         const page = u.handle.pageForSource(p);
         const text = content === void 0 ? void 0 : await textOf(content);
         if (page && text !== void 0 && u.handle.sameFrontMatter(p, text) && !u.handle.included(p)) {
-          stale.add(page);
+          markStale(page, u);
           mark("page");
         } else {
           u.handle.forget(p);
@@ -5157,21 +5301,30 @@ async function openDevSession(input, o = {}) {
         if (unitForSitePath(key) === u) out.delete(key);
       }
       for (const s of [...stale]) if (unitForSitePath(s) === u) stale.delete(s);
+      for (const o2 of u.handle.pageOuts) {
+        const src = u.handle.sourceForPage(o2);
+        if (src !== void 0) marked.add(src);
+      }
+      const named = (list) => {
+        for (const p of list ?? []) if (p.file !== void 0) marked.add(p.file);
+      };
+      named(scanProblems.get(prefix));
       const handle = await rebuildUnitLazy({ ...ctx, emit: emitInto }, u.unit);
+      named(scanProblems.get(prefix));
       const next = { ...u, handle };
       units.set(prefix, next);
-      for (const o2 of handle.pageOuts) stale.add(o2);
+      for (const o2 of handle.pageOuts) markStale(o2, next, true);
     }
     if (config.defaultVersion && [...lazy].some((prefix) => units.get(prefix)?.unit.version === config.defaultVersion)) {
       const all = [...units.values()].map((u) => u.unit);
       ctx.state.canonical = await defaultTables(config, all, all, input.files, readText);
-      for (const u of units.values()) if (u.unit.version !== config.defaultVersion) for (const o2 of u.handle.pageOuts) stale.add(o2);
+      for (const u of units.values()) if (u.unit.version !== config.defaultVersion) for (const o2 of u.handle.pageOuts) markStale(o2, u);
     }
     if (lazy.size && ctx.state.languages) {
       const all = [...units.values()].map((u) => u.unit);
       const versions = new Set([...lazy].map((prefix) => units.get(prefix)?.unit.version));
       ctx.state.languages = await languageTables(config, all, all, input.files, readText);
-      for (const u of units.values()) if (versions.has(u.unit.version) && !lazy.has(u.unit.prefix)) for (const o2 of u.handle.pageOuts) stale.add(o2);
+      for (const u of units.values()) if (versions.has(u.unit.version) && !lazy.has(u.unit.prefix)) for (const o2 of u.handle.pageOuts) markStale(o2, u);
     }
     if (lazy.size) {
       const all = [...units.values()].map((u) => u.unit);
@@ -5187,6 +5340,14 @@ async function openDevSession(input, o = {}) {
         (p) => stale.has(p)
       );
     }
+    for (const [src, prefix] of again) {
+      if (lazy.has(prefix)) continue;
+      for (const p of scanProblems.get(prefix) ?? []) {
+        if (p.file !== src) continue;
+        ctx.problems.push(p);
+        ctx.warnings.push(p.text);
+      }
+    }
     return { css: false, handled };
   }
   async function attributesOnly() {
@@ -5232,7 +5393,7 @@ function inConfig(e, file) {
 function problemOf(e, text) {
   const err = e ?? {};
   const config = err.inConfig === true || e instanceof ConfigError;
-  const file = err.configFile;
+  const file = err.configFile ?? (e instanceof PageClashError ? e.file : void 0);
   const at = typeof err.mark?.line === "number" ? { line: err.mark.line + 1, column: (err.mark.column ?? 0) + 1 } : {};
   return { code: config ? "config" : "build", ...file ? { file } : {}, ...at, message: err.reason || text.split("\n")[0], text };
 }
@@ -5311,6 +5472,7 @@ function openDevSession2(input, o) {
 }
 export {
   ConfigError,
+  PageClashError,
   build2 as build,
   composePage,
   indexNav,

package/dist/package/types/core/build.d.ts

@@ -204,6 +204,8 @@ export interface BuiltPage {
 /** What the site-level files need from every unit. Small: a few strings per page. */
 export interface SiteState {
     redirects: RedirectInput[];
+    /** What the build says about the content, not a problem, by unit prefix (replaced when a unit is built again). */
+    notes: Map<string, string[]>;
     /** The sidebar items kept between pages (src/theme/regions.ts). */
     navCache: NavCache;
     /** Site path ("en/latest/guide/x") → output file relative to the site root. */
@@ -226,6 +228,8 @@ export interface SiteState {
     stubs: string[];
     /** A dev session's: what pass 1 read from each page, kept between its rebuilds (src/core/scan-cache.ts). */
     scan?: ScanCache;
+    /** A dev session's: called as each unit's pass 1 starts and ends, so it knows which problems pass 1 reported (src/core/dev.ts). */
+    scanned?: (unit: BuildUnit, at: "start" | "end") => void;
     /** Included templates' parses (false: none kept), kept as long as the state: a dev session's unit rebuilds keep it. */
     parseCache: ParseCache | false;
     /** Template time left for the build, or for a dev session's current request. */
@@ -260,6 +264,11 @@ export interface BuildResult {
     warnings: string[];
     /** The warnings as data, one per warning, in the same order. */
     problems: BuildProblem[];
+    /**
+     * What the build says that is not a problem: a content page standing as a mounted API's root
+     * (@dogsbay/site-files' `mountRootNote`), once per mount. The CLI prints them as the Astro pipeline does.
+     */
+    notes: string[];
     stats: BuildStats;
     config: SiteConfig;
 }
@@ -400,6 +409,14 @@ export declare function selectUnits(allUnits: BuildUnit[], names: string[] | und
  * yes only loads KaTeX early; code is skipped, its `$` is not math.
  */
 export declare function mayHaveMath(v: unknown, inProps?: boolean): boolean;
+/** A page an API mounted beside it would land on: the build stops, on that page's file. */
+export declare class PageClashError extends Error {
+    /** The project path of the other page (or spec). */
+    readonly file: string;
+    constructor(message: string, 
+    /** The project path of the other page (or spec). */
+    file: string);
+}
 export interface LoadedTheme {
     templates: ThemeTemplates;
     themeCss?: string;

package/dist/package/types/core/config.d.ts

@@ -32,6 +32,12 @@ export interface SourceDef {
     name?: string;
     /** What the source holds: Dogsbay-MD pages (the default) or an OpenAPI spec, a page per operation. */
     from?: "dogsbay-md" | "openapi";
+    /**
+     * Where an OpenAPI source's pages go inside its version and locale (`reference/rest-api`), beside
+     * the Markdown it belongs to: its root page is the mount, and a content page there stands in for it
+     * (@dogsbay/site-files mounts.ts, plans/openapi-mount.md). Not with `name:`, which puts a source outside its version.
+     */
+    mount?: string;
     version?: string;
     locale?: string;
     attributes?: Record<string, unknown>;
@@ -258,6 +264,8 @@ export declare function unitOfPath<U extends {
 export interface UnitMember {
     source: SourceDef;
     namespace: string;
+    /** A mounted OpenAPI source's mount (`source.mount`): its pages go there, inside the unit. */
+    mount?: string;
 }
 /** One independent build: one or more content roots published under a locale/version prefix. */
 export interface BuildUnit {

package/dist/package/types/core/dev.d.ts

@@ -43,6 +43,8 @@ export interface DevSession {
     change(paths: string[]): Promise<ChangeResult>;
     /** Warnings not handed out yet (the start's, then those of each change and page render). */
     takeWarnings(): string[];
+    /** What the site's build says that is not a problem (BuildResult.notes: a content page standing as a mounted API's root), as it stands now. */
+    notes(): string[];
     /**
      * The same warnings as data, not handed out yet (its own count: taking one kind leaves the other):
      * the file each is about as a project path, with its line when known, and a code.
@@ -76,6 +78,15 @@ export interface ChangeResult {
      * their pages), `page` (pages marked stale), `asset` (files replaced), `none` (nothing it builds).
      */
     handled: "full" | "unit" | "page" | "asset" | "none";
+    /**
+     * The source files (project paths) of the pages whose earlier warnings no longer stand: drop
+     * them, then read `takeProblems()`. A listed page that still exists renders again when asked for
+     * (`get`, `diagnostics`), and its warnings are in `takeProblems()` once that resolves, so one that
+     * brings none is clean. Removed pages are listed too. After a `full` change, every page before
+     * and after, and `takeProblems()` starts again from the first. Pages with no source file (tag
+     * pages, translation stubs) are not listed; pages not listed keep their warnings.
+     */
+    stale: string[];
     ms: number;
 }
 /**

package/dist/package/types/core/openapi-pages.d.ts

@@ -0,0 +1,31 @@
+import type { BuildUnit, SiteConfig, UnitMember } from "./config.js";
+import type { FileContent } from "./build.js";
+import { openApiSourcePages } from "./resolve.js";
+type Got = Exclude<Awaited<ReturnType<typeof openApiSourcePages>>, {
+    error: string;
+}>;
+export interface PlacedApiPage {
+    /** In the unit: under the namespace or the mount (the root page is the mount itself). */
+    slug: string;
+    /** Output file relative to the unit: the root and the tag pages are folders of the pages under them (`api/pets/`). */
+    out: string;
+    isIndex: boolean;
+    page: Got["pages"][number];
+}
+export type PlacedApi = {
+    missing: true;
+} | {
+    spec: string;
+    error: string;
+} | {
+    spec: string;
+    pages: PlacedApiPage[];
+    nav: Got["nav"];
+    segs: string[];
+};
+/** The path segments of `site.url` (`https://x.github.io/docs/` → ["docs"]). */
+export declare function urlPathOf(url: string | undefined): string[];
+/** An OpenAPI member's pages, placed in its unit. */
+export declare function placeApiPages(cfg: SiteConfig, unit: BuildUnit, m: UnitMember, files: Map<string, FileContent>, readText: (c: FileContent) => Promise<string>): Promise<PlacedApi>;
+export declare function apiPageOuts(cfg: SiteConfig, unit: BuildUnit, m: UnitMember, files: Map<string, FileContent>, readText: (c: FileContent) => Promise<string>): Promise<[string, string][]>;
+export {};

package/dist/package/types/package/browser.d.ts

@@ -20,6 +20,7 @@ export declare function openDevSession(input: BuildInput & {
 }, o?: DevOptions): Promise<DevSession>;
 export { prebuiltSiteCss };
 export type { BuildInput, BuildResult, FileContent, OutputContent, SinkContent, SiteCssBuilder, BuiltPage, HighlightPool, BuildProblem, PageDiagnostic } from "../core/build.js";
+export { PageClashError } from "../core/build.js";
 export type { ChangeResult, DevOptions, DevSession } from "../core/dev.js";
 export { parseConfig, projectRoots, ConfigError, type SiteConfig, type DiagramEngine } from "../core/config.js";
 export type { DiagramRenderer, DiagramRenderers, DiagramRequest, DiagramResult } from "../core/diagrams.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/ssg",
-  "version": "0.2.0-beta.140",
+  "version": "0.2.0-beta.142",
   "type": "module",
   "description": "Documentation static site generator for Dogsbay-MD that builds inside Cloudflare Workers and publishes sites that work offline",
   "license": "Apache-2.0",
@@ -49,38 +49,38 @@
     "tailwindcss": "^4.3.2"
   },
   "peerDependencies": {
-    "@dogsbay/elements": "0.2.0-beta.140",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.140",
-    "@dogsbay/format-openapi": "0.2.0-beta.140",
-    "@dogsbay/format-topicmap": "0.2.0-beta.140",
-    "@dogsbay/highlight": "0.2.0-beta.140",
-    "@dogsbay/minja": "0.2.0-beta.140",
-    "@dogsbay/primitives": "0.2.0-beta.140",
-    "@dogsbay/render-html": "0.2.0-beta.140",
-    "@dogsbay/search": "0.2.0-beta.140",
-    "@dogsbay/serialize-core": "0.2.0-beta.140",
-    "@dogsbay/site-check": "0.2.0-beta.140",
-    "@dogsbay/site-files": "0.2.0-beta.140",
-    "@dogsbay/types": "0.2.0-beta.140"
+    "@dogsbay/elements": "0.2.0-beta.142",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.142",
+    "@dogsbay/format-openapi": "0.2.0-beta.142",
+    "@dogsbay/format-topicmap": "0.2.0-beta.142",
+    "@dogsbay/highlight": "0.2.0-beta.142",
+    "@dogsbay/minja": "0.2.0-beta.142",
+    "@dogsbay/primitives": "0.2.0-beta.142",
+    "@dogsbay/render-html": "0.2.0-beta.142",
+    "@dogsbay/search": "0.2.0-beta.142",
+    "@dogsbay/serialize-core": "0.2.0-beta.142",
+    "@dogsbay/site-check": "0.2.0-beta.142",
+    "@dogsbay/site-files": "0.2.0-beta.142",
+    "@dogsbay/types": "0.2.0-beta.142"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.12.1",
     "@cloudflare/workers-types": "^5.20260921.1",
-    "@dogsbay/elements": "0.2.0-beta.140",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.140",
-    "@dogsbay/format-openapi": "0.2.0-beta.140",
-    "@dogsbay/format-topicmap": "0.2.0-beta.140",
-    "@dogsbay/highlight": "0.2.0-beta.140",
-    "@dogsbay/icons": "0.2.0-beta.140",
-    "@dogsbay/minja": "0.2.0-beta.140",
-    "@dogsbay/primitives": "0.2.0-beta.140",
-    "@dogsbay/render-html": "0.2.0-beta.140",
-    "@dogsbay/search": "0.2.0-beta.140",
-    "@dogsbay/serialize-core": "0.2.0-beta.140",
-    "@dogsbay/site-check": "0.2.0-beta.140",
-    "@dogsbay/site-files": "0.2.0-beta.140",
-    "@dogsbay/types": "0.2.0-beta.140",
-    "@dogsbay/ui": "0.2.0-beta.140",
+    "@dogsbay/elements": "0.2.0-beta.142",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.142",
+    "@dogsbay/format-openapi": "0.2.0-beta.142",
+    "@dogsbay/format-topicmap": "0.2.0-beta.142",
+    "@dogsbay/highlight": "0.2.0-beta.142",
+    "@dogsbay/icons": "0.2.0-beta.142",
+    "@dogsbay/minja": "0.2.0-beta.142",
+    "@dogsbay/primitives": "0.2.0-beta.142",
+    "@dogsbay/render-html": "0.2.0-beta.142",
+    "@dogsbay/search": "0.2.0-beta.142",
+    "@dogsbay/serialize-core": "0.2.0-beta.142",
+    "@dogsbay/site-check": "0.2.0-beta.142",
+    "@dogsbay/site-files": "0.2.0-beta.142",
+    "@dogsbay/types": "0.2.0-beta.142",
+    "@dogsbay/ui": "0.2.0-beta.142",
     "@mermanjs/web": "0.7.0",
     "@playwright/test": "1.61.1",
     "@types/node": "^22.10.0",