yamlover 0.3.1 → 0.3.3

package/dist/server.js

@@ -2345,6 +2345,25 @@ async function walkTreeAsync(absDir, opts = {}) {
   }
   return r.value;
 }
+var BUILTIN_TAG_SCHEMA = "type: object\nformat: x-yamlover-tag\nproperties:\n  color:\n    type: string\nadditionalProperties: *:: yamlover: $defs: tag\n";
+var BUILTIN_TAGS_BODY = '!!<*yamlover:$defs:tag>\ncolors: The palette\n  yellow:\n    color: "#f9e2af"\n  green:\n    color: "#a6e3a1"\n  sky:\n    color: "#89dceb"\n  mauve:\n    color: "#cba6f7"\n  pink:\n    color: "#f5c2e7"\n  peach:\n    color: "#fab387"\n';
+var builtinTemplate = null;
+function builtinYamloverGraft() {
+  builtinTemplate ??= {
+    tag: parseYamlover(BUILTIN_TAG_SCHEMA, "$defs/tag").root,
+    tags: parseYamlover(BUILTIN_TAGS_BODY, "tags/.yamlover/body.yamlover").root
+  };
+  const tagCopy = structuredClone(builtinTemplate.tag);
+  const node = {
+    kind: "mapping",
+    array: false,
+    entries: [
+      { key: "$defs", edge: "contain", value: { kind: "mapping", array: false, entries: [{ key: "tag", edge: "contain", value: tagCopy }] } },
+      { key: "tags", edge: "contain", value: structuredClone(builtinTemplate.tags) }
+    ]
+  };
+  return { node, defs: /* @__PURE__ */ new Map([["tag", tagCopy]]) };
+}
 function* walkTreeGen(absDir, opts = {}) {
   const ctx = { root: path.resolve(absDir), opts, files: /* @__PURE__ */ new Map(), count: 0 };
   const root = yield* dirNode(ctx.root, ctx);
@@ -2352,13 +2371,20 @@ function* walkTreeGen(absDir, opts = {}) {
   const defsRoot = findDefsRoot(absDir);
   const defsDir = path.join(defsRoot, "$defs");
   const arrayRoot = root.array || (root.entries?.length ? root.entries.every((e2) => e2.key === null) : false);
-  if (!arrayRoot && fs.existsSync(defsDir) && root.entries && !root.entries.some((e2) => e2.key === "yamlover")) {
-    const shared = [{ key: "$defs", edge: "contain", value: yield* dirNode(defsDir, ctx) }];
-    const tagsDir = path.join(defsRoot, "tags");
-    if (fs.existsSync(tagsDir)) shared.push({ key: "tags", edge: "contain", value: yield* dirNode(tagsDir, ctx) });
-    root.entries.push({ key: "yamlover", edge: "contain", value: { kind: "mapping", entries: shared, array: false } });
+  let builtinDefs;
+  if (!arrayRoot && root.entries && !root.entries.some((e2) => e2.key === "yamlover")) {
+    if (fs.existsSync(defsDir)) {
+      const shared = [{ key: "$defs", edge: "contain", value: yield* dirNode(defsDir, ctx) }];
+      const tagsDir = path.join(defsRoot, "tags");
+      if (fs.existsSync(tagsDir)) shared.push({ key: "tags", edge: "contain", value: yield* dirNode(tagsDir, ctx) });
+      root.entries.push({ key: "yamlover", edge: "contain", value: { kind: "mapping", entries: shared, array: false } });
+    } else {
+      const built = builtinYamloverGraft();
+      root.entries.push({ key: "yamlover", edge: "contain", value: built.node });
+      builtinDefs = built.defs;
+    }
   }
-  applySchemas(root, defsRoot);
+  applySchemas(root, defsRoot, builtinDefs);
   return {
     doc: { root, source: { concrete: "directory", uri: absDir } },
     files: [...ctx.files.values()]
@@ -2572,7 +2598,7 @@ function findDefsRoot(dir) {
     d = up;
   }
 }
-function applySchemas(root, defsRoot) {
+function applySchemas(root, defsRoot, builtinDefs) {
   const cache = /* @__PURE__ */ new Map();
   const loadDef = (name) => {
     if (!cache.has(name)) {
@@ -2580,7 +2606,7 @@ function applySchemas(root, defsRoot) {
       try {
         cache.set(name, parseYamlover(fs.readFileSync(defFile, "utf8"), defFile).root);
       } catch {
-        cache.set(name, null);
+        cache.set(name, builtinDefs?.get(name) ?? null);
       }
     }
     return cache.get(name);

package/package.json

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

package/src/client/App.tsx

@@ -3,7 +3,7 @@ import { fetchInfo, fetchTasks, fetchTree, PasteResult, TaskInfo, TreeNode } fro
 import { Tree } from "./Tree";
 import { TaskStrip } from "./TaskStrip";
 import { NodeView, Format, FORMATS, DEFAULT_FORMAT } from "./NodeView";
-import { rendererName } from "./renderers/registry";
+import { rendererName, tocView } from "./renderers/registry";
 
 const isStandardFormat = (f: Format) => (FORMATS as string[]).includes(f);
 import { crumbs, formatFromUrl, isAncestorPath, pathFromUrl, segsToStr, strToSegs, writeUrl } from "./paths";
@@ -66,6 +66,24 @@ function nextToLoad(tree: TreeNode, current: string): string | null {
   return null;
 }
 
+/** The TOC rows in document (pre-order) order, mirroring exactly what `Tree`
+ *  shows — `tocView` applies the same per-renderer unwrap/filter (chapters
+ *  surface subchapters, dirs show children). Used by Ctrl-PgDn/PgUp to step the
+ *  selection to the neighbouring entry. Covers only the LOADED tree: per-branch
+ *  collapse state lives in each `Tree`'s local `open`, not here — but a branch
+ *  starts open once its children are loaded, so loaded ≈ visible in practice;
+ *  deep unloaded branches simply aren't reachable until expanded (lazy load). */
+function flattenToc(tree: TreeNode | null): string[] {
+  if (!tree) return [];
+  const out: string[] = [];
+  const walk = (n: TreeNode) => {
+    out.push(n.path);
+    for (const c of tocView(n).children) walk(c);
+  };
+  walk(tree);
+  return out;
+}
+
 export function App() {
   const [tree, setTree] = useState<TreeNode | null>(null);
   const [error, setError] = useState<string | null>(null);
@@ -73,6 +91,7 @@ export function App() {
   const [format, setFormat] = useState<Format>(formatFromUrl(DEFAULT_FORMAT) as Format);
   const [rootLabel, setRootLabel] = useState<string>(""); // CLI ROOT (breadcrumb head)
   const [leftWidth, setLeftWidth] = useState<number>(320);
+  const mainRef = useRef<HTMLElement>(null); // RHS pane — focused on TOC click so the keyboard drives the viewer
 
   // The breadcrumb head is the ROOT given on the command line (blank if omitted).
   useEffect(() => {
@@ -259,6 +278,39 @@ export function App() {
     [format, tree],
   );
 
+  // Selecting a TOC row navigates AND hands keyboard focus to the RHS pane, so
+  // Ctrl-PgDn/PgUp (and plain scroll keys) drive the viewer right after a click.
+  // Scoped to the tree — crumbs and in-content links keep plain `navigate`.
+  const selectFromToc = useCallback(
+    (p: string) => {
+      navigate(p);
+      mainRef.current?.focus();
+    },
+    [navigate],
+  );
+
+  // Ctrl/Alt + Down / Up step the selection to the next / previous TOC entry in
+  // document order (Alt as well as Ctrl because Ctrl+Up/Down is taken by macOS
+  // Mission Control). Attached once; reads live state through refs so the listener
+  // stays stable. `navigate` reveals + scrolls the new row (Tree's selected effect).
+  const navigateRef = useRef(navigate);
+  navigateRef.current = navigate;
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (!(e.ctrlKey || e.altKey) || (e.key !== "ArrowDown" && e.key !== "ArrowUp")) return;
+      const t = e.target as HTMLElement | null;
+      if (t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName))) return;
+      const order = flattenToc(treeRef.current);
+      const i = order.indexOf(currentRef.current);
+      if (i < 0) return; // current not in the loaded TOC yet — nothing to step from
+      const next = Math.min(Math.max(i + (e.key === "ArrowDown" ? 1 : -1), 0), order.length - 1);
+      e.preventDefault();
+      if (next !== i) navigateRef.current(order[next]);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
   const changeFormat = useCallback(
     (f: Format) => {
       writeUrl(current, f, true);
@@ -324,7 +376,7 @@ export function App() {
         <nav className="crumbs">
           {crumbs(current, rootLabel).map((c, i) => (
             <span key={c.path}>
-              {i > 0 && <span className="crumb-sep">/</span>}
+              {i > 0 && <span className="crumb-sep">:</span>}
               <a
                 className="crumb"
                 href={c.path}
@@ -353,7 +405,7 @@ export function App() {
             }
             if (error) return <div className="error">{error}</div>;
             if (!tree) return <div className="loading">loading…</div>;
-            return <Tree node={tree} current={current} onSelect={navigate} onLoadChildren={loadChildren} />;
+            return <Tree node={tree} current={current} onSelect={selectFromToc} onLoadChildren={loadChildren} />;
           })()}
         </aside>
         <div
@@ -363,7 +415,7 @@ export function App() {
             document.body.style.userSelect = "none";
           }}
         />
-        <main className="pane right">
+        <main className="pane right" ref={mainRef} tabIndex={-1}>
           <NodeView path={current} format={format} refreshSignal={refreshSignal} onFormat={changeFormat} onNavigate={navigate} onContentChanged={onContentChanged} onOpenUploaded={onOpenUploaded} />
         </main>
       </div>

package/src/client/paths.ts

@@ -25,6 +25,14 @@ export function strToSegs(str: string): Seg[] {
   return out;
 }
 
+/** Canonical key for cross-SCOPE comparison: collapse the colon scope ladder so a
+ *  project ref (`::yamlover:…`), a document ref (`:yamlover:…`), and a server-echoed
+ *  `:`-form path all compare equal. The ladder colons are not tokens (PATH_TOKEN), so
+ *  re-emitting drops them; keys are normalized through one decode→encode pass. */
+export function canonPath(p: string): string {
+  return segsToStr(strToSegs(p));
+}
+
 function safeDecode(s: string): string {
   try {
     return decodeURIComponent(s);
@@ -79,6 +87,25 @@ export function formatFromUrl(fallback: string): string {
   return new URLSearchParams(window.location.search).get("format") || fallback;
 }
 
+/** The current page from the URL's `?page=` (1-based). 1 when absent, ≤1, or not an integer —
+ *  used by paged viewers (PDF/DjVu) to restore where the reader left off. */
+export function pageFromUrl(): number {
+  const n = Number(new URLSearchParams(window.location.search).get("page"));
+  return Number.isInteger(n) && n > 1 ? n : 1;
+}
+
+/** Record the current page in `?page=` via replaceState — preserving every other param, and
+ *  DROPPING the param at page 1 (the implicit default). This does NOT remount the renderer (only
+ *  path/format/refreshSignal do), so a paged viewer can update it freely while scrolling. */
+export function writePageToUrl(n: number): void {
+  const params = new URLSearchParams(window.location.search);
+  if (n > 1) params.set("page", String(n));
+  else params.delete("page");
+  const qs = params.toString();
+  const url = window.location.pathname + (qs ? "?" + qs : "");
+  if (url !== window.location.pathname + window.location.search) window.history.replaceState({}, "", url);
+}
+
 /** Write the JSON path (canonical colon form, converted to the slash-transport URL)
  *  plus `?format=` into the URL. Path navigation pushes a history entry; switching
  *  format replaces. Any other query params already present are kept (e.g. a renderer's
@@ -86,6 +113,9 @@ export function formatFromUrl(fallback: string): string {
 export function writeUrl(path: string, format: string, replace = false): void {
   const params = new URLSearchParams(window.location.search);
   params.set("format", format);
+  // `?page=` is node-specific: a format switch (replace) keeps it, but navigating to another node
+  // (push) must not carry the old node's page over — drop it there.
+  if (!replace) params.delete("page");
   const url = `${urlOfPath(path || ":")}?${params.toString()}`;
   if (url === window.location.pathname + window.location.search) return;
   if (replace) window.history.replaceState({}, "", url);

package/src/client/renderers/annotate.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState, type ReactNode } from "react";
 import { Annotation, TagRef, createTag, fetchAnnotations, fetchNode, saveAnnotation, deleteAnnotation } from "../api";
 import { TAG_FORMAT, explicitColor, resolveTagColor, tagFields } from "./tag";
-import { strToSegs } from "../paths";
+import { canonPath, strToSegs } from "../paths";
 import { touchesYamlover, useDiffBump } from "../live";
 
 /**
@@ -30,12 +30,12 @@ import { touchesYamlover, useDiffBump } from "../live";
 // fetches the real `/yamlover/tags/colors` nodes once per session (useColorTags) so a project
 // that re-themes them wins; the paths and hexes here mirror yamlover/tags/.yamlover/body.yamlover.
 export const COLOR_TAGS: TagRef[] = [
-  { path: ":yamlover:tags:colors:yellow", name: "yellow", color: "#f9e2af" },
-  { path: ":yamlover:tags:colors:green", name: "green", color: "#a6e3a1" },
-  { path: ":yamlover:tags:colors:sky", name: "sky", color: "#89dceb" },
-  { path: ":yamlover:tags:colors:mauve", name: "mauve", color: "#cba6f7" },
-  { path: ":yamlover:tags:colors:pink", name: "pink", color: "#f5c2e7" },
-  { path: ":yamlover:tags:colors:peach", name: "peach", color: "#fab387" },
+  { path: "::yamlover:tags:colors:yellow", name: "yellow", color: "#f9e2af" },
+  { path: "::yamlover:tags:colors:green", name: "green", color: "#a6e3a1" },
+  { path: "::yamlover:tags:colors:sky", name: "sky", color: "#89dceb" },
+  { path: "::yamlover:tags:colors:mauve", name: "mauve", color: "#cba6f7" },
+  { path: "::yamlover:tags:colors:pink", name: "pink", color: "#f5c2e7" },
+  { path: "::yamlover:tags:colors:peach", name: "peach", color: "#fab387" },
 ];
 export const DEFAULT_TAG = COLOR_TAGS[0];
 export const DEFAULT_COLOR = DEFAULT_TAG.color!;
@@ -68,12 +68,15 @@ let colorTagsPromise: Promise<TagRef[]> | null = null;
 export function useColorTags(): TagRef[] {
   const [tags, setTags] = useState<TagRef[]>(COLOR_TAGS);
   useEffect(() => {
-    colorTagsPromise ??= fetchNode(":yamlover:tags:colors", 2)
+    colorTagsPromise ??= fetchNode("::yamlover:tags:colors", 2)
       .then((n) => {
         const out: TagRef[] = [];
         for (const [name, child] of tagFields(n.value)) {
           const color = explicitColor(child);
-          if (color) out.push({ path: `${n.path}/${encodeURIComponent(name)}`, name, color });
+          // PROJECT-scope ref pinned to `::yamlover:tags:colors:<name>` — NOT derived from
+          // `n.path` (the API echoes that in `:`-form, which would mismatch COLOR_TAGS and
+          // resurrect the ghost badge); and `:` not `/` (the pre-SEPARATOR separator bug).
+          if (color) out.push({ path: `::yamlover:tags:colors:${encodeURIComponent(name)}`, name, color });
         }
         return out.length ? out : COLOR_TAGS;
       })
@@ -113,7 +116,7 @@ export function recentTags(): TagRef[] {
 }
 
 function rememberRecent(t: TagRef): void {
-  if (t.path.startsWith(":yamlover:tags:colors:")) return; // the swatch row already shows these
+  if (canonPath(t.path).startsWith(":yamlover:tags:colors:")) return; // the swatch row already shows these
   const next = [t, ...recentTags().filter((r) => r.path !== t.path)].slice(0, 6);
   localStorage.setItem(RECENT_KEY, JSON.stringify(next));
 }
@@ -165,7 +168,7 @@ export function useAnnotations(path: string, bump = 0): Annotation[] {
  *  round-trip lands. */
 export interface MaterialAnnotations {
   annotations: Annotation[];
-  create: (selector: Record<string, unknown> | null, tag: TagRef) => void;
+  create: (selector: Record<string, unknown> | null, tag: TagRef, opts?: { silent?: boolean }) => void;
   remove: (annPath?: string) => void;
   retag: (ann: Annotation, tag: TagRef) => void;
 }
@@ -189,12 +192,18 @@ export function useMaterialAnnotations(path: string): MaterialAnnotations {
   }, [fetched]);
 
   const refresh = () => setBump((b) => b + 1);
-  const create = (selector: Record<string, unknown> | null, tag: TagRef) => {
+  const create = (selector: Record<string, unknown> | null, tag: TagRef, opts?: { silent?: boolean }) => {
     const entry = { path: "(pending)", selector: selector ?? undefined, tag } as Annotation;
     setOptimistic((o) => [...o, entry]);
     createAnnotation(path, selector, tag)
       .then(refresh)
-      .catch((e) => { setOptimistic((o) => o.filter((x) => x !== entry)); window.alert("save failed: " + (e as Error).message); }); // roll back the unsaved mark
+      .catch((e) => {
+        setOptimistic((o) => o.filter((x) => x !== entry)); // roll back the unsaved mark
+        // An IMPLICIT save (clicking away with the pre-selected tag) is best-effort — e.g. the
+        // default tag may not exist in this tree — so it rolls back QUIETLY. Only an explicit
+        // pick (a swatch/badge/✓) reports the failure.
+        if (!opts?.silent) window.alert("save failed: " + (e as Error).message);
+      });
   };
   const remove = (annPath?: string) => {
     if (!annPath || annPath === "(pending)") return;
@@ -228,7 +237,7 @@ function tagNameOf(path: string): string {
 
 /** The floating tag picker — color-tag swatches, recent named-tag badges, a tag-path input, plus
  *  action buttons. Mode decides which buttons show (the hook wires what each does): `create` gets
- *  ✓ confirm + optional ⧉ copy + 🗑 discard; `edit` gets just 🗑 delete (picking a tag re-tags).
+ *  ✓ confirm + optional ⧉ copy + 🗑 discard; `edit` gets ✓ close + 🗑 delete (picking a tag re-tags).
  *  `position: fixed`, so x/y are viewport coords. */
 export function AnnotationMenu({
   x, y, tag, mode, onPick, onConfirm, onCopy, onTrash, menuRef,
@@ -251,10 +260,14 @@ export function AnnotationMenu({
     return () => { on = false; };
   }, []);
 
+  // Compare tag paths on a CANONICAL key — a palette ref is project-scope (`::yamlover:…`)
+  // while a selected/edited tag may arrive `:`-form (the API echoes paths in `:`-form, and
+  // older localStorage holds `:`-form); raw `===` would miss the match and duplicate the tag.
+  const same = (a: string, b: string) => canonPath(a) === canonPath(b);
   // The badge row must always include THE tag this menu is about (`sel`-framed, like the
   // selected color swatch) — which tag is assigned/pre-selected must be visible at a glance,
-  // even when it has aged out of the recents.
-  const badges = colorTags.some((c) => c.path === tag.path) || recents.some((r) => r.path === tag.path)
+  // even when it has aged out of the recents. A PALETTE tag is shown as a swatch, not a badge.
+  const badges = colorTags.some((c) => same(c.path, tag.path)) || recents.some((r) => same(r.path, tag.path))
     ? recents
     : [tag, ...recents];
 
@@ -288,14 +301,14 @@ export function AnnotationMenu({
           <button
             key={t.path}
             type="button"
-            className={"annotate-swatch" + (t.path === tag.path ? " sel" : "")}
+            className={"annotate-swatch" + (same(t.path, tag.path) ? " sel" : "")}
             style={{ background: resolveTagColor(t) }}
             title={`${verb} ${t.name}`}
             onClick={() => onPick(t)}
           />
         ))}
       </div>
-      {onConfirm && <button type="button" className="annotate-tool ok" title={`${verb} ${tag.name} (keep the mark)`} onClick={onConfirm}>✓</button>}
+      {onConfirm && <button type="button" className="annotate-tool ok" title={mode === "edit" ? "close (keep this annotation)" : `${verb} ${tag.name} (keep the mark)`} onClick={onConfirm}>✓</button>}
       {onCopy && <button type="button" className="annotate-tool" title="copy text to clipboard (don't annotate)" onClick={onCopy}>⧉</button>}
       <button type="button" className="annotate-tool danger" title={mode === "edit" ? "delete this annotation" : "discard (don't annotate)"} onClick={onTrash}>🗑</button>
       {badges.length > 0 && (
@@ -303,7 +316,7 @@ export function AnnotationMenu({
           {badges.map((t) => (
             // the frame is a WRAPPER: filter applies before clip-path on the same element, so a
             // ring drawn on the clipped .tagtag itself would be clipped away with it (styles.css)
-            <span key={t.path} className={"tagframe" + (t.path === tag.path ? " sel" : "")}>
+            <span key={t.path} className={"tagframe" + (same(t.path, tag.path) ? " sel" : "")}>
               <button
                 type="button"
                 className="tagtag"
@@ -355,7 +368,7 @@ export function useAnnotationMenu(a: MaterialAnnotations): {
   const openEdit = (ann: Annotation, screen: { x: number; y: number }) =>
     setMenu({ mode: "edit", ann, x: screen.x, y: screen.y });
 
-  const commitCreate = (t: TagRef, m: MenuState) => { if (m.mode !== "create") return; setTag(t); a.create(m.selector, t); close(); };
+  const commitCreate = (t: TagRef, m: MenuState, silent = false) => { if (m.mode !== "create") return; setTag(t); a.create(m.selector, t, { silent }); close(); };
   const commitRetag = (t: TagRef, m: MenuState) => { if (m.mode !== "edit") return; setTag(t); a.retag(m.ann, t); close(); };
 
   // Outside-click: a create commits with the pre-selected tag (default keeps the mark); an edit closes.
@@ -363,7 +376,7 @@ export function useAnnotationMenu(a: MaterialAnnotations): {
     if (!menu) return;
     const onDown = (e: MouseEvent) => {
       if (menuRef.current?.contains(e.target as Node)) return;
-      if (menu.mode === "create") commitCreate(tag, menu);
+      if (menu.mode === "create") commitCreate(tag, menu, true); // implicit → best-effort, no error popup
       else close();
     };
     document.addEventListener("mousedown", onDown);
@@ -387,6 +400,7 @@ export function useAnnotationMenu(a: MaterialAnnotations): {
       <AnnotationMenu
         menuRef={menuRef} x={menu.x} y={menu.y} tag={menu.ann.tag ?? DEFAULT_TAG} mode="edit"
         onPick={(t) => commitRetag(t, menu)}
+        onConfirm={close} // ✓ closes the popup without deleting or re-tagging
         onTrash={() => { a.remove(menu.ann.path); close(); }}
       />
     );