yamlover 0.3.2 → 0.3.4

package/src/client/renderers/registry.tsx

@@ -79,6 +79,9 @@ export interface Chunk {
   path: string;
   type: string;
   format: string | null;
+  valueType?: string | null; // renderer dispatch facets (TYPES.md §9) — so a tagged chunk still routes
+  hasKeyed?: boolean;
+  hasOrdinal?: boolean;
   /** The JSON-space path of the document this chunk belongs to (the enclosing
    *  chapter's `documentPath`) — the anchor a document-relative (`/…`) marklower
    *  link in the chunk resolves against. */
@@ -99,11 +102,32 @@ export interface TocView {
   loadDepth?: number;
 }
 
+/** The three TYPE FACETS a renderer dispatches on (TYPES.md §9): the scalar self-VALUE's type,
+ *  the node's `format`, and whether it owns keyed/ordinal elements. */
+export interface TypeFacets {
+  valueType: string | null;
+  format: string | null;
+  hasKeyed: boolean;
+  hasOrdinal: boolean;
+}
+/** A renderer's acceptance predicate — a hand-coded type formula. What it does NOT test, it
+ *  TOLERATES: a `byFormat("text/markdown")` matcher ignores the keyed/ordinal facets, so a
+ *  markdown chunk that gained `yamlover-annotations` keys (an omni node) still matches. */
+export type Accepts = (f: TypeFacets) => boolean;
+
+/** Any projected node/chunk/link shape carrying the facet fields. */
+type FacetSource = { type?: string; format?: string | null; valueType?: string | null; hasKeyed?: boolean; hasOrdinal?: boolean };
+const facetsFrom = (n: FacetSource): TypeFacets => ({ valueType: n.valueType ?? null, format: n.format ?? null, hasKeyed: !!n.hasKeyed, hasOrdinal: !!n.hasOrdinal });
+/** The common matcher: claims a node whose `format` is one of `fmts` — tolerant of all structure. */
+const byFormat = (...fmts: string[]): Accepts => (f) => f.format !== null && fmts.includes(f.format);
+
 export interface Renderer {
   name: string;
-  /** The (type, format) tuples this renderer claims. A `null` format matches a
-   *  node that carries no `format`; a string format matches that format exactly. */
-  accepts: ReadonlyArray<readonly [type: string, format: string | null]>;
+  /** Whether this renderer claims a node, from its {@link TypeFacets}. */
+  accepts: Accepts;
+  /** Tie-break among matches — the highest wins. Format matchers are 2; the bare-string
+   *  default (marklower) is 1. */
+  specificity: number;
   /** Value depth `NodeView` must fetch for this renderer (default 1). A chapter
    *  needs 2: its `chunks`/`children` arrays one level, their elements the next. */
   depth?: number;
@@ -129,12 +153,10 @@ export interface Renderer {
  */
 const EXPLORER: Renderer = {
   name: "explorer",
-  accepts: [
-    ["object", "x-yamlover-tag"],
-    ["variant", "x-yamlover-tag"],
-    ["string", "x-yamlover-tag"],
-    ["null", "x-yamlover-tag"],
-  ],
+  // a tag, whatever shape it projects (object / variant / leaf string / bare null) — the format
+  // alone identifies it; the grid shows the tagged MATERIALS. Also the dir-concrete fallback below.
+  accepts: byFormat("x-yamlover-tag"),
+  specificity: 2,
   render: (node, onNavigate) => <ExplorerView node={node} onNavigate={onNavigate} />,
   config: (rerender) => <ExplorerViewControl rerender={rerender} />, // large/small icons (`?view=`)
 };
@@ -145,7 +167,8 @@ const isDirConcrete = (concrete: string | null | undefined): boolean => concrete
 const REGISTRY: Renderer[] = [
   {
     name: "chapter",
-    accepts: [["object", "x-yamlover-chapter"]],
+    accepts: byFormat("x-yamlover-chapter"),
+    specificity: 2,
     depth: 2, // reach the chunk/subchapter elements (arrays one level, items the next)
     tocView: chapterTocView,
     render: (node, onNavigate) => <ChapterView node={node} onNavigate={onNavigate} />,
@@ -155,10 +178,8 @@ const REGISTRY: Renderer[] = [
     // notch below Markdown. A chapter's prose chunks route here — both the bare
     // (string, null) form and the explicit `text/marklower` the chunk schema applies.
     name: "marklower",
-    accepts: [
-      ["string", null],
-      ["string", "text/marklower"],
-    ],
+    accepts: (f) => f.format === "text/marklower" || (f.format === null && f.valueType === "string"),
+    specificity: 1, // the bare-string default — a tagged bare string (format-less) still routes here
     render: (node, onNavigate) => <MarklowerView node={node} onNavigate={onNavigate} />,
     renderChunk: (chunk, onNavigate) => <MarklowerChunk chunk={chunk} onNavigate={onNavigate} />,
   },
@@ -166,14 +187,16 @@ const REGISTRY: Renderer[] = [
     // Markdown (the component file is text.tsx for historical reasons; the renderer —
     // its tab label and `?format=` key — is named for what it renders).
     name: "markdown",
-    accepts: [["string", "text/markdown"]],
+    accepts: byFormat("text/markdown"),
+    specificity: 2,
     render: (node) => <TextView node={node} />,
     renderChunk: (chunk) => <TextChunk chunk={chunk} />,
     config: (rerender) => <MarkupWidthControl rerender={rerender} />,
   },
   {
     name: "asciidoc",
-    accepts: [["string", "text/asciidoc"]],
+    accepts: byFormat("text/asciidoc"),
+    specificity: 2,
     render: (node) => <AsciidocView node={node} />,
     renderChunk: (chunk) => <AsciidocChunk chunk={chunk} />,
     config: (rerender) => <MarkupWidthControl rerender={rerender} />,
@@ -182,10 +205,8 @@ const REGISTRY: Renderer[] = [
     // Delimited text (CSV/TSV, a string) shown as a table; its parsing options
     // (separator, header) ride in the URL query — see csv.tsx.
     name: "csv",
-    accepts: [
-      ["string", "text/csv"],
-      ["string", "text/tab-separated-values"],
-    ],
+    accepts: byFormat("text/csv", "text/tab-separated-values"),
+    specificity: 2,
     render: (node) => <CsvView node={node} />,
     renderChunk: (chunk) => <CsvChunk chunk={chunk} />,
     config: (rerender) => <CsvControls rerender={rerender} />,
@@ -195,7 +216,8 @@ const REGISTRY: Renderer[] = [
     // CP866 / Windows-1251 / KOI8-R / UTF-8 (see plaintext.tsx). Served as raw
     // bytes so the encoding is the client's to choose.
     name: "plaintext",
-    accepts: [["binary", "text/plain"]],
+    accepts: byFormat("text/plain"),
+    specificity: 2,
     render: (node) => <PlaintextView node={node} />,
     renderChunk: (chunk) => <PlaintextChunk chunk={chunk} />,
     config: (rerender) => <EncodingControl rerender={rerender} />,
@@ -203,41 +225,40 @@ const REGISTRY: Renderer[] = [
   {
     // RTF — a dependency-free converter to HTML (see rtf.tsx).
     name: "rtf",
-    accepts: [["binary", "application/rtf"]],
+    accepts: byFormat("application/rtf"),
+    specificity: 2,
     render: (node) => <RtfView node={node} />,
     renderChunk: (chunk) => <RtfChunk chunk={chunk} />,
   },
   {
     // .docx (Office Open XML) via mammoth, lazily loaded.
     name: "docx",
-    accepts: [["binary", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"]],
+    accepts: byFormat("application/vnd.openxmlformats-officedocument.wordprocessingml.document"),
+    specificity: 2,
     render: (node) => lazily(<DocxView node={node} />),
     renderChunk: (chunk) => lazily(<DocxChunk chunk={chunk} />),
   },
   {
     // Excel workbooks — .xlsx and legacy .xls — via SheetJS, lazily loaded.
     name: "spreadsheet",
-    accepts: [
-      ["binary", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"],
-      ["binary", "application/vnd.ms-excel"],
-    ],
+    accepts: byFormat("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-excel"),
+    specificity: 2,
     render: (node) => lazily(<SpreadsheetView node={node} />),
     renderChunk: (chunk) => lazily(<SpreadsheetChunk chunk={chunk} />),
   },
   {
     // Legacy .doc (Word 97–2003 binary) — no in-browser parser; download fallback.
     name: "doc",
-    accepts: [["binary", "application/msword"]],
+    accepts: byFormat("application/msword"),
+    specificity: 2,
     render: (node) => <DocView node={node} />,
     renderChunk: (chunk) => <DocChunk chunk={chunk} />,
   },
   {
     // KML / KMZ geographic overlays drawn on a Leaflet map (lazily loaded).
     name: "map",
-    accepts: [
-      ["binary", "application/vnd.google-earth.kml+xml"],
-      ["binary", "application/vnd.google-earth.kmz"],
-    ],
+    accepts: byFormat("application/vnd.google-earth.kml+xml", "application/vnd.google-earth.kmz"),
+    specificity: 2,
     render: (node) => lazily(<MapView node={node} />),
     renderChunk: (chunk) => lazily(<MapChunk chunk={chunk} />),
   },
@@ -245,7 +266,8 @@ const REGISTRY: Renderer[] = [
     // LaTeX math (a string) typeset with KaTeX, both whole and inline. marklower
     // reuses the same engine for its `$$…$$` spans.
     name: "latex",
-    accepts: [["string", "text/x-latex"]],
+    accepts: byFormat("text/x-latex"),
+    specificity: 2,
     render: (node) => <LatexView node={node} />,
     renderChunk: (chunk) => <LatexChunk chunk={chunk} />,
   },
@@ -253,7 +275,8 @@ const REGISTRY: Renderer[] = [
     // PlantUML source (a string) shown as the diagram it compiles to, both as a
     // whole node and inline as a chapter chunk.
     name: "plantuml",
-    accepts: [["string", "text/x-plantuml"]],
+    accepts: byFormat("text/x-plantuml"),
+    specificity: 2,
     render: (node) => <PlantumlView node={node} />,
     renderChunk: (chunk) => <PlantumlChunk chunk={chunk} />,
   },
@@ -261,64 +284,64 @@ const REGISTRY: Renderer[] = [
   {
     // File-backed binaries the server tags with an inferred image format.
     name: "image",
-    accepts: [
-      ["binary", "image/png"],
-      ["binary", "image/jpeg"],
-      ["binary", "image/gif"],
-      ["binary", "image/webp"],
-      ["binary", "image/avif"],
-      ["binary", "image/bmp"],
-      ["binary", "image/x-icon"],
-      ["binary", "image/svg+xml"],
-    ],
+    accepts: byFormat("image/png", "image/jpeg", "image/gif", "image/webp", "image/avif", "image/bmp", "image/x-icon", "image/svg+xml"),
+    specificity: 2,
     render: (node) => lazily(<ImageView node={node} />),
     renderChunk: (chunk) => lazily(<ImageChunk chunk={chunk} />),
   },
   {
     name: "html",
-    accepts: [["binary", "text/html"]],
+    accepts: byFormat("text/html"),
+    specificity: 2,
     render: (node) => <HtmlView node={node} />,
     renderChunk: (chunk) => <HtmlView node={chunkNode(chunk)} />,
   },
   {
     name: "fb2",
-    accepts: [["binary", "application/x-fictionbook+xml"]],
+    accepts: byFormat("application/x-fictionbook+xml"),
+    specificity: 2,
     render: (node) => <Fb2View node={node} />,
     renderChunk: (chunk) => <Fb2View node={chunkNode(chunk)} />,
   },
   {
     name: "epub",
-    accepts: [["binary", "application/epub+zip"]],
+    accepts: byFormat("application/epub+zip"),
+    specificity: 2,
     render: (node) => <EpubView node={node} />,
     renderChunk: (chunk) => <EpubView node={chunkNode(chunk)} />,
   },
   {
     name: "pdf",
-    accepts: [["binary", "application/pdf"]],
+    accepts: byFormat("application/pdf"),
+    specificity: 2,
     render: (node) => lazily(<PdfView node={node} />),
     renderChunk: (chunk) => lazily(<PdfView node={chunkNode(chunk)} />),
   },
   {
     name: "djvu",
-    accepts: [["binary", "image/vnd.djvu"]],
+    accepts: byFormat("image/vnd.djvu"),
+    specificity: 2,
     render: (node) => lazily(<DjvuView node={node} />),
     renderChunk: (chunk) => lazily(<DjvuView node={chunkNode(chunk)} />),
   },
   {
     name: "psd",
-    accepts: [["binary", "image/vnd.adobe.photoshop"]],
+    accepts: byFormat("image/vnd.adobe.photoshop"),
+    specificity: 2,
     render: (node) => lazily(<PsdView node={node} />),
     renderChunk: (chunk) => lazily(<PsdView node={chunkNode(chunk)} />),
   },
   {
     name: "tiff",
-    accepts: [["binary", "image/tiff"]],
+    accepts: byFormat("image/tiff"),
+    specificity: 2,
     render: (node) => lazily(<TiffView node={node} />),
     renderChunk: (chunk) => lazily(<TiffView node={chunkNode(chunk)} />),
   },
   {
     name: "heic",
-    accepts: [["binary", "image/heic"]],
+    accepts: byFormat("image/heic"),
+    specificity: 2,
     render: (node) => lazily(<HeicView node={node} />),
     renderChunk: (chunk) => lazily(<HeicView node={chunkNode(chunk)} />),
   },
@@ -356,33 +379,32 @@ function chapterTocView(node: TreeNode): TocView {
   };
 }
 
-/** The renderer whose `accepts` covers `(type, format)`, or null when none does. */
-export function rendererFor(type: string, format: string | null): Renderer | null {
-  return REGISTRY.find((r) => r.accepts.some(([t, f]) => t === type && f === format)) ?? null;
+/** The renderer that claims `src`'s facets, or null when none does: of the matchers that accept
+ *  it, the most SPECIFIC (highest `specificity`) wins (TYPES.md §9). */
+export function rendererFor(src: FacetSource): Renderer | null {
+  const f = facetsFrom(src);
+  let best: Renderer | null = null;
+  for (const r of REGISTRY) if (r.accepts(f) && (best === null || r.specificity > best.specificity)) best = r;
+  return best;
 }
 
-/** The renderer for a node: its (type, format) claim, else — for a node stored as a
- *  filesystem directory that no format renderer claims (a dir-backed chapter stays a
- *  chapter) — the explorer, else null → the default tabbed view. */
+/** The renderer for a node: its facet claim, else — for a node stored as a filesystem directory
+ *  that no format renderer claims (a dir-backed chapter stays a chapter) — the explorer, else
+ *  null → the default tabbed view. */
 export function getRenderer(node: NodeJson): Renderer | null {
-  const r = rendererFor(node.type, node.format ?? null);
-  if (r) return r;
-  return isDirConcrete(node.concrete) ? EXPLORER : null;
+  return rendererFor(node) ?? (isDirConcrete(node.concrete) ? EXPLORER : null);
 }
 
-/** The name (= representation key / `?format=` value) of the renderer for
- *  `(type, format)` — with the same directory-concrete explorer fallback as
- *  {@link getRenderer} — or null when none claims it. */
-export function rendererName(type: string, format: string | null, concrete?: string | null): string | null {
-  const r = rendererFor(type, format);
-  if (r) return r.name;
-  return isDirConcrete(concrete) ? EXPLORER.name : null;
+/** The name (= representation key / `?format=` value) of the renderer that claims `src` — with the
+ *  same directory-concrete explorer fallback as {@link getRenderer} — or null when none claims it. */
+export function rendererName(src: FacetSource, concrete?: string | null): string | null {
+  return rendererFor(src)?.name ?? (isDirConcrete(concrete) ? EXPLORER.name : null);
 }
 
 /** How `node` appears in the TOC: its renderer's `tocView`, or — when no renderer
  *  claims it — its own children, lazily loaded (the passive default). */
 export function tocView(node: TreeNode): TocView {
-  const r = rendererFor(node.type, node.format);
+  const r = rendererFor(node);
   if (r?.tocView) return r.tocView(node);
   const loaded = node.children.length > 0;
   return { children: node.children, expandable: loaded ? node.children.length > 0 : node.hasChildren, loaded };

package/src/client/renderers/text.tsx

@@ -1,5 +1,6 @@
 import { marked } from "marked";
 import { NodeJson } from "../api";
+import { scalarValue } from "../render";
 import { Chunk } from "./registry";
 import { anchorizeHeadings, useHashScroll } from "./headings";
 import { Markup } from "./markup";
@@ -29,7 +30,7 @@ export function TextView({ node }: { node: NodeJson }) {
     <div className="text">
       {node.title && <h1 className="chapter-title">{node.title}</h1>}
       {node.description && <p className="chapter-subtitle">{node.description}</p>}
-      <Markup html={md(node.value)} />
+      <Markup html={md(scalarValue(node.value))} />
     </div>
   );
 }

package/src/client/styles.css

@@ -148,6 +148,10 @@ body {
   flex: 1 1 auto;
   padding: 14px 18px;
 }
+/* programmatically focused on TOC click (so the keyboard drives the viewer) — no focus ring */
+.right:focus {
+  outline: none;
+}
 .splitter {
   flex: 0 0 5px;
   cursor: col-resize;
@@ -519,6 +523,11 @@ a.chunk-index:hover {
   height: calc(100vh - 160px);
   min-height: 360px;
 }
+/* focused on mount so the keyboard scrolls the document — no focus ring on the scroller */
+.filepdf:focus,
+.filedjvu:focus {
+  outline: none;
+}
 .fileimage {
   /* keep the image's own aspect ratio — never stretch (007) */
   max-width: 100%;
@@ -864,7 +873,8 @@ a.chunk-index:hover {
   flex-wrap: wrap;
   gap: 4px;
 }
-.annotate-recents .tagtag {
+.annotate-recents .tagtag,
+.annotate-suggest .tagtag {
   border: 0;
   font: inherit;
   font-size: 11px;
@@ -876,10 +886,12 @@ a.chunk-index:hover {
    unclipped WRAPPER the child is clipped first; then a first round of hard offset drop-shadows
    in the MENU BACKGROUND color grows the silhouette by 1px (the gap), and a second round in
    the foreground color rings that — gap + ring, both following the actual tag shape. */
-.annotate-recents .tagframe {
+.annotate-recents .tagframe,
+.annotate-suggest .tagframe {
   display: inline-flex;
 }
-.annotate-recents .tagframe.sel {
+.annotate-recents .tagframe.sel,
+.annotate-suggest .tagframe.sel {
   filter:
     drop-shadow(1px 0 0 var(--bg-alt))
     drop-shadow(-1px 0 0 var(--bg-alt))
@@ -906,6 +918,25 @@ a.chunk-index:hover {
   outline: none;
   border-color: var(--dim);
 }
+/* the typeahead: the path input plus a suggestion list below it, spanning the menu width */
+.annotate-typeahead {
+  flex-basis: 100%;
+  min-width: 0;
+  position: relative;
+}
+.annotate-typeahead .annotate-taginput {
+  width: 100%;
+  box-sizing: border-box;
+}
+/* matched named tags as badges (the highlighted one rings via .tagframe.sel) */
+.annotate-suggest {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  margin-top: 5px;
+  max-height: 132px;
+  overflow-y: auto;
+}
 /* a region annotation drawn over a PDF page (the image overlay uses a Leaflet rectangle) */
 .pdf-page {
   position: relative;
@@ -1080,6 +1111,12 @@ mark.yo-annotation {
 .dirview-item:hover {
   background: var(--panel);
 }
+/* keyboard selection (roving focus — arrows walk, Enter opens) */
+.dirview-item:focus {
+  outline: none;
+  background: var(--panel);
+  box-shadow: 0 0 0 2px var(--accent) inset;
+}
 .dirview-icon {
   flex: none;
   width: 22px;

package/src/server/embed.ts

@@ -0,0 +1,187 @@
+/**
+ * embed.ts — surgical, indentation-aware edits that EMBED fragments and annotations into a
+ * yamlover host body (a standalone `*.yamlover` document, or a directory's
+ * `.yamlover/body.yamlover` overlay). Pure string→string transforms, like the chapter-list
+ * insertion in engine-api.ts — the parser tracks no spans, so we edit the source text directly,
+ * preserving the rest of the file (comments, formatting). See ANNOTATIONS.md.
+ *
+ * A host body is YAML-shaped: a mapping's keys at one indent; a sequence's `- ` items at the
+ * SAME indent as their key; an item/value body 2 deeper. We descend a `within` path of mapping
+ * KEYS (creating any that are absent, as empty blocks) to reach a target node, then:
+ *   • append an element to its `yamlover-annotations:` sequence (creating the key), or
+ *   • upsert a `<slug>:` entry into its `yamlover-fragments:` mapping (creating the key).
+ *
+ * Index (sequence-position) descent — e.g. tagging a chapter CHUNK, which would turn its
+ * block-scalar into an omni node — is intentionally NOT handled here; the server resolves such a
+ * target to a key-addressable host. Keep this module free of fs / Store coupling so it unit-tests
+ * in isolation (see test/embed.test.ts).
+ */
+
+const ANNOTATIONS_KEY = "yamlover-annotations";
+const FRAGMENTS_KEY = "yamlover-fragments";
+
+const indentOf = (line: string): number => { let i = 0; while (line[i] === " ") i++; return i; };
+const isContentLine = (line: string): boolean => { const t = line.trim(); return t.length > 0 && !t.startsWith("#"); };
+
+/** The indent of the first content line — the top mapping's key column (0 for most bodies). */
+function firstContentIndent(lines: string[]): number {
+  for (const l of lines) if (isContentLine(l)) return indentOf(l);
+  return 0;
+}
+
+/** A yamlover plain/quoted key token: bare when it is a safe plain scalar, else double-quoted
+ *  (JSON escapes — the subset the parser reads back). Mirrors how filenames with dots/spaces are
+ *  authored as overlay keys (e.g. `"S0002-9904.pdf":`). */
+export function keyToken(key: string): string {
+  return /^[A-Za-z0-9_][A-Za-z0-9_-]*$/.test(key) ? key : JSON.stringify(key);
+}
+
+/** Line index of `key:` at exactly `indent` within [lo,hi); -1 once the mapping ends (a dedent
+ *  to a shallower content line). Skips deeper lines (a nested value / block scalar). */
+function findKeyLine(lines: string[], lo: number, hi: number, indent: number, key: string): number {
+  const tok = keyToken(key);
+  for (let i = lo; i < hi; i++) {
+    if (!isContentLine(lines[i])) continue;
+    const ind = indentOf(lines[i]);
+    if (ind < indent) return -1; // left the mapping
+    if (ind !== indent) continue; // deeper — a nested value
+    const t = lines[i].trim();
+    if (t === `${key}:` || t.startsWith(`${key}: `) || t === `${tok}:` || t.startsWith(`${tok}: `)) return i;
+  }
+  return -1;
+}
+
+/** Walk `end` back over trailing blank lines, so an insert lands right after the last content. */
+function trimBack(lines: string[], floor: number, end: number): number {
+  let e = end;
+  while (e > floor + 1 && !isContentLine(lines[e - 1])) e--;
+  return e;
+}
+
+/** The end (exclusive) of the block owned by the content starting at `from`, whose own lines sit
+ *  at >= `indent`: the first later content line shallower than `indent`, sans trailing blanks. */
+function blockEnd(lines: string[], from: number, hi: number, indent: number): number {
+  let last = from;
+  for (let i = from; i < hi; i++) {
+    if (!isContentLine(lines[i])) continue;
+    if (indentOf(lines[i]) < indent) return trimBack(lines, last, i);
+    last = i;
+  }
+  return trimBack(lines, last, hi);
+}
+
+interface Region { lo: number; hi: number; indent: number } // a mapping body: child keys at `indent`, within [lo,hi)
+
+/** Descend the mapping-KEY path `within` to the target node's body region, CREATING any missing
+ *  key as an empty block (so a fresh overlay grows the `"file":` → `yamlover-fragments:` →
+ *  `<slug>:` spine on demand). Mutates `lines` in place; returns the region under the last key. */
+function reachBody(lines: string[], within: string[]): Region {
+  let lo = 0;
+  let hi = lines.length;
+  let indent = firstContentIndent(lines);
+  if (lines.length === 1 && lines[0] === "") { lines.length = 0; hi = 0; indent = 0; } // empty file
+
+  for (const key of within) {
+    const L = findKeyLine(lines, lo, hi, indent, key);
+    if (L < 0) {
+      const at = trimBack(lines, lo - 1, hi); // append the new key at the end of the current body
+      lines.splice(at, 0, `${" ".repeat(indent)}${keyToken(key)}:`);
+      lo = at + 1; hi = at + 1; indent += 2; // its (empty) body
+      continue;
+    }
+    const inline = lines[L].slice(indentOf(lines[L])).slice(`${lines[L].trim().split(":")[0]}:`.length);
+    const bodyLo = L + 1;
+    const bodyHi = blockEnd(lines, bodyLo, hi, indent + 1); // anything deeper than the key
+    // the child key column: a deeper content line's indent if the node already has a block body,
+    // else key-indent + 2 (a leaf/inline value gains its first field there — an omni node).
+    let childIndent = indent + 2;
+    for (let i = bodyLo; i < bodyHi; i++) {
+      if (isContentLine(lines[i]) && indentOf(lines[i]) > indent) { childIndent = indentOf(lines[i]); break; }
+    }
+    void inline;
+    lo = bodyLo; hi = bodyHi; indent = childIndent;
+  }
+  return { lo, hi, indent };
+}
+
+/** Start lines of the `- ` items of a sequence whose key sits at `indent` (items at the same
+ *  indent), scanning the region body for the `key:` then its items. */
+function seqItemLines(lines: string[], region: Region, key: string): { keyLine: number; items: number[]; end: number } | null {
+  const keyLine = findKeyLine(lines, region.lo, region.hi, region.indent, key);
+  if (keyLine < 0) return null;
+  const items: number[] = [];
+  let end = keyLine + 1;
+  for (let i = keyLine + 1; i < region.hi; i++) {
+    if (!isContentLine(lines[i])) continue;
+    const ind = indentOf(lines[i]);
+    if (ind < region.indent) break;
+    if (ind === region.indent) {
+      const t = lines[i].trim();
+      if (t === "-" || t.startsWith("- ")) { items.push(i); end = i; continue; }
+      break; // a sibling key at the list indent → the sequence ended
+    }
+    end = i; // deeper — the current item's body
+  }
+  return { keyLine, items, end: trimBack(lines, end, region.hi) };
+}
+
+/** Append one annotation element (rendered at the list indent) to the `yamlover-annotations:`
+ *  sequence of the node addressed by `within`, creating the key (and any missing path) if absent.
+ *  `render(indent)` returns the element's source lines (a `- *…tag` item, or a `- {…}` object). */
+export function appendAnnotation(text: string, within: string[], render: (indent: number) => string[]): string {
+  const lines = text.replace(/\n$/, "").split("\n");
+  const region = reachBody(lines, within);
+  const seq = seqItemLines(lines, region, ANNOTATIONS_KEY);
+  if (!seq) {
+    const at = trimBack(lines, region.lo - 1, region.hi);
+    lines.splice(at, 0, `${" ".repeat(region.indent)}${ANNOTATIONS_KEY}:`, ...render(region.indent));
+  } else {
+    lines.splice(seq.end, 0, ...render(region.indent));
+  }
+  return lines.join("\n") + "\n";
+}
+
+/** Upsert a `<slug>:` entry into the `yamlover-fragments:` mapping of the node addressed by
+ *  `within`, creating the key (and any missing path) if absent. `render(indent)` returns the
+ *  fragment's source lines INCLUDING the `<slug>:` line, at the mapping's child indent. A slug
+ *  that already exists is REPLACED (its whole block). */
+export function upsertFragment(text: string, within: string[], slug: string, render: (indent: number) => string[]): string {
+  const lines = text.replace(/\n$/, "").split("\n");
+  const region = reachBody(lines, within);
+  let fragKey = findKeyLine(lines, region.lo, region.hi, region.indent, FRAGMENTS_KEY);
+  if (fragKey < 0) {
+    const at = trimBack(lines, region.lo - 1, region.hi);
+    lines.splice(at, 0, `${" ".repeat(region.indent)}${FRAGMENTS_KEY}:`);
+    fragKey = at;
+  }
+  const mapIndent = region.indent + 2;
+  const mapBody: Region = { lo: fragKey + 1, hi: blockEnd(lines, fragKey + 1, lines.length, region.indent + 1), indent: mapIndent };
+  const existing = findKeyLine(lines, mapBody.lo, mapBody.hi, mapIndent, slug);
+  if (existing >= 0) {
+    const end = blockEnd(lines, existing + 1, mapBody.hi, mapIndent + 1);
+    lines.splice(existing, end - existing, ...render(mapIndent));
+  } else {
+    const at = trimBack(lines, fragKey, mapBody.hi);
+    lines.splice(at, 0, ...render(mapIndent));
+  }
+  return lines.join("\n") + "\n";
+}
+
+/** Remove an annotation element from the `yamlover-annotations:` of the node at `within` — the
+ *  first `- ` item whose trimmed text matches `predicate`. Returns the text unchanged if none
+ *  matches. The block of a multi-line object item is removed whole. */
+export function removeAnnotation(text: string, within: string[], predicate: (itemText: string) => boolean): string {
+  const lines = text.replace(/\n$/, "").split("\n");
+  const region = reachBody(lines, within);
+  const seq = seqItemLines(lines, region, ANNOTATIONS_KEY);
+  if (!seq) return text;
+  for (let k = 0; k < seq.items.length; k++) {
+    const i = seq.items[k];
+    const itemText = lines[i].trim().replace(/^-\s*/, "");
+    if (!predicate(itemText)) continue;
+    const next = k + 1 < seq.items.length ? seq.items[k + 1] : seq.end;
+    lines.splice(i, next - i);
+    return lines.join("\n") + "\n";
+  }
+  return text;
+}