yamlover 0.3.55 → 0.3.56

package/dist/server.js

@@ -63317,6 +63317,22 @@ var Store = class {
   get stale() {
     return this._stale;
   }
+  /** PREPARED-STATEMENT CACHE — one StatementSync per distinct SQL, reused for the life of the
+   *  handle. The read methods below run once per NODE during a projection (the server's
+   *  envelopeDeps asks `node`/`entries`/`unrealizedRefs` about every member it serializes), so a
+   *  fresh `db.prepare()` per call meant ~200k compilations to answer ONE request over a 29k-node
+   *  document — measured at ~97% of a 4.5s /api/content response, against 0.16s of actual row
+   *  reading. Statements survive DML (the DELETE/INSERT churn of a re-index); the only DDL this
+   *  class runs is in the constructor, before anything can be cached. */
+  stmts = /* @__PURE__ */ new Map();
+  stmt(sql) {
+    let s2 = this.stmts.get(sql);
+    if (!s2) {
+      s2 = this.db.prepare(sql);
+      this.stmts.set(sql, s2);
+    }
+    return s2;
+  }
   constructor(dbPath) {
     this.db = new DatabaseSync(dbPath);
     this.db.exec("PRAGMA journal_mode = WAL;");
@@ -63329,6 +63345,7 @@ var Store = class {
     this._stale = ver !== SCHEMA_VERSION;
   }
   close() {
+    this.stmts.clear();
     this.db.close();
   }
   /** Rebuild the whole index from one resolved document: clear, then insert nodes + edges in
@@ -63543,7 +63560,7 @@ var Store = class {
    *  whose on-disk (size, mtime) still matches the manifest has not changed in any way a
    *  reindex could see — Windows reports mere READS as changes via last-access-time updates). */
   file(relPath) {
-    const r2 = this.db.prepare("SELECT * FROM file WHERE path = ?").get(relPath);
+    const r2 = this.stmt("SELECT * FROM file WHERE path = ?").get(relPath);
     return r2 ? { path: r2.path, hash: r2.hash ?? null, size: r2.size, mtimeMs: r2.mtime_ms } : null;
   }
   /** Manifest entries still lacking a content hash (large blobs the walk never read), smallest
@@ -63583,7 +63600,7 @@ var Store = class {
    *  authority links — in source order. These are the entries {@link entries} cannot list (no
    *  edge exists), returned so a projection can still show the authored pointer in place. */
   unrealizedRefs(holder) {
-    return this.db.prepare("SELECT label, pos, raw, edge, external FROM dangling WHERE holder = ? ORDER BY pos").all(holder).map((r2) => ({
+    return this.stmt("SELECT label, pos, raw, edge, external FROM dangling WHERE holder = ? ORDER BY pos").all(holder).map((r2) => ({
       label: r2.label ?? null,
       pos: r2.pos ?? null,
       raw: r2.raw,
@@ -63593,23 +63610,23 @@ var Store = class {
   }
   /** A node's attributes (null if no such path). */
   node(path12) {
-    const row = this.db.prepare("SELECT * FROM node WHERE path = ?").get(path12);
+    const row = this.stmt("SELECT * FROM node WHERE path = ?").get(path12);
     return row ? rowToNode(row) : null;
   }
   /** Direct containment children of a node, in source order (by `pos`). */
   children(path12) {
-    return this.db.prepare("SELECT to_path, label, pos FROM edge WHERE from_path = ? AND kind = 'contain' ORDER BY pos").all(path12).map((r2) => ({ to: r2.to_path, label: r2.label ?? null, pos: r2.pos ?? null }));
+    return this.stmt("SELECT to_path, label, pos FROM edge WHERE from_path = ? AND kind = 'contain' ORDER BY pos").all(path12).map((r2) => ({ to: r2.to_path, label: r2.label ?? null, pos: r2.pos ?? null }));
   }
   /** ALL of a node's entries in source order — containment children AND `*`/`~` pointer
    *  entries (ref/back). Unlike {@link children} this keeps positional pointers (`- *file`)
    *  in place, so an array that mixes inline values and pointers (e.g. a chapter's `chunks`)
    *  projects in full. `kind` says whether `to` is an owned child (contain) or a pointer target. */
   entries(path12) {
-    return this.db.prepare("SELECT to_path, label, pos, kind FROM edge WHERE from_path = ? AND kind IN ('contain','ref','back') ORDER BY pos").all(path12).map((r2) => ({ to: r2.to_path, label: r2.label ?? null, pos: r2.pos ?? null, kind: r2.kind }));
+    return this.stmt("SELECT to_path, label, pos, kind FROM edge WHERE from_path = ? AND kind IN ('contain','ref','back') ORDER BY pos").all(path12).map((r2) => ({ to: r2.to_path, label: r2.label ?? null, pos: r2.pos ?? null, kind: r2.kind }));
   }
   /** Whether a node has any containment children (expandable in the TOC). */
   hasChildren(path12) {
-    const r2 = this.db.prepare("SELECT 1 FROM edge WHERE from_path = ? AND kind = 'contain' LIMIT 1").get(path12);
+    const r2 = this.stmt("SELECT 1 FROM edge WHERE from_path = ? AND kind = 'contain' LIMIT 1").get(path12);
     return r2 != null;
   }
   /** The containment subtree rooted at `path`, up to `depth` levels (TOC). A recursive CTE
@@ -63618,7 +63635,7 @@ var Store = class {
    *  not contents: they are pruned here with their whole subtrees, so every TOC consumer gets the
    *  same view without re-filtering. */
   toc(path12 = ":", depth = Infinity) {
-    const rows = this.db.prepare(
+    const rows = this.stmt(
       `WITH RECURSIVE sub(from_path, to_path, label, pos, lvl) AS (
            SELECT e.from_path, e.to_path, e.label, e.pos, 1 FROM edge e
              JOIN node t ON t.path = e.to_path
@@ -63654,8 +63671,8 @@ var Store = class {
   /** Edges in/out of a node, by kind. `derived` inverses are computed here on demand (never
    *  stored) per ENGINE.md — for each ref/back into/out of the node, the reverse direction. */
   relationships(path12) {
-    const out = this.db.prepare("SELECT * FROM edge WHERE from_path = ? AND kind != 'contain'").all(path12).map(rowToEdge);
-    const inc = this.db.prepare("SELECT * FROM edge WHERE to_path = ? AND kind != 'contain'").all(path12).map(rowToEdge);
+    const out = this.stmt("SELECT * FROM edge WHERE from_path = ? AND kind != 'contain'").all(path12).map(rowToEdge);
+    const inc = this.stmt("SELECT * FROM edge WHERE to_path = ? AND kind != 'contain'").all(path12).map(rowToEdge);
     const derivedIn = inc.filter((e3) => e3.kind === "ref" || e3.kind === "back").map((e3) => ({ from: e3.to, to: e3.from, label: e3.label, kind: "derived", pos: null }));
     return { out, in: [...inc, ...derivedIn] };
   }
@@ -63760,6 +63777,11 @@ var LossyError = class extends Error {
 function dq(s2) {
   return JSON.stringify(s2);
 }
+function hexValue(tok) {
+  const signed = tok[0] === "-" || tok[0] === "+";
+  const mag = Number(signed ? tok.slice(1) : tok);
+  return tok[0] === "-" ? -mag : mag;
+}
 function seqMarkLen(text, yaml = false) {
   if (text === "-" || text.startsWith("- ")) return 1;
   if (!yaml && (text === "-:" || text.startsWith("-: "))) return 2;
@@ -65007,7 +65029,7 @@ function plainScalar(text) {
   if (/^[-+]?\.(?:inf|Inf|INF)$/.test(t3)) return { kind: "scalar", value: t3[0] === "-" ? -Infinity : Infinity, raw: text };
   if (/^\.(?:nan|NaN|NAN)$/.test(t3)) return { kind: "scalar", value: NaN, raw: text };
   if (/^[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(t3)) return { kind: "scalar", value: Number(t3), raw: text };
-  if (/^[-+]?0x[0-9a-fA-F]+$/.test(t3)) return { kind: "scalar", value: Number(t3), raw: text };
+  if (/^[-+]?0x[0-9a-fA-F]+$/.test(t3)) return { kind: "scalar", value: hexValue(t3), raw: text };
   return { kind: "scalar", value: t3, raw: text };
 }
 function backslashUnescape(s2) {
@@ -65314,13 +65336,25 @@ function isDelim(c3) {
   return WS.has(c3) || c3 === "," || c3 === ":" || c3 === "{" || c3 === "}" || c3 === "[" || c3 === "]" || c3 === '"' || c3 === "'" || c3 === "/";
 }
 function json5number(tok) {
-  if (/^[+-]?0[xX][0-9a-fA-F]+$/.test(tok)) return Number(tok);
+  if (/^[+-]?0[xX][0-9a-fA-F]+$/.test(tok)) return hexValue(tok);
   if (/^[+-]?Infinity$/.test(tok)) return tok[0] === "-" ? -Infinity : Infinity;
   if (/^[+-]?NaN$/.test(tok)) return NaN;
   if (/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(tok)) return Number(tok);
   return void 0;
 }
 
+// ../parser/ts/src/overlay-keys.ts
+var OVERLAY_KEY = ".yo";
+var LEGACY_OVERLAY_KEY = "yo";
+var overlayKeyAlts = [OVERLAY_KEY, LEGACY_OVERLAY_KEY];
+var FRAGMENTS_SUBKEY = "fragments";
+var THUMBNAILS_SUBKEY = "thumbnails";
+var LEGACY_THUMBNAILS_KEY = "yamlover-thumbnails";
+var LEGACY_ANNOTATIONS_KEY = "yamlover-annotations";
+var isOverlayKey = (k) => k === OVERLAY_KEY || k === LEGACY_OVERLAY_KEY;
+var isHiddenEntryKey = (k) => typeof k === "string" && (k.startsWith(".") || k === LEGACY_OVERLAY_KEY || k === LEGACY_THUMBNAILS_KEY || k === LEGACY_ANNOTATIONS_KEY);
+var isFragmentSegs = (segs) => segs.length >= 3 && isOverlayKey(segs[segs.length - 3]) && segs[segs.length - 2] === FRAGMENTS_SUBKEY;
+
 // ../engine/ts/src/mounts.ts
 import fs from "node:fs";
 import path from "node:path";
@@ -65489,11 +65523,21 @@ function* walkTreeGen(absDir, opts = {}) {
     builtinDefs = (graftTaxonomy() ?? builtinYamloverGraft()).defs;
   }
   applySchemas(root, defsRoot, builtinDefs);
+  stampHiddenKeys(root);
   return {
     doc: { root, source: { concrete: "dir", uri: absDir } },
     files: [...ctx.files.values()]
   };
 }
+function stampHiddenKeys(root) {
+  for (const e3 of root.entries ?? []) {
+    if (isPointer(e3.value)) continue;
+    if (isHiddenEntryKey(e3.key) && e3.value.meta?.hidden !== true) {
+      e3.value.meta = { ...e3.value.meta, hidden: true };
+    }
+    stampHiddenKeys(e3.value);
+  }
+}
 function reindex(store, absDir, opts = {}) {
   const prev = store.stale ? /* @__PURE__ */ new Map() : store.manifest();
   const { doc, files } = walkTree(absDir, { ...opts, cache: opts.cache ?? manifestCache(prev) });
@@ -65525,6 +65569,7 @@ async function reindexAsyncDoc(store, absDir, opts = {}) {
     const t0 = Date.now();
     try {
       snap.root.meta = { ...snap.root.meta, documentRoot: true };
+      stampHiddenKeys(snap.root);
       store.indexDocument({ root: snap.root, source: { concrete: "dir", uri: absDir } });
       minInterval = Math.max(partialMs, 5 * (Date.now() - t0));
       const added = snap.filePaths.slice(reported);
@@ -65573,6 +65618,7 @@ async function reindexPathAsync(store, absDir, cachedDoc, changedRel, opts = {})
   while (!r2.done) r2 = gen.next();
   target.arr[target.i].value = r2.value;
   applySchemas(cachedDoc.root, findDefsRoot(absDir), graftDefs(cachedDoc.root));
+  stampHiddenKeys(cachedDoc.root);
   const relPrefix = dirSegs.join("/") + "/";
   const P = pathOfSegs(dirSegs);
   const prevSub = new Map([...prev].filter(([k]) => k.startsWith(relPrefix)));
@@ -65609,7 +65655,7 @@ async function countChildren(absRoot, opts, onCount) {
     }
     let top = 0;
     for (const e3 of entries) {
-      if (skipInYamloverDir(e3.name)) continue;
+      if (skipInYamloverDir(e3.name) && e3.name !== BODY_FILE && e3.name !== "meta.yo") continue;
       const abs = path2.join(dir, e3.name);
       if (opts.ignore?.(abs)) continue;
       n2++;
@@ -65791,8 +65837,9 @@ function* dirNode(dir, ctx, inherited) {
 }
 function* yamloverDirNode(absYamlover, ctx) {
   let names3;
+  const isRawOverlay = (n2) => n2 === BODY_FILE || n2 === "meta.yo";
   try {
-    names3 = fs2.readdirSync(absYamlover).filter((n2) => !skipInYamloverDir(n2)).filter((n2) => !ctx.opts.ignore?.(path2.join(absYamlover, n2))).sort();
+    names3 = fs2.readdirSync(absYamlover).filter((n2) => !skipInYamloverDir(n2) || isRawOverlay(n2)).filter((n2) => !ctx.opts.ignore?.(path2.join(absYamlover, n2))).sort();
   } catch {
     return null;
   }
@@ -65800,6 +65847,16 @@ function* yamloverDirNode(absYamlover, ctx) {
   ctx.open?.push({ name: path2.basename(absYamlover), entries, meta: { hidden: true } });
   for (const name of names3) {
     const abs = path2.join(absYamlover, name);
+    if (isRawOverlay(name)) {
+      try {
+        if (fs2.statSync(abs).size > MAX_TEXT_BYTES) continue;
+        const text = readTracked(ctx, abs).toString("utf8");
+        entries.push({ key: name, edge: "contain", value: { kind: "scalar", value: text, raw: text, meta: { derivedFormat: "text/plain", span: { uri: abs, start: 0, end: text.length } } } });
+        yield { done: ++ctx.count, path: rel(ctx, abs) };
+      } catch {
+      }
+      continue;
+    }
     const child = yield* childNode(abs, void 0, ctx);
     entries.push({ key: name, edge: "contain", value: child });
     yield { done: ++ctx.count, path: rel(ctx, abs) };
@@ -65824,10 +65881,12 @@ function* childNode(abs, m, ctx) {
   if (fmt && (DOC_FORMATS[fmt] || TEXT_FORMATS.has(fmt))) {
     if (stat.size > MAX_DOC_BYTES) return blob(abs, fmt, ctx);
     if (DOC_FORMATS[fmt]) return parsedDoc(abs, DOC_FORMATS[fmt], ctx);
+    if (stat.size > MAX_TEXT_BYTES) return blob(abs, fmt, ctx);
     return textScalar(abs, fmt, ctx);
   }
   if (fmt) return blob(abs, fmt, ctx);
   if (looksBinary(abs)) return blob(abs, "application/octet-stream", ctx);
+  if (!PARSED_EXTS.has(ext) || path2.basename(abs).startsWith(".")) return blob(abs, "text/plain", ctx);
   return parsedScalar(abs, ext, ctx);
 }
 function decodeConcrete(abs, concrete, format, stat, ctx) {
@@ -65966,8 +66025,7 @@ function applySchemas(root, defsRoot, builtinDefs) {
     return { name: null, node: v };
   };
   const isContainerSchema = (n2) => !!field(n2, "members") || !!field(n2, "others") || !!field(n2, "properties") || !!field(n2, "items") || !!field(n2, "allOf") || ["object", "variant", "omni", "mixed", "kseq", "array"].includes(str(n2, "type") ?? "");
-  const OVERLAY_KEYS = /* @__PURE__ */ new Set(["yo"]);
-  const elemIsContainer = (el) => el.kind === "mapping" || el.meta?.dirBacked === true || (el.entries ?? []).some((e3) => e3.key == null || !OVERLAY_KEYS.has(e3.key));
+  const elemIsContainer = (el) => el.kind === "mapping" || el.meta?.dirBacked === true || (el.entries ?? []).some((e3) => e3.key == null || !isHiddenEntryKey(e3.key));
   const ordinalElems = (inst) => {
     const anchoredKeys = new Set(inst.meta?.anchored ?? []);
     return (inst.entries ?? []).filter((e3) => (e3.key == null || anchoredKeys.has(e3.key)) && !isPointer(e3.value) && e3.value.meta?.yo !== true && !(e3.value.meta?.schema && isPointer(e3.value.meta.schema)));
@@ -66007,7 +66065,7 @@ function applySchemas(root, defsRoot, builtinDefs) {
         if (e3.value.meta?.schema && isPointer(e3.value.meta.schema)) continue;
         if (e3.value.meta?.yo === true) continue;
         const declared = (membersNode ? field(membersNode, e3.key) : null) ?? (props && !isPointer(props) ? field(props, e3.key) : null);
-        const sub = declared ?? (others && !OVERLAY_KEYS.has(e3.key) ? others : null) ?? addl;
+        const sub = declared ?? (isHiddenEntryKey(e3.key) ? null : others ?? addl);
         if (sub) apply(e3.value, sub, depth + 1);
       }
       if (keylessClauses.length) {
@@ -66089,14 +66147,14 @@ function applyBody(file, node, ctx) {
     }
     const ci = childAt.get(e3.key);
     if (ci !== void 0 && children2[ci]) {
-      children2[ci] = augmentEntry(children2[ci], e3);
+      children2[ci] = e3.key === YAMLOVER_DIR ? mergeOverlayEntry(children2[ci], e3) : augmentEntry(children2[ci], e3);
       continue;
     }
     bodyAt.set(e3.key, bodyOrder.length);
     bodyOrder.push(e3);
   }
   const unlisted = children2.filter((e3) => e3 !== null);
-  const remainder = unlisted.length > 0;
+  const remainder = unlisted.some((e3) => isPointer(e3.value) || e3.value.meta?.hidden !== true);
   const meta = anchored.length > 0 ? { ...meta0, anchored } : meta0;
   const entries = [...bodyOrder, ...unlisted];
   if (body.kind === "mapping" && (body.array || bodyEntries.length > 0 && bodyEntries.every((e3) => e3.key === null))) {
@@ -66104,7 +66162,8 @@ function applyBody(file, node, ctx) {
   }
   if (body.kind === "scalar") {
     const emptySelf = body.value === null && (body.raw == null || body.raw.trim() === "");
-    if (!(emptySelf && entries.length > 0)) {
+    const visible = entries.some((e3) => isPointer(e3.value) || e3.value.meta?.hidden !== true);
+    if (!(emptySelf && visible)) {
       return { kind: "scalar", value: body.value, raw: body.raw, entries, array: false, meta };
     }
   }
@@ -66121,6 +66180,29 @@ function augmentEntry(base, overlay2) {
   };
   return { key: base.key, edge: "contain", value };
 }
+function mergeOverlayEntry(dirE, bodyE) {
+  if (isPointer(dirE.value) || isPointer(bodyE.value)) return bodyE;
+  return { key: dirE.key, edge: "contain", value: mergeOverlayNode(dirE.value, bodyE.value) };
+}
+function mergeOverlayNode(disk, body) {
+  const out = (body.entries ?? []).slice();
+  const at = /* @__PURE__ */ new Map();
+  out.forEach((e3, i2) => {
+    if (typeof e3.key === "string") at.set(e3.key, i2);
+  });
+  for (const d2 of disk.entries ?? []) {
+    const i2 = typeof d2.key === "string" ? at.get(d2.key) : void 0;
+    if (i2 === void 0) {
+      out.push(d2);
+      continue;
+    }
+    const b = out[i2];
+    if (!isPointer(b.value) && !isPointer(d2.value)) {
+      out[i2] = { ...b, value: mergeOverlayNode(d2.value, b.value) };
+    }
+  }
+  return { ...body, entries: out, meta: { ...disk.meta, ...body.meta, hidden: true } };
+}
 function pointerLeafKey(v) {
   if (!isPointer(v)) return null;
   const last = v.steps[v.steps.length - 1];
@@ -66164,6 +66246,10 @@ var EXT_FORMAT = {
   ".heif": "image/heic",
   ".fb2": "application/x-fictionbook+xml",
   ".epub": "application/epub+zip",
+  // A stored mail message. Opaque bytes, never inline text: its own headers name its charset
+  // (koi8-r and windows-1251 are the norm in an old archive) and its parts carry their own
+  // transfer encodings, so decoding belongs to the renderer, not to the walk.
+  ".eml": "message/rfc822",
   ".html": "text/html",
   ".htm": "text/html",
   ".md": "text/markdown",
@@ -66190,9 +66276,42 @@ var EXT_FORMAT = {
   ".txt": "text/plain",
   ".text": "text/plain",
   ".log": "text/plain",
-  ".ini": "text/plain"
+  ".ini": "text/plain",
+  // FOREIGN SOURCE CODE — text this project does not speak, NAMED so it stops looking like
+  // a broken yamlover file. Held inline as UTF-8 (they are, in practice) and shown verbatim;
+  // without these a saved web page's minified `.js` reached the yamlover parser and either
+  // degraded loudly or parsed into garbage (a 4 KiB key), both indistinguishable from a `.yo`
+  // its author must fix.
+  ".js": "text/javascript",
+  ".mjs": "text/javascript",
+  ".cjs": "text/javascript",
+  ".ts": "text/typescript",
+  ".tsx": "text/typescript",
+  ".jsx": "text/javascript",
+  ".css": "text/css",
+  ".py": "text/x-python",
+  ".sh": "text/x-shellscript",
+  ".sql": "text/x-sql",
+  ".xml": "text/xml",
+  ".jsonl": "application/x-ndjson"
 };
-var TEXT_FORMATS = /* @__PURE__ */ new Set(["text/markdown", "text/asciidoc", "text/x-plantuml", "text/csv", "text/tab-separated-values"]);
+var TEXT_FORMATS = /* @__PURE__ */ new Set([
+  "text/markdown",
+  "text/asciidoc",
+  "text/x-plantuml",
+  "text/csv",
+  "text/tab-separated-values",
+  // foreign source code: a string scalar carrying its own bytes, never parsed
+  "text/javascript",
+  "text/typescript",
+  "text/css",
+  "text/x-python",
+  "text/x-shellscript",
+  "text/x-sql",
+  "text/xml",
+  "application/x-ndjson"
+]);
+var PARSED_EXTS = /* @__PURE__ */ new Set(["", ".yo", ".yamlover", ".yaml", ".yml", ".json", ".json5", ".json5p"]);
 var DOC_FORMATS = {
   "yamlover": "yamlover",
   "yaml": "yaml",
@@ -66322,19 +66441,12 @@ function scalarTok(s2) {
   if (typeof v === "boolean") return v ? "true" : "false";
   if (typeof v === "string") return JSON.stringify(v);
   const raw = s2.raw.trim();
-  if (raw !== "" && Object.is(json5number2(raw), v)) return raw;
+  if (raw !== "" && Object.is(json5number(raw), v)) return raw;
   if (Number.isNaN(v)) return "NaN";
   if (v === Infinity) return "Infinity";
   if (v === -Infinity) return "-Infinity";
   return String(v);
 }
-function json5number2(tok) {
-  if (/^[+-]?0[xX][0-9a-fA-F]+$/.test(tok)) return Number(tok);
-  if (/^[+-]?Infinity$/.test(tok)) return tok[0] === "-" ? -Infinity : Infinity;
-  if (/^[+-]?NaN$/.test(tok)) return NaN;
-  if (/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(tok)) return Number(tok);
-  return void 0;
-}
 
 // ../parser/ts/src/serialize-yamlover.ts
 var STEP2 = 2;
@@ -66766,7 +66878,8 @@ function rawBlock(s2) {
   const header = nl < 0 ? raw : raw.slice(0, nl);
   if (!/^[|>][+-]?$/.test(header)) return null;
   const lines = nl < 0 ? [] : raw.slice(nl + 1).split("\n");
-  if (lines.length > 0 && /^[ \t]/.test(lines[0])) return null;
+  const firstRawContent = lines.find((l2) => l2 !== "");
+  if (firstRawContent !== void 0 && /^[ \t]/.test(firstRawContent)) return null;
   if (lines.some((l2) => l2 !== "" && /^ +$/.test(l2))) return null;
   const folded = header[0] === ">";
   const chomp = header.includes("-") ? "strip" : header.includes("+") ? "keep" : "clip";
@@ -66841,7 +66954,8 @@ function blockLines(v) {
   const body = v.slice(0, end);
   if (body === "") return null;
   const lines = body.split("\n");
-  if (/^[ \t]/.test(lines[0])) return null;
+  const firstContent = lines.find((l2) => l2 !== "");
+  if (firstContent !== void 0 && /^[ \t]/.test(firstContent)) return null;
   if (lines.some((l2) => l2 !== "" && /^ +$/.test(l2))) return null;
   const header = trailing === 0 ? "|-" : trailing === 1 ? "|" : "|+";
   for (let i2 = 1; i2 < trailing; i2++) lines.push("");
@@ -67656,6 +67770,15 @@ function keyName(portion) {
   if (steps.length !== 1 || steps[0].sel !== "key") throw new SyntaxError(`query: bad name segment "${portion}"`);
   return steps[0].name;
 }
+function isPointerShapedQuery(text) {
+  try {
+    return parseQuery(text).portions.every(
+      (p2) => p2.kind === "key" || p2.kind === "index" || p2.kind === "nullkey" || p2.kind === "up"
+    );
+  } catch {
+    return false;
+  }
+}
 var YAMLOVER_AUTHORITY3 = "yamlover.inthemoon.net";
 function evalQuery(s2, text, from = ":") {
   const q = parseQuery(text);
@@ -67893,11 +68016,11 @@ function doubledFragmentDiagnostics(doc) {
     const entries = node.entries ?? [];
     entries.forEach((e3, i2) => {
       const key = typeof e3.key === "string" ? e3.key : null;
-      if (key === "fragments" && segs[segs.length - 1] === "fragments" && segs[segs.length - 2] === "yo") {
+      if (key === "fragments" && segs[segs.length - 1] === "fragments" && isOverlayKey(segs[segs.length - 2])) {
         out.push({
           code: "annotations/doubled-fragments",
           severity: "warning",
-          message: `a \`fragments:\` mapping nested inside \`yo: fragments:\` \u2014 left by a pre-fix annotate over the flat spelling`,
+          message: `a \`fragments:\` mapping nested inside \`${segs[segs.length - 2]}: fragments:\` \u2014 left by a pre-fix annotate over the flat spelling`,
           path: ":" + [...segs, key].join(":"),
           hint: "move its child fragments up one level, into the enclosing fragments mapping"
         });
@@ -67908,6 +68031,27 @@ function doubledFragmentDiagnostics(doc) {
   walk(doc.root, []);
   return out;
 }
+function legacyOverlaySpellingDiagnostics(doc) {
+  const out = [];
+  const walk = (node, segs) => {
+    const entries = node.entries ?? [];
+    entries.forEach((e3, i2) => {
+      const key = typeof e3.key === "string" ? e3.key : null;
+      if (key === LEGACY_OVERLAY_KEY || key === LEGACY_THUMBNAILS_KEY) {
+        out.push({
+          code: "annotations/legacy-overlay-spelling",
+          severity: "info",
+          message: `the legacy \`${key}:\` spelling \u2014 the canonical key is ${key === LEGACY_OVERLAY_KEY ? "`.yo:`" : "`.yo: thumbnails:`"}`,
+          path: ":" + [...segs, key].join(":"),
+          hint: "migrate the tree with tools/migrate-dot-yo.mjs (legacy spellings stay readable forever)"
+        });
+      }
+      if (e3.value !== null && typeof e3.value === "object") walk(e3.value, [...segs, key ?? String(i2)]);
+    });
+  };
+  walk(doc.root, []);
+  return out;
+}
 function deadLinkTargets(doc, store) {
   const out = /* @__PURE__ */ new Set();
   for (const l2 of scanTextLinks(doc)) {
@@ -67924,10 +68068,8 @@ function logDeadLinks(found, log, max = 8) {
 }
 
 // src/server/embed.ts
-var ANNOTATIONS_KEY = "yamlover-annotations";
-var YO_KEY = "yo";
-var FRAGMENTS_SUBKEY = "fragments";
-var THUMBNAILS_KEY = "yamlover-thumbnails";
+var ANNOTATIONS_KEY = LEGACY_ANNOTATIONS_KEY;
+var stepAlts = (s2) => typeof s2 === "string" ? [s2] : s2;
 var indentOf = (line) => {
   let i2 = 0;
   while (line[i2] === " ") i2++;
@@ -67942,7 +68084,7 @@ function firstContentIndent(lines) {
   return 0;
 }
 function keyToken(key) {
-  return /^[A-Za-z0-9_][A-Za-z0-9_-]*$/.test(key) && !/^\d+$/.test(key) ? key : JSON.stringify(key);
+  return /^\.?[A-Za-z0-9_][A-Za-z0-9_-]*$/.test(key) && !/^\d+$/.test(key) ? key : JSON.stringify(key);
 }
 function findKeyLine(lines, lo, hi, indent, key) {
   const tok = keyToken(key);
@@ -67960,14 +68102,20 @@ function flatRun(line, keys, k) {
   let rest = line.trim();
   let n2 = 0;
   while (k + n2 < keys.length && rest !== "") {
-    const key = keys[k + n2];
-    const tok = [key, keyToken(key)].find((t3) => rest === `${t3}:` || rest.startsWith(`${t3}: `));
+    const tok = stepAlts(keys[k + n2]).flatMap((key) => [key, keyToken(key)]).find((t3) => rest === `${t3}:` || rest.startsWith(`${t3}: `));
     if (tok === void 0) break;
     rest = rest === `${tok}:` ? "" : rest.slice(tok.length + 2);
     n2++;
   }
   return Math.max(1, n2);
 }
+function findStepLine(lines, lo, hi, indent, step2) {
+  for (const alt of stepAlts(step2)) {
+    const L2 = findKeyLine(lines, lo, hi, indent, alt);
+    if (L2 >= 0) return L2;
+  }
+  return -1;
+}
 function trimBack(lines, floor, end) {
   let e3 = end;
   while (e3 > floor + 1 && !isContentLine(lines[e3 - 1])) e3--;
@@ -68005,11 +68153,10 @@ function bodyUnder(lines, L2, hi, indent) {
 function reachBodyAt(lines, start, within) {
   let { lo, hi, indent } = start;
   for (let k = 0; k < within.length; ) {
-    const key = within[k];
-    const L2 = findKeyLine(lines, lo, hi, indent, key);
+    const L2 = findStepLine(lines, lo, hi, indent, within[k]);
     if (L2 < 0) {
       const at = trimBack(lines, lo - 1, hi);
-      lines.splice(at, 0, `${" ".repeat(indent)}${keyToken(key)}:`);
+      lines.splice(at, 0, `${" ".repeat(indent)}${keyToken(stepAlts(within[k])[0])}:`);
       lo = at + 1;
       hi = at + 1;
       indent += 2;
@@ -68022,10 +68169,21 @@ function reachBodyAt(lines, start, within) {
   }
   return { lo, hi, indent };
 }
+function presentStepAlt(lines, region, step2) {
+  for (const alt of stepAlts(step2)) {
+    if (findKeyLine(lines, region.lo, region.hi, region.indent, alt) >= 0) return alt;
+  }
+  return stepAlts(step2)[0];
+}
+function overlaySpellingAt(text, within) {
+  const lines = text.replace(/\n$/, "").split("\n");
+  const region = within.length === 0 ? { lo: 0, hi: lines.length, indent: firstContentIndent(lines) } : findBody(lines, within);
+  return region ? presentStepAlt(lines, region, overlayKeyAlts) : overlayKeyAlts[0];
+}
 function findBody(lines, within) {
   let region = { lo: 0, hi: lines.length, indent: firstContentIndent(lines) };
   for (let k = 0; k < within.length; ) {
-    const L2 = findKeyLine(lines, region.lo, region.hi, region.indent, within[k]);
+    const L2 = findStepLine(lines, region.lo, region.hi, region.indent, within[k]);
     if (L2 < 0) return null;
     const consumed = flatRun(lines[L2], within, k);
     region = bodyUnder(lines, L2, region.hi, region.indent);
@@ -68088,17 +68246,20 @@ function replaceSeqEntryAt(lines, region, key, render) {
   lines.splice(keyLine, trimBack(lines, keyLine, end) - keyLine, ...render(region.indent));
 }
 function upsertFragment(text, within, slug, render) {
-  return upsertMapEntry(text, within, [YO_KEY, FRAGMENTS_SUBKEY], slug, render);
+  return upsertMapEntry(text, within, [overlayKeyAlts, FRAGMENTS_SUBKEY], slug, render);
 }
 function pruneEmptyKeyAt(lines, region, key) {
-  const L2 = findKeyLine(lines, region.lo, region.hi, region.indent, key);
-  if (L2 < 0) return false;
-  const t3 = lines[L2].trim();
-  if (t3 !== `${key}:` && t3 !== `${keyToken(key)}:`) return false;
-  const body = bodyUnder(lines, L2, region.hi, region.indent);
-  for (let i2 = body.lo; i2 < body.hi; i2++) if (isContentLine(lines[i2])) return false;
-  lines.splice(L2, Math.max(1, body.hi - L2));
-  return true;
+  for (const alt of stepAlts(key)) {
+    const L2 = findKeyLine(lines, region.lo, region.hi, region.indent, alt);
+    if (L2 < 0) continue;
+    const t3 = lines[L2].trim();
+    if (t3 !== `${alt}:` && t3 !== `${keyToken(alt)}:`) return false;
+    const body = bodyUnder(lines, L2, region.hi, region.indent);
+    for (let i2 = body.lo; i2 < body.hi; i2++) if (isContentLine(lines[i2])) return false;
+    lines.splice(L2, Math.max(1, body.hi - L2));
+    return true;
+  }
+  return false;
 }
 var isBookmarkLine = (line) => line.trim().startsWith("&");
 function appendBookmarkAt(lines, region, tokens) {
@@ -68148,10 +68309,13 @@ function pruneEmptyYo(text, within) {
   const lines = text.replace(/\n$/, "").split("\n");
   const region = findBody(lines, within);
   if (!region) return text;
-  return pruneEmptyKeyAt(lines, region, YO_KEY) ? lines.join("\n") + "\n" : text;
+  return pruneEmptyKeyAt(lines, region, overlayKeyAlts) ? lines.join("\n") + "\n" : text;
 }
 function upsertThumbnail(text, within, resKey, render) {
-  return upsertMapEntry(text, within, [THUMBNAILS_KEY], resKey, render);
+  const probe = text.replace(/\n$/, "").split("\n");
+  const legacy = findBody(probe, [...within, LEGACY_THUMBNAILS_KEY]) !== null;
+  const mapPath = legacy ? [LEGACY_THUMBNAILS_KEY] : [overlayKeyAlts, THUMBNAILS_SUBKEY];
+  return upsertMapEntry(text, within, mapPath, resKey, render);
 }
 function annotationsRemainAt(lines, region) {
   const seq = seqItemLines(lines, region, ANNOTATIONS_KEY);
@@ -68168,10 +68332,10 @@ function pruneEmptyKeys(lines, within) {
   for (let d2 = within.length; d2 > 0; d2--) {
     const parent = findBody(lines, within.slice(0, d2 - 1));
     if (!parent) break;
-    const L2 = findKeyLine(lines, parent.lo, parent.hi, parent.indent, within[d2 - 1]);
+    const L2 = findStepLine(lines, parent.lo, parent.hi, parent.indent, within[d2 - 1]);
     if (L2 < 0) break;
     const t3 = lines[L2].trim();
-    if (t3 !== `${within[d2 - 1]}:` && t3 !== `${keyToken(within[d2 - 1])}:`) break;
+    if (!stepAlts(within[d2 - 1]).some((alt) => t3 === `${alt}:` || t3 === `${keyToken(alt)}:`)) break;
     const body = bodyUnder(lines, L2, parent.hi, parent.indent);
     let empty = true;
     for (let i2 = body.lo; i2 < body.hi; i2++) if (isContentLine(lines[i2])) {
@@ -68196,7 +68360,7 @@ function findMapping(lines, region, mapPath) {
   let r2 = region;
   let line = -1;
   for (let k = 0; k < mapPath.length; ) {
-    const L2 = findKeyLine(lines, r2.lo, r2.hi, r2.indent, mapPath[k]);
+    const L2 = findStepLine(lines, r2.lo, r2.hi, r2.indent, mapPath[k]);
     if (L2 < 0) return null;
     const consumed = flatRun(lines[L2], mapPath, k);
     line = L2;
@@ -68725,7 +68889,7 @@ function pruneClone(node, segs, frag, depthLeft, side, deps) {
   const out = [];
   let renderedIdx = 0;
   (node.entries ?? []).forEach((e3, srcIdx) => {
-    if (hiddenNode(e3.value)) return;
+    if (hiddenNode(e3.value) && (typeof e3.key !== "string" || !isHiddenEntryKey(e3.key) || deps.memberExists([...segs, e3.key]))) return;
     const idx = renderedIdx;
     if (e3.edge !== "back") renderedIdx++;
     if (isPointer(e3.value)) {
@@ -69151,8 +69315,9 @@ function enforce(v, mode) {
   if (mode === "off") return [];
   if (mode === "report") return v.diagnostics;
   if (mode === "throw") {
-    if (v.diagnostics.length) throw new ValidationError(v.allowed ? v.diagnostics[0].message : v.reason, v.diagnostics);
-    return [];
+    const fatal = v.diagnostics.filter((d2) => d2.severity !== "info");
+    if (fatal.length) throw new ValidationError(v.allowed ? fatal[0].message : v.reason, v.diagnostics);
+    return v.diagnostics;
   }
   if (!v.allowed) throw new ValidationError(v.reason, v.diagnostics);
   return v.diagnostics;
@@ -69531,13 +69696,16 @@ function createHandlers(dataRoot, opts = {}) {
     cachedDoc = doc;
     return diff2;
   };
+  let filePatched = false;
   const doReindexFile = async (absFile) => {
+    filePatched = false;
     if (cachedDoc) {
       const rel2 = path11.relative(dataRoot, absFile).split(path11.sep).join("/");
       try {
         const res = await reindexPathAsync(store0, dataRoot, cachedDoc, rel2, walkOpts);
         if (res) {
           cachedDoc = res.doc;
+          filePatched = true;
           return res.diff;
         }
       } catch {
@@ -69582,35 +69750,46 @@ function createHandlers(dataRoot, opts = {}) {
     }
   };
   let reconcilePending = null;
+  const settle = (task, label, produce) => enqueue(async () => {
+    const h = tasks.start(task);
+    try {
+      const diff2 = await produce();
+      if (diff2.moved.length > 0 && !readOnly) {
+        const r2 = relinkMoved(dataRoot, diff2.moved, { ignore: ignore2 });
+        if (r2.editedFiles.length > 0) {
+          const follow = reindex(store0, dataRoot, walkOpts);
+          diff2.changed = [.../* @__PURE__ */ new Set([...diff2.changed, ...follow.changed])];
+          cachedDoc = null;
+        }
+      }
+      h.done();
+      log(`${label()}: +${diff2.added.length} ~${diff2.changed.length} \u2212${diff2.removed.length} \u2192${diff2.moved.length}`);
+      if (cachedDoc) logDeadLinks(deadLinkDiagnostics(cachedDoc, store0, dataRoot), log);
+      broadcast(diff2);
+      scheduleHasher();
+      return diff2;
+    } catch (e3) {
+      h.fail(e3);
+      throw e3;
+    }
+  });
   const reconcile2 = () => {
     if (reconcilePending) return reconcilePending;
-    const p2 = enqueue(async () => {
+    const p2 = settle("reconciling", () => "reconcile", () => {
       reconcilePending = null;
-      const h = tasks.start("reconciling");
-      try {
-        const diff2 = await doReindex();
-        if (diff2.moved.length > 0 && !readOnly) {
-          const r2 = relinkMoved(dataRoot, diff2.moved, { ignore: ignore2 });
-          if (r2.editedFiles.length > 0) {
-            const follow = reindex(store0, dataRoot, walkOpts);
-            diff2.changed = [.../* @__PURE__ */ new Set([...diff2.changed, ...follow.changed])];
-            cachedDoc = null;
-          }
-        }
-        h.done();
-        log(`reconcile: +${diff2.added.length} ~${diff2.changed.length} \u2212${diff2.removed.length} \u2192${diff2.moved.length}`);
-        if (cachedDoc) logDeadLinks(deadLinkDiagnostics(cachedDoc, store0, dataRoot), log);
-        broadcast(diff2);
-        scheduleHasher();
-        return diff2;
-      } catch (e3) {
-        h.fail(e3);
-        throw e3;
-      }
+      return doReindex();
     });
     reconcilePending = p2;
     return p2;
   };
+  const patchOne = (rel2) => settle(`patching ${rel2}`, () => filePatched ? "patch" : "patch \u2192 full walk", () => doReindexFile(path11.join(dataRoot, ...rel2.split("/"))));
+  const patchable = (batch) => {
+    if (batch.length !== 1) return null;
+    const rel2 = batch[0];
+    if (!store0.file(rel2)) return null;
+    const st = fs10.statSync(path11.join(dataRoot, ...rel2.split("/")), { throwIfNoEntry: false });
+    return st?.isFile() ? rel2 : null;
+  };
   const spuriousEvent = (rel2) => {
     const rec = store0.file(rel2);
     if (!rec) return false;
@@ -69627,7 +69806,8 @@ function createHandlers(dataRoot, opts = {}) {
       return;
     }
     log(`watch: ${external.length} change(s) \u2014 ${external.slice(0, 5).join(", ")}${external.length > 5 ? ", \u2026" : ""}`);
-    reconcile2().catch(() => {
+    const one = reconcilePending ? null : patchable(external);
+    (one ? patchOne(one) : reconcile2()).catch(() => {
     });
   }, { ignore: ignore2 }) : null;
   const handler = (req, res, url) => {
@@ -69658,7 +69838,7 @@ function createHandlers(dataRoot, opts = {}) {
         try {
           const v = validateTree(scanTree(dataRoot, ignore2));
           const doc = cachedDoc ?? walkTree(dataRoot, walkOpts).doc;
-          sendJson(res, 200, { allowed: v.allowed, diagnostics: [...v.diagnostics, ...deadLinkDiagnostics(doc, s2, dataRoot), ...doubledFragmentDiagnostics(doc)] });
+          sendJson(res, 200, { allowed: v.allowed, diagnostics: [...v.diagnostics, ...deadLinkDiagnostics(doc, s2, dataRoot), ...doubledFragmentDiagnostics(doc), ...legacyOverlaySpellingDiagnostics(doc)] });
         } catch (e3) {
           sendJson(res, 500, { error: String(e3.message || e3) });
         }
@@ -69684,7 +69864,8 @@ function createHandlers(dataRoot, opts = {}) {
         try {
           const paths = evalQuery(s2, q, at);
           const projectScoped = /^\s*::/.test(q);
-          const dropHidden = (p3) => projectScoped ? queryHidden(s2, p3) : inHiddenSubtree(s2, p3);
+          const explicit = isPointerShapedQuery(q);
+          const dropHidden = (p3) => !explicit && (projectScoped ? queryHidden(s2, p3) : inHiddenSubtree(s2, p3));
           if (shape === "tree") {
             const results = paths.filter((p3) => !dropHidden(p3)).map((p3) => {
               const segs2 = storePathToSegs(p3);
@@ -69945,7 +70126,10 @@ function createHandlers(dataRoot, opts = {}) {
             ...row2.type === "blob" ? { size: row2.size } : {},
             // a DEGRADED node (walk.ts: its source failed to parse) declares it, so the client
             // shows the failure instead of a merely-empty page and keeps its editor shut
-            ...row2.meta?.parseError ? { parseError: row2.meta.parseError } : {}
+            ...row2.meta?.parseError ? { parseError: row2.meta.parseError } : {},
+            // THE OVERLAY LAW: engine-managed `.yo` subtree entries browsed directly are DUMB —
+            // the client forces the generic data view and greys the editor (settings.yo excepted)
+            ...inYoSubtree(s2, segs2) && !isSettingsPath(segs2) ? { special: "overlay" } : {}
           };
           const text = buildEnvelope(
             { segs: segs2, subtree, docDepth, header, relations: buildRelations(dataRoot, s2, segs2) },
@@ -69981,6 +70165,7 @@ function createHandlers(dataRoot, opts = {}) {
               const segs2 = strToSegs(p3);
               if (segs2.length === 0) throw new Error(`mv: ${what} must name a file or directory`);
               if (segs2.some((g) => typeof g === "number")) throw new Error(`mv: ${what} must be a file/directory path (no positions)`);
+              if (inYoSubtree(s2, segs2)) throw new Error(`mv: ${what} is inside the engine-managed .yo subtree`);
               return segs2.join("/");
             };
             const report = mv(dataRoot, rel2(from ?? "", "from"), rel2(to2 ?? "", "to"), { ignore: ignore2 });
@@ -69997,6 +70182,7 @@ function createHandlers(dataRoot, opts = {}) {
             const { path: reqPath, key: newKey } = data;
             const segs2 = canonSegs(s2, strToSegs(reqPath ?? ""), false);
             if (segs2.length === 0 || typeof segs2[segs2.length - 1] !== "string") throw new Error("rekey needs a keyed node path");
+            if (inYoSubtree(s2, segs2) && !isSettingsPath(segs2)) throw new Error("entries under .yo are engine-managed and read-only");
             if (typeof newKey !== "string" || newKey === "" || newKey !== newKey.trim()) throw new Error("a key must be a non-empty, un-padded string");
             const parentSegs = segs2.slice(0, -1);
             const oldKey = String(segs2[segs2.length - 1]);
@@ -70247,11 +70433,21 @@ var inHiddenSubtree = (s2, p2) => {
   return false;
 };
 var visibleHasChildren = (s2, p2) => s2.children(p2).some((c3) => !isHidden(s2, c3.to));
+var inYoSubtree = (s2, segs) => {
+  for (let i2 = 1; i2 <= segs.length; i2++) {
+    const seg = segs[i2 - 1];
+    if (seg === OVERLAY_KEY || seg === LEGACY_OVERLAY_KEY || seg === LEGACY_THUMBNAILS_KEY) {
+      if (isHidden(s2, storePath(segs.slice(0, i2)))) return true;
+    }
+  }
+  return false;
+};
+var isSettingsPath = (segs) => segs.some((g, i2) => g === OVERLAY_KEY && segs[i2 + 1] === "settings.yo");
 var queryHidden = (s2, p2) => {
   if (isHidden(s2, p2)) return true;
   for (let segs = storePathToSegs(p2); segs.length; segs = segs.slice(0, -1)) {
     const sp = storePath(segs);
-    if (isHidden(s2, sp) && String(segs[segs.length - 1]).startsWith(".")) return true;
+    if (isHidden(s2, sp) && isHiddenEntryKey(segs[segs.length - 1])) return true;
   }
   return false;
 };
@@ -70321,6 +70517,21 @@ function projectSchema(dataRoot, s2, segs, depth, top) {
   if (t3) schema.title = t3;
   return schema;
 }
+var STUB_VALUE_MAX = 64 << 10;
+function isWholeFileBody(row, v) {
+  const span = row.meta?.span;
+  return !!span && span.start === 0 && span.end === v.length;
+}
+function stubValue(info, row) {
+  const v = row.value;
+  if (typeof v === "string" && v.length > STUB_VALUE_MAX && isWholeFileBody(row, v)) {
+    info.value = v.slice(0, STUB_VALUE_MAX);
+    info.valueTruncated = true;
+    info.valueLength = v.length;
+    return;
+  }
+  info.value = wireScalar(v);
+}
 function linkMarker(dataRoot, s2, segs) {
   const p2 = storePath(segs);
   const row = s2.node(p2);
@@ -70332,10 +70543,10 @@ function linkMarker(dataRoot, s2, segs) {
   const title = titleOf(s2, p2);
   if (title) info.title = title;
   if (k === "binary") info.size = row.size;
-  else if (k === "scalar") info.value = wireScalar(row.value);
+  else if (k === "scalar") stubValue(info, row);
   else if (k === "omni" || k === "mix") {
     info.count = ownedEntries(s2, p2).length;
-    if (k === "omni") info.value = wireScalar(row.value);
+    if (k === "omni") stubValue(info, row);
   } else {
     info.count = ownedEntries(s2, p2).filter((e3) => !(e3.kind === "contain" && isHidden(s2, e3.to))).length;
   }
@@ -70460,11 +70671,17 @@ function firstChunkText(s2, p2) {
 }
 var ONTO_FORMAT = "x-yamlover-onto";
 var FRAGMENT_FORMAT = "x-yamlover-fragment";
-var YO_KEY2 = "yo";
-var FRAGS_SUBKEY = "fragments";
+var FRAGS_SUBKEY = FRAGMENTS_SUBKEY;
 var CROP_SUBDIR = "fragments";
 var THUMB_SUBDIR = "thumbnails";
 var childPath = (parent, key) => (parent === ":" ? "" : parent) + ":" + key;
+var overlaySubPath = (s2, hostStore, sub) => {
+  for (const k of overlayKeyAlts) {
+    const p2 = childPath(childPath(hostStore, k), sub);
+    if (s2.node(p2)) return p2;
+  }
+  return null;
+};
 function projectTag(s2, tagStore) {
   if (!s2.node(tagStore)) return null;
   const segs = storePathToSegs(tagStore);
@@ -70487,8 +70704,8 @@ function readAnnotations(s2, hostStore) {
   return out;
 }
 function readFragments(s2, hostStore) {
-  const frags = childPath(childPath(hostStore, YO_KEY2), FRAGS_SUBKEY);
-  if (!s2.node(frags)) return [];
+  const frags = overlaySubPath(s2, hostStore, FRAGS_SUBKEY);
+  if (!frags) return [];
   const out = [];
   for (const fc of s2.children(frags)) {
     if (!fc.label) continue;
@@ -70541,6 +70758,9 @@ function annotationsFor(dataRoot, s2, segs) {
           node: nodeClient,
           selector: f2.selector,
           fragmentSlug: f2.slug,
+          // the fragment node's REAL client path — the delete target must carry the overlay
+          // spelling the file actually uses (`.yo` or the legacy `yo`), never re-mint it
+          fragmentPath: segsToStr(storePathToSegs(f2.node)),
           ...f2.description ? { description: f2.description } : {},
           ...f2.imageUrl ? { imageUrl: f2.imageUrl } : {}
         });
@@ -70579,7 +70799,7 @@ function pointerRaw(clientPath) {
   return "::" + out;
 }
 var LANES_SUBKEY = "lanes";
-var BOARD_CONFIG_KEYS = /* @__PURE__ */ new Set(["workflow", "lanes", "yamlover", "ontos", YO_KEY2]);
+var BOARD_CONFIG_KEYS = /* @__PURE__ */ new Set(["workflow", "lanes", "yamlover", "ontos", ...overlayKeyAlts]);
 var TAGISH_FORMATS = /* @__PURE__ */ new Set([ONTO_FORMAT, "x-yamlover-workflow", "x-yamlover-board"]);
 function writeBoardStructure(src, structure) {
   let lines = src.replace(/\n+$/, "").split("\n");
@@ -70601,15 +70821,15 @@ function writeBoardStructure(src, structure) {
     }
     return out;
   };
-  replaceSeqEntryAt(lines, reachBody(lines, [YO_KEY2]), LANES_SUBKEY, render);
+  replaceSeqEntryAt(lines, reachBody(lines, [overlayKeyAlts]), LANES_SUBKEY, render);
   return lines.join("\n") + "\n";
 }
 function membershipPathsOf(s2, store) {
   return s2.relationships(store).out.filter((e3) => e3.kind === "back" && e3.label == null).map((e3) => segsToStr(storePathToSegs(e3.to)));
 }
 function readBoardStructure(s2, boardStore) {
-  const lanesStore = childPath(childPath(boardStore, YO_KEY2), LANES_SUBKEY);
-  if (!s2.node(lanesStore)) return null;
+  const lanesStore = overlaySubPath(s2, boardStore, LANES_SUBKEY);
+  if (!lanesStore) return null;
   return s2.children(lanesStore).map(
     (lane) => s2.children(lane.to).map((comp) => ({
       tags: membershipPathsOf(s2, comp.to),
@@ -70761,7 +70981,7 @@ function fragmentBlockLines(slug, selector, imagePtr, indent) {
   lines.push(`${pad}  created: ${(/* @__PURE__ */ new Date()).toISOString()}`);
   return lines;
 }
-var isFragmentSegs = (segs) => segs.length >= 3 && segs[segs.length - 3] === YO_KEY2 && segs[segs.length - 2] === FRAGS_SUBKEY;
+var isFragmentSegs2 = (segs) => isFragmentSegs(segs);
 var labelToken = (v) => /[:\[\]()&'"\n]|^\s|\s$/.test(v) ? "'" + v.replace(/'/g, "''") + "'" : v;
 function locateExact(text, sel) {
   const needle = String(sel.exact ?? "");
@@ -70842,7 +71062,7 @@ function embedAnnotation(dataRoot, s2, mode, a2) {
     const made = embedFragment(dataRoot, s2, mode, { target: a2.target, selector: sel });
     return embedAnnotation(dataRoot, s2, mode, { target: made.fragmentPath, tag: a2.tag });
   }
-  if (Object.keys(params).length && !isFragmentSegs(segs)) {
+  if (Object.keys(params).length && !isFragmentSegs2(segs)) {
     throw new Error("annotation parameters live on a fragment (docs/annotations/applications)");
   }
   const tokens = [`&${pointerRaw(a2.tag)}:-`, ...Object.entries(params).map(([k, v]) => `${keyToken(k)}: ${yScalar(v)}`)];
@@ -70884,7 +71104,7 @@ function ownDocFile(dataRoot, segs) {
 function embedFragment(dataRoot, s2, mode, f2) {
   const segs = strToSegs(f2.target || ":");
   const chosen = typeof f2.slug === "string" ? f2.slug.trim() : "";
-  if (chosen !== "" && s2.node(storePath([...segs, YO_KEY2, FRAGS_SUBKEY, chosen]))) {
+  if (chosen !== "" && overlayKeyAlts.some((yo) => s2.node(storePath([...segs, yo, FRAGS_SUBKEY, chosen])))) {
     throw new Error(`a fragment \`${chosen}\` already exists on this node`);
   }
   const slug = chosen !== "" ? chosen : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
@@ -70900,9 +71120,10 @@ function embedFragment(dataRoot, s2, mode, f2) {
       /*ensureOmni*/
       true
     );
-    upsertMapEntryAt(lines, reachBodyAt(lines, region, [YO_KEY2, FRAGS_SUBKEY]), slug, (indent) => fragmentBlockLines(slug, f2.selector, null, indent));
+    const yoKey2 = presentStepAlt(lines, region, overlayKeyAlts);
+    upsertMapEntryAt(lines, reachBodyAt(lines, region, [overlayKeyAlts, FRAGS_SUBKEY]), slug, (indent) => fragmentBlockLines(slug, f2.selector, null, indent));
     writeBody(dataRoot, s2, bodyFile2, lines.join("\n") + "\n");
-    return { slug, fragmentPath: segsToStr([...segs, YO_KEY2, FRAGS_SUBKEY, slug]) };
+    return { slug, fragmentPath: segsToStr([...segs, yoKey2, FRAGS_SUBKEY, slug]) };
   }
   const { bodyFile, within } = hostFor(dataRoot, s2, segs);
   let imagePtr = null;
@@ -70918,8 +71139,9 @@ function embedFragment(dataRoot, s2, mode, f2) {
   }
   mkdirInside(dataRoot, path11.dirname(bodyFile), { recursive: true });
   const src = fs10.existsSync(bodyFile) ? fs10.readFileSync(bodyFile, "utf8") : "";
+  const yoKey = overlaySpellingAt(src, within);
   writeBody(dataRoot, s2, bodyFile, upsertFragment(src, within, slug, (indent) => fragmentBlockLines(slug, f2.selector, imagePtr, indent)));
-  return { slug, fragmentPath: segsToStr([...segs, YO_KEY2, FRAGS_SUBKEY, slug]) };
+  return { slug, fragmentPath: segsToStr([...segs, yoKey, FRAGS_SUBKEY, slug]) };
 }
 var thumbResKey = (w, h) => `[${w}, ${h}]`;
 var thumbName = (hash, w, h) => `${hash.replace(/:/g, "-")}-${w}x${h}.jpg`;
@@ -70984,9 +71206,9 @@ function unembedAnnotation(dataRoot, s2, target, tag, sel) {
       false
     ), keys);
     removeBookmarkAt(lines, fragRegion, pred);
-    if (isFragmentSegs(keys) && !bookmarksRemainAt(lines, fragRegion())) {
+    if (isFragmentSegs2(keys) && !bookmarksRemainAt(lines, fragRegion())) {
       removeMapEntryAt(lines, chunkFieldRegion(lines, indices, false), keys.slice(0, -1), keys[keys.length - 1]);
-      pruneEmptyKeyAt(lines, chunkFieldRegion(lines, indices, false), YO_KEY2);
+      pruneEmptyKeyAt(lines, chunkFieldRegion(lines, indices, false), overlayKeyAlts);
       collapseChunkOmni(lines, indices);
     } else if (keys.length === 0 && !bookmarksRemainAt(lines, fragRegion())) {
       collapseChunkOmni(lines, indices);
@@ -71007,8 +71229,8 @@ function unembedAnnotation(dataRoot, s2, target, tag, sel) {
   if (!fs10.existsSync(bodyFile)) return bodyFile;
   let src = removeBookmark(fs10.readFileSync(bodyFile, "utf8"), within, pred);
   const overlay2 = overlaidDir(bodyFile) !== null;
-  if (isFragmentSegs(within) && !bookmarksRemain(src, within)) {
-    src = removeMapEntry(src, within.slice(0, -3), [YO_KEY2, FRAGS_SUBKEY], within[within.length - 1]);
+  if (isFragmentSegs2(within) && !bookmarksRemain(src, within)) {
+    src = removeMapEntry(src, within.slice(0, -3), within.slice(-3, -1), within[within.length - 1]);
     src = pruneEmptyYo(src, within.slice(0, -3));
     src = pruneEmptyAnnotations(src, within.slice(0, -3), overlay2);
   } else {
@@ -72360,6 +72582,9 @@ function applyEdits2(dataRoot, s2, edits) {
   for (const e3 of edits) {
     const editSegs = applyRemap(canonSegs(s2, strToSegs(e3.path ?? ""), true));
     const op = String(e3.op ?? "");
+    if (inYoSubtree(s2, editSegs) && !isSettingsPath(editSegs)) {
+      throw new Error("entries under .yo are engine-managed and read-only (settings.yo excepted)");
+    }
     if (op === "insert" && (e3.concrete === "file/yamlover" || isOverlayDirConcrete(e3.concrete)) && isPlainDir(dataRoot, s2, editSegs)) {
       const dir = path11.resolve(dataRoot, ...editSegs.map(String));
       const src = [...metaTag(e3.meta, void 0, false) ? [metaTag(e3.meta, void 0, false)] : [], String(e3.yamlover ?? ""), ""].join("\n");
@@ -72718,6 +72943,7 @@ function envelopeDeps(s2, dataRoot, membersOnDisk) {
 function previewEnvelope(source) {
   const doc = parseYamlover(source, "<preview>");
   doc.root.meta = { ...doc.root.meta, documentRoot: true, ...doc.head?.length ? { head: doc.head } : {} };
+  stampHiddenKeys(doc.root);
   const s2 = new Store(":memory:");
   try {
     s2.indexDocument(doc);
@@ -72868,7 +73094,19 @@ var EXT_CT = {
   ".html": "text/html",
   ".md": "text/markdown",
   ".csv": "text/csv",
-  ".epub": "application/epub+zip"
+  ".epub": "application/epub+zip",
+  ".js": "text/javascript",
+  ".mjs": "text/javascript",
+  ".cjs": "text/javascript",
+  ".ts": "text/typescript",
+  ".tsx": "text/typescript",
+  ".jsx": "text/javascript",
+  ".css": "text/css",
+  ".py": "text/x-python",
+  ".sh": "text/x-shellscript",
+  ".sql": "text/x-sql",
+  ".xml": "text/xml",
+  ".jsonl": "application/x-ndjson"
 };
 function formatFromExt(file) {
   return EXT_CT[path11.extname(file).toLowerCase()] ?? null;
@@ -72880,7 +73118,15 @@ var UTF8_CT = /* @__PURE__ */ new Set([
   "text/asciidoc",
   "text/x-plantuml",
   "text/csv",
-  "text/tab-separated-values"
+  "text/tab-separated-values",
+  "text/javascript",
+  "text/typescript",
+  "text/css",
+  "text/x-python",
+  "text/x-shellscript",
+  "text/x-sql",
+  "text/xml",
+  "application/x-ndjson"
 ]);
 function blobContentType(format) {
   if (format == null) return "application/octet-stream";