yamlover 0.3.23 → 0.3.24

package/dist/server.js

@@ -62331,6 +62331,7 @@ var require_ignore = __commonJS({
 // src/server/engine-api.ts
 import path10 from "node:path";
 import fs10 from "node:fs";
+import os from "node:os";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // ../parser/ts/src/ir.ts
@@ -62535,7 +62536,7 @@ function pathOf(chain) {
 
 // ../engine/ts/src/store.ts
 import { DatabaseSync } from "node:sqlite";
-var SCHEMA_VERSION = 5;
+var SCHEMA_VERSION = 6;
 var SCHEMA = `
 CREATE TABLE IF NOT EXISTS node (
   path         TEXT PRIMARY KEY,
@@ -62565,8 +62566,14 @@ CREATE TABLE IF NOT EXISTS file (
 CREATE TABLE IF NOT EXISTS dangling (
   from_path TEXT NOT NULL,               -- the entry holding the pointer
   raw       TEXT NOT NULL,               -- the pointer text as authored
-  reason    TEXT NOT NULL                -- why it did not resolve
+  reason    TEXT NOT NULL,               -- why it did not resolve (externals: the authority)
+  holder    TEXT NOT NULL,               -- the mapping that holds the entry
+  label     TEXT,                        -- the entry's key; null for keyless/positional
+  pos       INTEGER,                     -- the entry's index in the holder (source order)
+  edge      TEXT NOT NULL,               -- ref | back (as authored)
+  external  INTEGER NOT NULL DEFAULT 0   -- 1 = an external-authority link, not an error
 );
+CREATE INDEX IF NOT EXISTS dangling_holder ON dangling (holder);
 `;
 function encodeScalarValue(v) {
   if (typeof v === "number" && !Number.isFinite(v)) return JSON.stringify({ "@nonfinite": String(v) });
@@ -62631,10 +62638,10 @@ var Store = class {
         insNode.run(path11, node.kind, format, value, hash, size, isArray ? 1 : 0, meta);
         if (parent !== null) insEdge.run(parent, path11, label, "contain", pos);
       });
-      const insDangling = this.db.prepare("INSERT INTO dangling (from_path, raw, reason) VALUES (?, ?, ?)");
+      const insDangling = this.db.prepare(INSERT_DANGLING);
       for (const r2 of resolveDocument(doc)) {
         if (r2.target.kind === "node") insEdge.run(r2.holder, r2.target.path, r2.label, r2.edge, r2.pos);
-        else if (r2.target.kind === "unresolved") insDangling.run(r2.from, r2.raw, r2.target.reason);
+        else insDanglingRef(insDangling, r2);
       }
       if (files) {
         const insFile = this.db.prepare("INSERT OR REPLACE INTO file (path, hash, size, mtime_ms) VALUES (?, ?, ?, ?)");
@@ -62675,7 +62682,7 @@ var Store = class {
     const insEdge = this.db.prepare(
       `INSERT INTO edge (from_path, to_path, label, kind, pos) VALUES (?, ?, ?, ?, ?)`
     );
-    const insDangling = this.db.prepare("INSERT INTO dangling (from_path, raw, reason) VALUES (?, ?, ?)");
+    const insDangling = this.db.prepare(INSERT_DANGLING);
     const insFile = this.db.prepare("INSERT OR REPLACE INTO file (path, hash, size, mtime_ms) VALUES (?, ?, ?, ?)");
     this.db.exec("BEGIN");
     try {
@@ -62684,7 +62691,7 @@ var Store = class {
       };
       delUnder("path", "node");
       delUnder("from_path", "edge");
-      delUnder("from_path", "dangling");
+      delUnder("holder", "dangling");
       if (relPrefix) this.db.prepare("DELETE FROM file WHERE substr(path,1,?) = ?").run(relPrefix.length, relPrefix);
       walkNodes(doc.root, ":", (p2, node, parent, label, pos) => {
         if (!underP(p2)) return;
@@ -62701,7 +62708,7 @@ var Store = class {
       for (const r2 of edges) {
         if (!underP(r2.holder)) continue;
         if (r2.target.kind === "node") insEdge.run(r2.holder, r2.target.path, r2.label, r2.edge, r2.pos);
-        else if (r2.target.kind === "unresolved") insDangling.run(r2.from, r2.raw, r2.target.reason);
+        else insDanglingRef(insDangling, r2);
       }
       for (const f2 of files) insFile.run(f2.path, f2.hash, f2.size, f2.mtimeMs);
       this.db.exec("COMMIT");
@@ -62835,14 +62842,27 @@ var Store = class {
       throw e3;
     }
   }
-  /** The pointers that failed to resolve at index time (ENGINE.md: reported, never dropped). */
+  /** The pointers that failed to resolve at index time (ENGINE.md: reported, never dropped).
+   *  External-authority links are not errors, so they are excluded here. */
   dangling() {
-    return this.db.prepare("SELECT * FROM dangling").all().map((r2) => ({
+    return this.db.prepare("SELECT * FROM dangling WHERE external = 0").all().map((r2) => ({
       from: r2.from_path,
       raw: r2.raw,
       reason: r2.reason
     }));
   }
+  /** A node's pointer ENTRIES with no local target — unresolved (dangling) plus external-
+   *  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) => ({
+      label: r2.label ?? null,
+      pos: r2.pos ?? null,
+      raw: r2.raw,
+      edge: r2.edge,
+      external: r2.external === 1
+    }));
+  }
   /** A node's attributes (null if no such path). */
   node(path11) {
     const row = this.db.prepare("SELECT * FROM node WHERE path = ?").get(path11);
@@ -62905,6 +62925,13 @@ var Store = class {
     return { out, in: [...inc, ...derivedIn] };
   }
 };
+var INSERT_DANGLING = "INSERT INTO dangling (from_path, raw, reason, holder, label, pos, edge, external) VALUES (?, ?, ?, ?, ?, ?, ?, ?)";
+function insDanglingRef(stmt, r2) {
+  if (r2.target.kind === "node") return;
+  const ext = r2.target.kind === "external";
+  const reason = r2.target.kind === "external" ? r2.target.authority : r2.target.reason;
+  stmt.run(r2.from, r2.raw, reason, r2.anchor ? "" : r2.holder, r2.label, r2.pos, r2.edge, ext ? 1 : 0);
+}
 function walkNodes(node, path11, visit2, parent = null, label = null, pos = null) {
   visit2(path11, node, parent, label, pos);
   if (!node.entries) return;
@@ -62915,6 +62942,7 @@ function walkNodes(node, path11, visit2, parent = null, label = null, pos = null
   });
 }
 function formatFromMeta(node) {
+  if (node.meta?.derivedFormat) return node.meta.derivedFormat;
   const s2 = node.meta?.schema;
   if (!s2) return null;
   if (isPointer(s2)) {
@@ -64916,7 +64944,7 @@ function applyMeta(node, meta) {
     if (!m) continue;
     if (m.uniqueItems) e3.value = { ...e3.value, meta: { ...e3.value.meta, set: true } };
     if (e3.value.kind === "blob") continue;
-    if (m.format && !e3.value.meta?.schema) e3.value = { ...e3.value, meta: { ...e3.value.meta, schema: inlineFormat(m.format) } };
+    if (m.format && !e3.value.meta?.schema) e3.value = { ...e3.value, meta: { ...e3.value.meta, derivedFormat: m.format } };
   }
   return node;
 }
@@ -64935,7 +64963,7 @@ function blob(abs, format, ctx) {
 }
 function textScalar(abs, format, ctx) {
   const text = readTracked(ctx, abs).toString("utf8");
-  return { kind: "scalar", value: text, raw: text, meta: { schema: inlineFormat(format) } };
+  return { kind: "scalar", value: text, raw: text, meta: { derivedFormat: format } };
 }
 function parsedScalar(abs, ext, ctx) {
   const lang = ext === ".json" || ext === ".json5" || ext === ".json5p" ? "json5p" : ext === ".yaml" || ext === ".yml" ? "yaml" : "yamlover";
@@ -64983,7 +65011,7 @@ function applySchemas(root, defsRoot, builtinDefs) {
     return v && !isPointer(v) && v.kind === "scalar" && v.value != null ? String(v.value) : null;
   };
   const hasFormat = (inst) => {
-    if (inst.kind === "blob") return true;
+    if (inst.kind === "blob" || inst.meta?.derivedFormat) return true;
     const s2 = inst.meta?.schema;
     return !!s2 && !isPointer(s2) && s2.kind === "mapping" && !!field(s2, "format");
   };
@@ -65019,7 +65047,7 @@ function applySchemas(root, defsRoot, builtinDefs) {
     const stype = str(s2, "type");
     const named = name && (stype === "object" || stype === "variant" || stype === "mixed" || !!field(s2, "allOf"));
     const fmt = str(s2, "format") ?? (named ? `x-yamlover-${name}` : null);
-    if (fmt && !hasFormat(inst)) inst.meta = { ...inst.meta, schema: inlineFormat(fmt) };
+    if (fmt && !hasFormat(inst)) inst.meta = { ...inst.meta, derivedFormat: fmt };
     if (stype === "object" || stype === "variant" || stype === "mixed" || stype === "array" || field(s2, "items")) {
       const props = field(s2, "properties");
       const addl = field(s2, "additionalProperties");
@@ -65044,9 +65072,6 @@ function applySchemas(root, defsRoot, builtinDefs) {
   };
   walk(root);
 }
-function inlineFormat(format) {
-  return { kind: "mapping", entries: [{ key: "format", edge: "contain", value: { kind: "scalar", value: format, raw: format } }], array: false };
-}
 function applyBody(dir, node, ctx) {
   const file = path2.join(dir, YAMLOVER_DIR, "body.yamlover");
   if (!fs2.existsSync(file)) return node;
@@ -65189,11 +65214,21 @@ var DOC_FORMATS = {
 import * as path3 from "node:path";
 
 // ../parser/ts/src/serialize-common.ts
+var LossyError = class extends Error {
+};
 function anchorBody(a2) {
   return renderPointer(a2.path) + (a2.ordinal ? "[]" : "");
 }
 
 // ../parser/ts/src/serialize-yamlover.ts
+function schemaText(v) {
+  const text = isPointer(v) ? `*${renderPointer(v)}` : schemaNodeText(v);
+  if (/[>\n]/.test(text)) throw new LossyError(`a !!<\u2026> schema tag cannot contain ">" or a newline: ${text}`);
+  return text;
+}
+function schemaTagToken(v) {
+  return `!!<${schemaText(v)}>`;
+}
 function pointerToken(raw) {
   if (raw !== raw.trim()) return `*'${raw.replace(/'/g, "''")}'`;
   return "*" + raw;
@@ -65222,6 +65257,73 @@ function hasUnquotedSpace(s2) {
   }
   return false;
 }
+function dq(s2) {
+  return JSON.stringify(s2);
+}
+function keyText(key) {
+  const needsQuote = key === "" || key !== key.trim() || /[\u0000-\u001f\u007f]/.test(key) || key.includes(": ") || // splitKV would split at the inner colon
+  key === "-" || key.startsWith("- ") || /^['"]/.test(key) || key.includes("\\");
+  if (needsQuote) return dq(key);
+  return key.replace(/[/[\]*&#~?!()<>=|]/g, (c3) => "\\" + c3);
+}
+function schemaNodeText(n2) {
+  if (n2.kind === "mapping") {
+    const ents = n2.entries;
+    const keyed = ents.filter((e3) => e3.key !== null);
+    if (keyed.length === ents.length && ents.length === 1 && ents[0].edge !== "back") {
+      const e3 = ents[0];
+      const v = isPointer(e3.value) ? flowPtr(e3.value) : flowText(e3.value);
+      return `${keyText(e3.key)}: ${v}`;
+    }
+    if (keyed.length > 0) {
+      throw new LossyError("an inline !!<\u2026> schema holds at most one top-level key");
+    }
+  }
+  return flowText(n2);
+}
+function flowText(n2) {
+  if (n2.kind === "blob") throw new LossyError("a blob has no flow form");
+  if (n2.meta?.schema !== void 0 || n2.meta?.set === true) {
+    throw new LossyError("tags inside an inline !!<\u2026> schema are not serializable");
+  }
+  const ents = n2.entries ?? [];
+  if (n2.kind === "scalar") {
+    if (ents.length > 0) throw new LossyError("a value-plus-fields node has no flow form");
+    return flowTok(n2);
+  }
+  if (ents.length === 0) return n2.array ? "[]" : "{}";
+  const keyed = ents.filter((e3) => e3.key !== null);
+  if (keyed.length > 0 && keyed.length < ents.length) throw new LossyError("a mixed container has no flow form");
+  if (ents.some((e3) => e3.edge === "back")) throw new LossyError("back-edges inside an inline !!<\u2026> schema are not serializable");
+  const item = (e3) => {
+    const v = isPointer(e3.value) ? flowPtr(e3.value) : flowText(e3.value);
+    return e3.key === null ? v : `${flowKey(e3.key)}: ${v}`;
+  };
+  return keyed.length === 0 ? `[${ents.map(item).join(", ")}]` : `{${ents.map(item).join(", ")}}`;
+}
+function nonFinite(v) {
+  return Number.isNaN(v) ? ".nan" : v === Infinity ? ".inf" : "-.inf";
+}
+function flowTok(s2) {
+  const v = s2.value;
+  if (v === null) return "null";
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) return nonFinite(v);
+    return String(v);
+  }
+  if (v !== "" && /^[^,:[\]{}'"#\s]+$/.test(v) && !"*&~!|>".includes(v[0]) && plainScalar(v).value === v) return v;
+  if (/[\n\r\u0000-\u0008\u000b-\u001f\u007f]/.test(v)) throw new LossyError("a control character has no flow form inside a !!<\u2026> tag");
+  return `'${v.replace(/'/g, "''")}'`;
+}
+function flowPtr(p2) {
+  const compact2 = renderPointer(p2, { spaced: false });
+  if (/['"\s]/.test(compact2)) throw new LossyError(`pointer "*${compact2}" does not fit a flow context`);
+  return `*${compact2}`;
+}
+function flowKey(k) {
+  return /^[\w.$/-]+$/.test(k) ? k : `'${k.replace(/'/g, "''")}'`;
+}
 
 // ../engine/ts/src/rewrite.ts
 function under(p2, x2) {
@@ -65556,7 +65658,9 @@ var DEFAULT_SETTINGS = {
   exports: [],
   annotations: ":annotations",
   tags: ":tags",
-  sidecars: "per-directory"
+  sidecars: "per-directory",
+  width: void 0,
+  theme: void 0
 };
 var DEFAULT_SETTINGS_SOURCE = `# .yamlover/settings.yamlover \u2014 project settings for this root (created with defaults).
 # Settings are DEFAULTS, never constraints: they only say where the server CREATES things when you
@@ -65569,6 +65673,7 @@ var DEFAULT_SETTINGS_SOURCE = `# .yamlover/settings.yamlover \u2014 project sett
 annotations: *:: annotations   # create new annotations in :annotations
 tags: *:: tags                 # create new tags in :tags
 sidecars: per-directory        # where derived thumbnail/crop blobs go (enum, not a path)
+# width: 100                   # reading width (ch) for prose views; browser settings override it
 `;
 function ensureSettingsFile(absRoot) {
   const file = path6.join(absRoot, ".yamlover", "settings.yamlover");
@@ -65592,9 +65697,20 @@ function loadSettings(absRoot) {
     exports: exportsSetting(valueAt(root, "exports")),
     annotations: locationSetting(valueAt(root, "annotations"), DEFAULT_SETTINGS.annotations),
     tags: locationSetting(valueAt(root, "tags"), DEFAULT_SETTINGS.tags),
-    sidecars: sidecarLocation(valueAt(root, "sidecars"), DEFAULT_SETTINGS.sidecars)
+    sidecars: sidecarLocation(valueAt(root, "sidecars"), DEFAULT_SETTINGS.sidecars),
+    width: intSetting(valueAt(root, "width"), 20, 400),
+    theme: enumSetting(valueAt(root, "theme"), ["dark", "light"])
   };
 }
+function intSetting(v, min, max) {
+  if (v === void 0 || isPointer(v) || v.kind !== "scalar") return void 0;
+  const n2 = typeof v.value === "number" ? v.value : NaN;
+  return Number.isInteger(n2) && n2 >= min && n2 <= max ? n2 : void 0;
+}
+function enumSetting(v, values) {
+  if (v === void 0 || isPointer(v) || v.kind !== "scalar") return void 0;
+  return values.includes(v.value) ? v.value : void 0;
+}
 function uriSetting(v) {
   if (v === void 0) return void 0;
   if (isPointer(v)) return v.base.scope === "link" ? v.base.authority : void 0;
@@ -66434,7 +66550,11 @@ function findGitRoot(start) {
 
 // src/server/node-kind.ts
 function ownedEntries(s2, p2) {
-  return s2.entries(p2).filter((e3) => e3.kind !== "back");
+  const own = s2.entries(p2).filter((e3) => e3.kind !== "back");
+  const unrealized = s2.unrealizedRefs(p2).filter((u2) => u2.edge !== "back");
+  if (unrealized.length === 0) return own;
+  for (const u2 of unrealized) own.push({ to: "", label: u2.label, pos: u2.pos, kind: "ref", raw: u2.raw });
+  return own.sort((a2, b) => (a2.pos ?? 0) - (b.pos ?? 0));
 }
 function displayKind(s2, p2, row) {
   const ents = ownedEntries(s2, p2);
@@ -66529,6 +66649,7 @@ function createHandlers(dataRoot, opts = {}) {
   const rootName = path10.basename(path10.resolve(dataRoot)) || "/";
   const dbPath = path10.join(dataRoot, ".yamlover", "index.db");
   const settingsFile = path10.join(dataRoot, ".yamlover", "settings.yamlover");
+  const settingsRel = path10.relative(dataRoot, settingsFile).split(path10.sep).join("/");
   if (opts.ensureSettings) {
     try {
       ensureSettingsFile(dataRoot);
@@ -66555,6 +66676,7 @@ function createHandlers(dataRoot, opts = {}) {
   };
   const broadcast = (diff2) => {
     if (diff2.added.length + diff2.changed.length + diff2.removed.length + diff2.moved.length === 0) return;
+    if (diff2.changed.includes(settingsRel) || diff2.added.includes(settingsRel)) settings = loadSettings(dataRoot);
     const toClient = (rel) => segsToStr(rel.split("/"));
     sseWrite({
       type: "diff",
@@ -66867,6 +66989,17 @@ function createHandlers(dataRoot, opts = {}) {
         ).then((body) => sendJson(res, 200, body)).catch((e3) => sendJson(res, 400, { error: String(e3.message || e3) }));
         return;
       }
+      if (req.method === "POST" && url.pathname === "/api/preview") {
+        readBody(req).then((data) => sendJson(res, 200, previewPayload(String(data.source ?? "")))).catch((e3) => sendJson(res, 400, { error: String(e3.message || e3) }));
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/api/edit-text") {
+        readBody(req).then((data) => {
+          const d = data;
+          sendJson(res, 200, { source: applyTextEdits(String(d.source ?? ""), Array.isArray(d.edits) ? d.edits : []) });
+        }).catch((e3) => sendJson(res, 400, { error: String(e3.message || e3) }));
+        return;
+      }
       if (req.method === "POST" && url.pathname === "/api/mv") {
         readBody(req).then(
           (data) => enqueue(async () => {
@@ -66912,20 +67045,6 @@ function createHandlers(dataRoot, opts = {}) {
         sendJson(res, 200, { source, settings, path: ":.yamlover:settings.yamlover" });
         return;
       }
-      if (req.method === "POST" && url.pathname === "/api/config") {
-        readBody(req).then(
-          (data) => enqueue(async () => {
-            const source = String(data?.source ?? "");
-            parseYamlover(source, settingsFile);
-            fs10.mkdirSync(path10.dirname(settingsFile), { recursive: true });
-            fs10.writeFileSync(settingsFile, source);
-            settings = loadSettings(dataRoot);
-            broadcast(await doReindexFile(settingsFile));
-            return { ok: true, settings };
-          })
-        ).then((body) => sendJson(res, 200, body)).catch((e3) => sendJson(res, 400, { error: String(e3.message || e3) }));
-        return;
-      }
       const segs = strToSegs(url.searchParams.get("path") || ":");
       const p2 = storePath(segs);
       const depth = parseDepth(url.searchParams.get("depth"));
@@ -67074,12 +67193,12 @@ var hasSubchapterChild = (s2, p2) => s2.children(p2).some((c3) => {
 });
 function downstreamEntries(s2, p2) {
   const isSet = !!s2.node(p2)?.meta?.set;
-  let own = s2.entries(p2).filter((e3) => e3.kind !== "back" && !(e3.kind === "contain" && isHidden(s2, e3.to)));
-  const seen = new Set(own.map((e3) => relKey(e3.label, e3.to)));
+  let own = ownedEntries(s2, p2).filter((e3) => !(e3.kind === "contain" && isHidden(s2, e3.to)));
+  const seen = new Set(own.map((e3) => relKey(e3.label, e3.to || e3.raw || "")));
   if (isSet) {
     const kept = /* @__PURE__ */ new Set();
     own = own.filter((e3) => {
-      const k = relKey(e3.label, e3.to);
+      const k = relKey(e3.label, e3.to || e3.raw || "");
       if (kept.has(k)) return false;
       kept.add(k);
       return true;
@@ -67108,6 +67227,7 @@ function projectValue(dataRoot, s2, segs, depth, top) {
   const currentDoc = documentRootSegs(s2, segs);
   const project = (c3) => {
     if (c3.kind === "contain") return projectValue(dataRoot, s2, [...segs, c3.label ?? c3.pos ?? 0], depth - 1, false);
+    if (!c3.to) return refMarker(c3.raw ?? "", null);
     const targetSegs = storePathToSegs(c3.to);
     return depth === Infinity ? refMarker(refPointerText(s2, targetSegs, currentDoc), segsToStr(targetSegs)) : linkMarker(dataRoot, s2, targetSegs);
   };
@@ -67145,8 +67265,25 @@ function irNodeAt(doc, segs) {
   }
   return node;
 }
+function scalarRawToken(node) {
+  if (isPointer(node) || node.kind !== "scalar") return void 0;
+  const raw = node.raw;
+  if (raw == null || raw.includes("\n")) return void 0;
+  const v = node.value;
+  if (typeof v === "string" && v.includes("\n")) return void 0;
+  const plain = v === null ? "null" : String(v);
+  return raw === plain ? void 0 : raw;
+}
 function tagOf(n2) {
-  return n2.meta?.set ? "!!set" : void 0;
+  const parts = [];
+  if (n2.meta?.schema !== void 0) {
+    try {
+      parts.push(schemaTagToken(n2.meta.schema));
+    } catch {
+    }
+  }
+  if (n2.meta?.set) parts.push("!!set");
+  return parts.length ? parts.join(" ") : void 0;
 }
 function nodeDeco(bucket, node) {
   const anchors = (node.meta?.anchors ?? []).map(anchorBody);
@@ -67163,7 +67300,9 @@ function collectComments(doc, segs, depth) {
   {
     const self2 = {};
     nodeDeco(self2, root);
-    if (self2.anchors || self2.tag || self2.valueTrailing) out[""] = self2;
+    const raw = scalarRawToken(root);
+    if (raw) self2.raw = raw;
+    if (self2.anchors || self2.tag || self2.valueTrailing || self2.raw) out[""] = self2;
   }
   const head = (root.meta?.head ?? []).map((c3) => c3.text);
   if (head.length > 0) out.$head = head;
@@ -67186,7 +67325,11 @@ function collectComments(doc, segs, depth) {
       const leadComment = e3.meta?.comments?.find((c3) => c3.placement === "leading");
       if (e3.meta?.blankBefore || leadComment?.blankBefore) bucket.blankBefore = true;
       if (isPointer(e3.value)) bucket.pointer = renderPointer(e3.value);
-      else nodeDeco(bucket, e3.value);
+      else {
+        nodeDeco(bucket, e3.value);
+        const raw = scalarRawToken(e3.value);
+        if (raw) bucket.raw = raw;
+      }
       if (Object.keys(bucket).length > 0) out[rel + cont] = bucket;
       if (e3.edge === "contain" && !isPointer(e3.value)) walk(e3.value, rel + cont, d - 1, false);
     }
@@ -67203,7 +67346,7 @@ function projectSchema(dataRoot, s2, segs, depth, top) {
   const schema = { type: typeName(s2, p2, row) };
   if (row.format) schema.format = row.format;
   const kids = downstreamEntries(s2, p2);
-  const sub = (c3) => c3.kind === "contain" ? projectSchema(dataRoot, s2, [...segs, c3.label ?? c3.pos ?? 0], depth - 1, false) : linkMarker(dataRoot, s2, storePathToSegs(c3.to));
+  const sub = (c3) => c3.kind === "contain" ? projectSchema(dataRoot, s2, [...segs, c3.label ?? c3.pos ?? 0], depth - 1, false) : c3.to ? linkMarker(dataRoot, s2, storePathToSegs(c3.to)) : refMarker(c3.raw ?? "", null);
   if (k === "object" || k === "mix" || k === "omni") {
     const props = {};
     for (const c3 of kids) props[c3.label ?? `[${c3.pos}]`] = sub(c3);
@@ -67235,7 +67378,9 @@ function linkMarker(dataRoot, s2, segs) {
   else if (k === "omni" || k === "mix") {
     info.count = ownedEntries(s2, p2).length;
     if (k === "omni") info.value = wireScalar(row.value);
-  } else info.count = s2.children(p2).filter((c3) => !isHidden(s2, c3.to)).length;
+  } else {
+    info.count = ownedEntries(s2, p2).filter((e3) => !(e3.kind === "contain" && isHidden(s2, e3.to))).length;
+  }
   if (row.format === TAG_FORMAT) {
     const c3 = s2.node(p2 + ":color")?.value;
     if (typeof c3 === "string") info.color = c3;
@@ -67663,16 +67808,24 @@ function nearestDirSegs(dataRoot, segs) {
   }
   return null;
 }
-function chapterSource(dataRoot, s2, segs) {
+var YAMLOVER_ONLY = /\.yamlover$/i;
+var BLOCK_YAML = /\.(ya?ml|yamlover)$/i;
+var JSON_FILE = /\.(json|json5|json5p)$/i;
+function resolveBacking(dataRoot, s2, segs) {
   const docSegs = documentRootSegs(s2, segs);
   const docFs = path10.resolve(dataRoot, ...docSegs.map(String));
   const dirBacked = fs10.existsSync(docFs) && fs10.statSync(docFs).isDirectory();
   const bodyFile = dirBacked ? path10.join(docFs, ".yamlover", "body.yamlover") : docFs;
-  if (!bodyFile.endsWith(".yamlover") || !fs10.existsSync(bodyFile)) {
-    throw new Error("unsupported chapter source (need a .yamlover body)");
-  }
   return { docSegs, bodyFile, dirBacked };
 }
+function chapterSource(dataRoot, s2, segs, allow = YAMLOVER_ONLY) {
+  const r2 = resolveBacking(dataRoot, s2, segs);
+  const okExt = r2.dirBacked ? r2.bodyFile.endsWith(".yamlover") : allow.test(r2.bodyFile);
+  if (!okExt || !fs10.existsSync(r2.bodyFile)) {
+    throw new Error("unsupported edit source (need a .yamlover / .yaml / .yml body)");
+  }
+  return r2;
+}
 function pasteIntoChapter(dataRoot, s2, segs, name, bytes) {
   const { docSegs, bodyFile, dirBacked } = chapterSource(dataRoot, s2, segs);
   const writeDirSegs = dirBacked ? docSegs : docSegs.slice(0, -1);
@@ -67902,8 +68055,11 @@ function textChunkLines(text, indent) {
 function chapterEntries(lines, r2) {
   const starts = [];
   if (r2.marker >= 0) {
-    const inline = lines[r2.marker].replace(/^\s*-\s*/, "");
-    if (inline.trim()) starts.push({ key: /^-/.test(inline) ? null : inline.match(/^([^:\s]+):/)?.[1] ?? null, start: r2.marker, inline: true });
+    const raw = lines[r2.marker].replace(/^\s*/, "");
+    if (raw === "-" || raw.startsWith("- ")) {
+      const inline = raw.replace(/^-\s*/, "");
+      if (inline.trim()) starts.push({ key: /^-/.test(inline) ? null : inline.match(/^([^:\s]+):/)?.[1] ?? null, start: r2.marker, inline: true });
+    }
   }
   for (let i2 = r2.lo; i2 < r2.hi; i2++) {
     if (!isContentLine2(lines[i2])) continue;
@@ -67934,7 +68090,8 @@ function entryHead(lines, e3) {
 function isContainerEntry(lines, e3, childIndent) {
   const head = entryHead(lines, e3);
   if (/^[|>][+-]?\d*$/.test(head.trim())) return itemHasFields(lines, e3, childIndent);
-  if (/^[^\s"'*|>#-][^:]*:(\s|$)/.test(head)) return true;
+  const bare = head.replace(/\s+#.*$/, "");
+  if (/^[^\s"'*|>#-][^:]*:(\s|$)/.test(bare)) return true;
   for (let i2 = e3.start + 1; i2 < e3.end; i2++) {
     if (!isContentLine2(lines[i2])) continue;
     const ind = indentOf2(lines[i2]);
@@ -68156,6 +68313,51 @@ function editChapterSource(src, within, op, valueSrc, meta) {
   assignAt(lines, reachChapter(lines, within.slice(0, -1)), within[within.length - 1], op, valueSrc, meta);
   return lines.join("\n");
 }
+function jsonValueSpan(src, es, ee) {
+  const last = src[ee - 1];
+  if (last === '"' || last === "'") {
+    for (let j2 = ee - 2; j2 >= es; j2--) {
+      if (src[j2] !== last) continue;
+      let bs = 0;
+      for (let k = j2 - 1; k >= es && src[k] === "\\"; k--) bs++;
+      if (bs % 2 === 0) return [j2, ee];
+    }
+    throw new Error("could not locate the string value in the source");
+  }
+  let j = ee;
+  while (j > es && !/[\s,:{}[\]]/.test(src[j - 1])) j--;
+  return [j, ee];
+}
+function yamloverScalarToJsonToken(valueSrc) {
+  const root = parseYamlover(valueSrc, "<edit>").root;
+  if (root.kind !== "scalar") throw new Error("only a scalar value is editable in a JSON file");
+  const v = root.value;
+  if (v === null) return "null";
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (typeof v === "number") return /^[-+]?(\d+\.?\d*|\.\d+)([eE][-+]?\d+)?$/.test(root.raw) ? root.raw : String(v);
+  return JSON.stringify(v);
+}
+function editJsonScalar(src, within, token) {
+  if (within.length === 0) throw new Error("cannot edit the JSON document root as a scalar value");
+  let node = parseJson5p(src, "<edit>").root;
+  for (let k = 0; k < within.length; k++) {
+    const seg = within[k];
+    const entries = node.entries ?? [];
+    const entry = typeof seg === "number" ? entries.filter((e3) => e3.edge === "contain" && e3.key === null)[seg] : entries.find((e3) => e3.edge === "contain" && e3.key === seg);
+    if (!entry) throw new Error(`no entry at ${typeof seg === "number" ? `[${seg}]` : seg}`);
+    const value = entry.value;
+    if (k === within.length - 1) {
+      if (isPointer(value) || value.kind !== "scalar") throw new Error("only a scalar value is editable in a JSON file");
+      const span = entry.meta?.span;
+      if (!span) throw new Error("no source span for the target value");
+      const [vs, ve] = jsonValueSpan(src, span.start, span.end);
+      return src.slice(0, vs) + token + src.slice(ve);
+    }
+    if (isPointer(value) || value.kind !== "mapping") throw new Error(`cannot descend into a non-container at ${typeof seg === "number" ? `[${seg}]` : seg}`);
+    node = value;
+  }
+  throw new Error("empty JSON edit path");
+}
 var isPointerValue = (src) => /^\*\S*$/.test(src.trim()) && !src.includes("\n");
 function isPlainDir(dataRoot, s2, segs) {
   if (!segs.every((g) => typeof g === "string")) return false;
@@ -68178,6 +68380,7 @@ function bornAsDocument(dataRoot, e3, tag) {
 }
 function applyEdits2(dataRoot, s2, edits) {
   const byFile = /* @__PURE__ */ new Map();
+  const jsonByFile = /* @__PURE__ */ new Map();
   const appended = [];
   const created = [];
   for (const e3 of edits) {
@@ -68191,7 +68394,15 @@ function applyEdits2(dataRoot, s2, edits) {
       created.push(segsToStr([...editSegs, final]));
       continue;
     }
-    const { docSegs, bodyFile, dirBacked } = chapterSource(dataRoot, s2, editSegs);
+    const backing = resolveBacking(dataRoot, s2, editSegs);
+    if (!backing.dirBacked && JSON_FILE.test(backing.bodyFile)) {
+      if (op !== "emplace") throw new Error("only scalar value edits (emplace) are supported for JSON files");
+      const jlist = jsonByFile.get(backing.bodyFile) ?? [];
+      jlist.push({ within: editSegs.slice(backing.docSegs.length), valueSrc: String(e3.yamlover ?? "") });
+      jsonByFile.set(backing.bodyFile, jlist);
+      continue;
+    }
+    const { docSegs, bodyFile, dirBacked } = chapterSource(dataRoot, s2, editSegs, BLOCK_YAML);
     if (op === "insert" && !e3.concrete?.includes("/")) {
       const last = editSegs[editSegs.length - 1];
       if (typeof last !== "number") appended.push(editSegs);
@@ -68232,8 +68443,55 @@ function applyEdits2(dataRoot, s2, edits) {
     fs10.writeFileSync(bodyFile, src);
     touched.push(bodyFile);
   }
+  for (const [file, jedits] of jsonByFile) {
+    let src = fs10.readFileSync(file, "utf8");
+    for (const j of jedits) {
+      src = editJsonScalar(src, j.within, yamloverScalarToJsonToken(j.valueSrc));
+    }
+    fs10.writeFileSync(file, src);
+    touched.push(file);
+  }
   return { touched, created, appended };
 }
+var PREVIEW_ROOT = path10.join(os.tmpdir(), ".yamlover-preview-nonexistent");
+function previewPayload(source) {
+  const doc = parseYamlover(source, "<preview>");
+  doc.root.meta = { ...doc.root.meta, documentRoot: true, ...doc.head?.length ? { head: doc.head } : {} };
+  const s2 = new Store(":memory:");
+  try {
+    s2.indexDocument(doc);
+    const row = s2.node(":");
+    return {
+      path: ":",
+      type: tocType(s2, ":", row),
+      format: row.format ?? null,
+      ...facetsOf(s2, ":", row),
+      concrete: "yamlover",
+      // by construction — the document IS yamlover text
+      documentPath: ":",
+      title: titleOf(s2, ":"),
+      description: descriptionOf(s2, ":"),
+      value: projectValue(PREVIEW_ROOT, s2, [], Infinity, true),
+      comments: collectComments(doc, [], Infinity),
+      relations: {}
+      // a standalone document has no project around it
+    };
+  } finally {
+    s2.close();
+  }
+}
+function applyTextEdits(src, edits) {
+  let out = src;
+  for (const e3 of edits) {
+    if (e3.concrete || e3.name) throw new Error("`concrete`/`name` are only for file-backed edits");
+    const valueSrc = String(e3.yamlover ?? "");
+    const meta = e3.meta === void 0 ? void 0 : e3.meta === null ? null : String(e3.meta);
+    if (valueSrc && !isPointerValue(valueSrc)) parseYamlover(valueSrc, "<edit>");
+    out = editChapterSource(out, strToSegs(String(e3.path ?? "")), String(e3.op ?? ""), valueSrc, meta);
+  }
+  parseYamlover(out, "<edit-result>");
+  return out;
+}
 function firstContentIndent2(lines) {
   for (const l2 of lines) if (isContentLine2(l2)) return indentOf2(l2);
   return 0;
@@ -68354,8 +68612,10 @@ function notFound(res, url) {
   sendJson(res, 404, { error: `no such node/endpoint: ${url.pathname}?${url.searchParams}` });
 }
 export {
+  applyTextEdits,
   createHandlers,
-  mergeAgentDoc
+  mergeAgentDoc,
+  previewPayload
 };
 /*! Bundled license information:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yamlover",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "description": "Browse a yamlover tree in the web: npx yamlover <root> serves a React SPA over a directory.",
   "type": "module",
   "license": "MIT",