yamlover 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yamlover",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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(() => {
@@ -120,7 +139,7 @@ export function App() {
     const n = findNode(tree, current);
     if (!n) return; // not loaded along the path yet — wait for the next pass
     resolvedLanding.current = true;
-    const rn = rendererName(n.type, n.format, n.concrete);
+    const rn = rendererName(n, n.concrete);
     if (rn) {
       setFormat(rn);
       writeUrl(current, rn, true);
@@ -249,7 +268,7 @@ export function App() {
       const target = tree ? findNode(tree, p) : null;
       let f: Format = format;
       if (target) {
-        const rn = rendererName(target.type, target.format, target.concrete);
+        const rn = rendererName(target, target.concrete);
         f = rn ?? (isStandardFormat(format) ? format : DEFAULT_FORMAT);
       }
       writeUrl(p, f, false);
@@ -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);
@@ -288,7 +340,7 @@ export function App() {
         const sub = await fetchTree(dir, INITIAL_DEPTH);
         setTree((t) => (t ? replaceChildren(t, dir, sub.children) : t));
         const fileNode = sub.children.find((c) => c.path === result.path);
-        const f: Format = (fileNode ? rendererName(fileNode.type, fileNode.format, fileNode.concrete) : null) ?? DEFAULT_FORMAT;
+        const f: Format = (fileNode ? rendererName(fileNode, fileNode.concrete) : null) ?? DEFAULT_FORMAT;
         writeUrl(result.path, f, false);
         setCurrent(result.path);
         setFormat(f);
@@ -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/api.ts

@@ -5,6 +5,9 @@ export interface TreeNode {
   label: string;
   type: string;
   format: string | null;
+  valueType?: string | null; // renderer dispatch facets (TYPES.md §9)
+  hasKeyed?: boolean;
+  hasOrdinal?: boolean;
   concrete: string | null; // how it is stored; `dir` → a plain-folder icon
   hasChildren: boolean;
   children: TreeNode[];
@@ -13,7 +16,10 @@ export interface TreeNode {
 export interface NodeJson {
   path: string;
   type: string;
-  format?: string | null; // schema `format`; with `type` it keys the renderer
+  format?: string | null; // schema `format`; with the facets it keys the renderer (TYPES.md §9)
+  valueType?: string | null; // the scalar self-VALUE's type (null|boolean|integer|number|string|binary), or null
+  hasKeyed?: boolean; // owns ≥1 keyed element
+  hasOrdinal?: boolean; // owns ≥1 ordinal (keyless) element
   concrete: string | null;
   documentPath?: string; // the document (nearest yamlover entity) this node is in —
                          // the anchor a document-relative (`/…`) link resolves against
@@ -90,15 +96,18 @@ export interface TagRef {
   color: string | null;
 }
 
-/** An annotation of a material — ONE TAG APPLICATION: a marked segment (or the whole node, when
- *  `selector` is absent) tagged by `tag`, with an optional per-application comment. `tag` is
- *  null only for legacy annotations saved before tags carried the color. */
+/** An annotation of a material — ONE TAG APPLICATION (ANNOTATIONS.md): the whole node, or a
+ *  fragment within it (then `selector` carries that fragment's region and `fragmentSlug` its
+ *  key, and `imageUrl` its crop), tagged by `tag` with optional `description` / `params`. */
 export interface Annotation {
-  path: string; // the annotation's own node path
   tag?: TagRef | null;
   selector?: { type?: string; exact?: string; prefix?: string; suffix?: string; [k: string]: unknown };
+  fragmentSlug?: string; // set when the tag is on a fragment (the region) rather than the whole node
+  imageUrl?: string; // an image-like fragment's crop (a /api/blob URL)
   description?: string;
+  params?: Record<string, unknown>;
   created?: string;
+  path?: string; // a transient client marker only ("(preview)"/"(pending)"); annotations have no node path
 }
 
 /** The annotations whose `target` is the material at `path` (the engine's reverse link). */
@@ -112,16 +121,32 @@ export function fetchTagged(path: string): Promise<unknown[]> {
   return getJson<unknown[]>(`/api/tagged?path=${encodeURIComponent(path)}`);
 }
 
-/** Save a new annotation — apply the tag at `tag` to the material at `target` (JSON paths),
- *  optionally narrowed to `selector` and commented by `description`; returns the created path. */
-export function saveAnnotation(a: { target: string; tag: string; selector?: Record<string, unknown>; description?: string }): Promise<{ path: string }> {
-  return fetch("/api/annotate", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(a) }).then(
-    async (res) => {
-      const body = await res.json();
-      if (!res.ok) throw new Error((body && body.error) || `HTTP ${res.status}`);
-      return body as { path: string };
-    },
-  );
+/** Evaluate a colon-grammar QUERY (QUERY.md / engine `query` op) at `at` (default: the root `:`),
+ *  returning the matched node paths in canonical colon form. A malformed query rejects (the
+ *  server answers 400). Reused by the tag-picker typeahead and, later, by find-usages. */
+export function query(q: string, at = ":"): Promise<string[]> {
+  const params = new URLSearchParams({ q, path: at });
+  return getJson<{ results: string[] }>(`/api/query?${params}`).then((r) => r.results);
+}
+
+async function postJson<T>(url: string, body: unknown): Promise<T> {
+  const res = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+  const json = await res.json();
+  if (!res.ok) throw new Error((json && json.error) || `HTTP ${res.status}`);
+  return json as T;
+}
+
+/** Create a FRAGMENT — a marked region in the node at `target` (ANNOTATIONS.md). Returns its slug
+ *  and full node path, which is then the `target` for {@link annotate}. `imageBase64` is an
+ *  optional PNG crop for image-like selections. */
+export function createFragment(target: string, selector: Record<string, unknown>, imageBase64?: string): Promise<{ slug: string; fragmentPath: string }> {
+  return postJson("/api/fragment", { target, selector, ...(imageBase64 ? { imageBase64 } : {}) });
+}
+
+/** Apply the tag at `tag` to the node at `target` (a whole node OR a fragment path) — appends to
+ *  the target's `yamlover-annotations`. `description`/`params` make it a parametrized annotation. */
+export function annotate(a: { target: string; tag: string; description?: string; params?: Record<string, unknown> }): Promise<{ ok: true }> {
+  return postJson("/api/annotate", a);
 }
 
 /** Create a named tag at the project's default tags location (settings.yamlover; `/tags` by
@@ -178,9 +203,11 @@ export function pasteRich(target: string, rich: unknown): Promise<PasteResult> {
   return postPaste({ path: target, rich });
 }
 
-/** Delete the annotation at its node path (a standalone `<…>.yamlover` file, any directory). */
-export function deleteAnnotation(path: string): Promise<void> {
-  return fetch(`/api/annotate?path=${encodeURIComponent(path)}`, { method: "DELETE" }).then(async (res) => {
+/** Remove the application of `tag` from the node at `target` (a whole node OR a fragment path) —
+ *  splices the matching element out of its `yamlover-annotations`. */
+export function deleteAnnotation(target: string, tag: string): Promise<void> {
+  const q = new URLSearchParams({ target, tag });
+  return fetch(`/api/annotate?${q}`, { method: "DELETE" }).then(async (res) => {
     if (!res.ok) throw new Error(((await res.json().catch(() => null))?.error) || `HTTP ${res.status}`);
   });
 }

package/src/client/render.tsx

@@ -15,19 +15,22 @@ import { ReactNode } from "react";
 const LINK_KEY = "$yamloverLink";
 const BINARY_KEY = "$yamloverBinary";
 const REF_KEY = "$yamloverRef";
-// An omni/mix node (a `!!omni` self-value + fields, or a `!!mix` of items + fields) arrives as
+// An omni/mix node (a `!!var` self-value + fields, or a `!!mix` of items + fields) arrives as
 // `{ [MIXED_KEY]: {kind, value?, entries:[{key,value}]} }`, rendered in yamlover as a leading
 // scalar (omni) then each entry positional (`- v`, key=null) or keyed (`k: v`).
 const MIXED_KEY = "$yamloverMixed";
 
 export interface Link {
   kind: "object" | "array" | "scalar" | "binary" | "omni" | "mix";
-  type?: string; // the target's JSON-Schema type; with `format`, the routing key
+  type?: string; // the target's JSON-Schema type; with the facets, the routing key
   path: string;
   title?: string; // the target's schema title, when set (used as a link label)
   count?: number;
   size?: number;
   format?: string | null;
+  valueType?: string | null; // renderer dispatch facets (TYPES.md §9) — carried so a chunk routes correctly
+  hasKeyed?: boolean;
+  hasOrdinal?: boolean;
   value?: unknown; // for a link to a scalar: its value, shown as the label
   color?: string | null; // for a link to a pure color tag: its explicit color (badges)
   concrete?: string | null; // how the target is stored; `dir`/`yamlover` → a folder icon
@@ -66,6 +69,16 @@ const asBinary = (v: unknown) => asSingle<BinaryPayload>(v, BINARY_KEY);
 const asRef = (v: unknown) => asSingle<Ref>(v, REF_KEY);
 const asMixed = (v: unknown) => asSingle<Mixed>(v, MIXED_KEY);
 
+/** The scalar SELF-VALUE a string/scalar renderer should show. An OMNI node (a scalar that also
+ *  carries fields — e.g. a markdown doc that gained `yamlover-annotations` keys) projects its page
+ *  `value` as a `$yamloverMixed` marker, so peel it to the self-value; a plain scalar passes
+ *  through. Pairs with the facet-tolerant dispatch (TYPES.md §9): routing keeps an annotated string
+ *  on its renderer, and this hands that renderer the string — not the marker object. */
+export function scalarValue(v: unknown): unknown {
+  const m = asMixed(v);
+  return m && m.kind === "omni" ? m.value : v;
+}
+
 type Syntax = "yaml" | "json";
 
 /**
@@ -197,7 +210,7 @@ function emitYaml(value: unknown, indent: number, out: ReactNode[], kc: KC, nav:
   const mixed = asMixed(value);
   if (mixed) {
     const pad = " ".repeat(indent);
-    // omni: the node's own scalar value on its own line first (`!!omni 5` → `5`)
+    // omni: the node's own scalar value on its own line first (`!!var 5` → `5`)
     if (mixed.kind === "omni") out.push(pad, scalarNode(mixed.value, "yaml", kc), "\n");
     for (const e of mixed.entries) {
       if (e.key === null) {

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 { Annotation, TagRef, createTag, fetchAnnotations, fetchNode, query, createFragment, annotate, deleteAnnotation } from "../api";
 import { TAG_FORMAT, explicitColor, resolveTagColor, tagFields } from "./tag";
-import { canonPath, strToSegs } from "../paths";
+import { canonPath, displayPath, strToSegs } from "../paths";
 import { touchesYamlover, useDiffBump } from "../live";
 
 /**
@@ -57,10 +57,10 @@ function annKey(a: Annotation): string {
 /** Whether an annotation can be edited/deleted here — any STANDALONE annotation file (its node
  *  path is the `.yamlover` file itself), wherever it lives in the tree: annotations are graph
  *  nodes, not residents of a fixed folder, so one moved to another directory stays editable.
- *  Excludes the optimistic `(pending)` placeholders and "frozen" annotations authored inline in
- *  shared documents (which the server can't delete without editing that document). */
+ *  Every embedded annotation (one with a resolved tag) is editable — re-tag/delete just edits its
+ *  host body. Transient markers (a `(preview)`/`(pending)` placeholder) are not. */
 export function editable(a: Annotation): boolean {
-  return typeof a.path === "string" && a.path.endsWith(".yamlover");
+  return !!a.tag && a.path !== "(preview)" && a.path !== "(pending)";
 }
 
 // The color tags as indexed (fetched once per session; the constant covers offline/legacy roots).
@@ -88,6 +88,41 @@ export function useColorTags(): TagRef[] {
   return tags;
 }
 
+// Enumerate every NAMED tag in the project for the picker typeahead: a document-root recursive
+// descent, format-filtered (QUERY.md "all tag nodes"). Document-root scope finds tags wherever
+// `settings.tags.location` puts them — the client need not know that path. The grafted COLOR
+// palette lives off the document root (link scope `::yamlover:…`) so it is naturally absent;
+// the defensive filter below also drops any color tag a project re-themes in-tree (those are the
+// swatch row, not the suggestion list).
+const TAG_QUERY = ": ...: !!<format: x-yamlover-tag>";
+
+function indexToRefs(paths: string[]): TagRef[] {
+  const seen = new Set<string>();
+  const out: TagRef[] = [];
+  for (const p of paths) {
+    const cp = canonPath(p);
+    if (cp.startsWith(":yamlover:tags:colors:") || seen.has(cp)) continue; // colors → swatch row
+    seen.add(cp);
+    out.push({ path: p, name: tagNameOf(p), color: null }); // named tag → hue derived from name
+  }
+  return out;
+}
+
+/** The project's named tags, enumerated once and re-enumerated when a `.yamlover` source changes
+ *  (so a freshly created tag appears). Feeds the picker's typeahead suggestions. */
+export function useTagIndex(): TagRef[] {
+  const [tags, setTags] = useState<TagRef[]>([]);
+  const bump = useDiffBump(touchesYamlover);
+  useEffect(() => {
+    let cancelled = false;
+    query(TAG_QUERY)
+      .then((paths) => { if (!cancelled) setTags(indexToRefs(paths)); })
+      .catch(() => { if (!cancelled) setTags([]); });
+    return () => { cancelled = true; };
+  }, [bump]);
+  return tags;
+}
+
 /** The remembered last-applied tag (persisted in localStorage) + a setter that persists it and
  *  files a NAMED tag among the recents (color tags live in the swatch row already). */
 export function useAnnotationTag(): [TagRef, (t: TagRef) => void] {
@@ -140,10 +175,24 @@ function pruneRememberedTags(): Promise<TagRef[]> {
   });
 }
 
-/** Apply `tag` to the material at `target`, narrowed to `selector` when given (null = the whole
- *  node); resolves when persisted. */
-export function createAnnotation(target: string, selector: Record<string, unknown> | null, tag: TagRef): Promise<unknown> {
-  return saveAnnotation({ target, tag: tag.path, ...(selector ? { selector } : {}) });
+/** Apply `tag` to the material at `target`. With a `selector`, first create a FRAGMENT (the
+ *  region, plus an optional PNG crop) and tag THAT; without one, tag the whole node. */
+export async function createAnnotation(
+  target: string,
+  selector: Record<string, unknown> | null,
+  tag: TagRef,
+  imageBase64?: string,
+): Promise<unknown> {
+  if (!selector) return annotate({ target, tag: tag.path });
+  const { fragmentPath } = await createFragment(target, selector, imageBase64);
+  return annotate({ target: fragmentPath, tag: tag.path });
+}
+
+/** The host node path that carries a tag application: the material itself, or — when the
+ *  annotation marks a region — that fragment's node path (`…:yamlover-fragments:<slug>`). */
+function annotationTarget(materialPath: string, ann: Annotation): string {
+  if (!ann.fragmentSlug) return materialPath;
+  return (materialPath === ":" ? "" : materialPath) + ":yamlover-fragments:" + ann.fragmentSlug;
 }
 
 /** Read-only fetch of a material's annotations; `bump` (a changing number) forces a refetch.
@@ -168,8 +217,8 @@ export function useAnnotations(path: string, bump = 0): Annotation[] {
  *  round-trip lands. */
 export interface MaterialAnnotations {
   annotations: Annotation[];
-  create: (selector: Record<string, unknown> | null, tag: TagRef, opts?: { silent?: boolean }) => void;
-  remove: (annPath?: string) => void;
+  create: (selector: Record<string, unknown> | null, tag: TagRef, opts?: { silent?: boolean; imageBase64?: string }) => void;
+  remove: (ann: Annotation) => void;
   retag: (ann: Annotation, tag: TagRef) => void;
 }
 
@@ -180,49 +229,54 @@ export function useMaterialAnnotations(path: string): MaterialAnnotations {
   const [bump, setBump] = useState(0);
   const fetched = useAnnotations(path, bump);
   const [optimistic, setOptimistic] = useState<Annotation[]>([]); // created, not yet in `fetched`
-  const [deleted, setDeleted] = useState<Set<string>>(new Set());  // paths hidden, not yet dropped
+  const [deleted, setDeleted] = useState<Set<string>>(new Set());  // annKeys hidden, not yet dropped
 
-  // Reconcile when the server list refreshes: drop optimistic creations it now holds, and keep a
-  // path "deleted" only while the server still lists it (so a re-tag's old copy can't flash back).
+  // Reconcile when the server list refreshes: drop optimistic creations it now holds, and keep an
+  // annotation "deleted" only while the server still lists it (so a re-tag's old copy can't flash
+  // back). Identity is annKey (selector + tag) — annotations carry no node path of their own.
   useEffect(() => {
     const keys = new Set(fetched.map(annKey));
     setOptimistic((o) => o.filter((a) => !keys.has(annKey(a))));
-    const present = new Set(fetched.map((a) => a.path).filter(Boolean) as string[]);
-    setDeleted((d) => new Set([...d].filter((p) => present.has(p))));
+    setDeleted((d) => new Set([...d].filter((k) => keys.has(k))));
   }, [fetched]);
 
   const refresh = () => setBump((b) => b + 1);
-  const create = (selector: Record<string, unknown> | null, tag: TagRef, opts?: { silent?: boolean }) => {
+  const rollback = (entry: Annotation, e: unknown, silent?: boolean) => {
+    setOptimistic((o) => o.filter((x) => x !== entry));
+    if (!silent) window.alert("save failed: " + (e as Error).message);
+  };
+  const create = (selector: Record<string, unknown> | null, tag: TagRef, opts?: { silent?: boolean; imageBase64?: string }) => {
     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)); // 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);
-      });
+    // 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 (opts.silent).
+    createAnnotation(path, selector, tag, opts?.imageBase64).then(refresh).catch((e) => rollback(entry, e, opts?.silent));
   };
-  const remove = (annPath?: string) => {
-    if (!annPath || annPath === "(pending)") return;
-    setDeleted((d) => new Set(d).add(annPath));
-    deleteAnnotation(annPath)
+  const remove = (ann: Annotation) => {
+    if (!ann?.tag || ann.path === "(pending)") return;
+    const key = annKey(ann);
+    setDeleted((d) => new Set(d).add(key));
+    deleteAnnotation(annotationTarget(path, ann), ann.tag.path)
       .then(refresh)
-      .catch((e) => { setDeleted((d) => { const n = new Set(d); n.delete(annPath); return n; }); window.alert("delete failed: " + (e as Error).message); }); // un-hide on failure
+      .catch((e) => { setDeleted((d) => { const n = new Set(d); n.delete(key); return n; }); window.alert("delete failed: " + (e as Error).message); }); // un-hide on failure
   };
   const retag = (ann: Annotation, tag: TagRef) => {
-    remove(ann.path); // hide + delete the old application
-    create(ann.selector ?? null, tag); // show + save the new one
+    remove(ann); // hide + delete the old application
+    if (ann.fragmentSlug) {
+      // re-tag the SAME fragment (no new region) — annotate its existing node with the new tag
+      const entry = { path: "(pending)", selector: ann.selector, fragmentSlug: ann.fragmentSlug, tag } as Annotation;
+      setOptimistic((o) => [...o, entry]);
+      annotate({ target: annotationTarget(path, ann), tag: tag.path }).then(refresh).catch((e) => rollback(entry, e));
+    } else {
+      create(null, tag); // whole-node re-tag
+    }
   };
 
   const seen = new Set<string>();
   const annotations: Annotation[] = [];
   for (const a of [...optimistic, ...fetched]) {
-    if (a.path && deleted.has(a.path)) continue;
     const k = annKey(a);
-    if (seen.has(k)) continue;
+    if (deleted.has(k) || seen.has(k)) continue;
     seen.add(k);
     annotations.push(a);
   }
@@ -235,6 +289,16 @@ function tagNameOf(path: string): string {
   return segs.length ? String(segs[segs.length - 1]) : path;
 }
 
+/** Typeahead rank for a tag against the lowercased query `q` (lower is better): an exact name,
+ *  then a name prefix, then a name substring, then matched only via the full path. */
+function rankTag(t: TagRef, q: string): number {
+  const n = t.name.toLowerCase();
+  if (n === q) return 0;
+  if (n.startsWith(q)) return 1;
+  if (n.includes(q)) return 2;
+  return 3;
+}
+
 /** 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 ✓ close + 🗑 delete (picking a tag re-tags).
@@ -247,8 +311,10 @@ export function AnnotationMenu({
   menuRef?: React.Ref<HTMLDivElement>;
 }) {
   const colorTags = useColorTags();
+  const tagIndex = useTagIndex(); // all named tags, for the typeahead
   const [recents, setRecents] = useState(recentTags); // shown at once; pruned against the server
   const [path, setPath] = useState("");
+  const [hi, setHi] = useState(-1); // highlighted suggestion (-1 = none)
   const [busy, setBusy] = useState(false); // a lookup/create round-trip is in flight
   const verb = mode === "edit" ? "re-tag" : "tag";
 
@@ -271,12 +337,31 @@ export function AnnotationMenu({
     ? recents
     : [tag, ...recents];
 
+  // Typeahead suggestions: substring match on the typed text against the tag name OR its full
+  // path (so `humor` and `genre:humor:deadpan` both hit), ranked, capped. Hide what is one click
+  // away already — a swatch or a badge — so the list is only NEW choices.
+  const q = path.trim().toLowerCase();
+  const suggestions = q
+    ? tagIndex
+        .filter((t) =>
+          !colorTags.some((c) => same(c.path, t.path)) &&
+          !badges.some((b) => same(b.path, t.path)) &&
+          (t.name.toLowerCase().includes(q) || canonPath(t.path).toLowerCase().includes(q)))
+        .map((t) => ({ t, rank: rankTag(t, q) }))
+        .sort((a, b) => a.rank - b.rank || a.t.name.localeCompare(b.t.name))
+        .slice(0, 8)
+        .map((x) => x.t)
+    : [];
+  // Re-seat the highlight whenever the typed text changes (suggestions derive from it).
+  useEffect(() => { setHi(suggestions.length ? 0 : -1); }, [path]); // eslint-disable-line react-hooks/exhaustive-deps
+
   // Apply an arbitrary tag by its node path: fetch, verify it IS a tag, pick it. A bare NAME
   // (no `/`) that matches no node is CREATED at the project's tags location and then picked —
   // typing a fresh name is how a new named tag is born. A missed multi-segment path stays an
-  // error: a typo'd path must not silently mint a tag named like a path.
-  const pickPath = () => {
-    const p = path.trim();
+  // error: a typo'd path must not silently mint a tag named like a path. `raw` lets a chosen
+  // suggestion route through the same fetch-verify (re-checking the tag still exists).
+  const pickPath = (raw?: string) => {
+    const p = (raw ?? path).trim();
     if (!p || busy) return;
     setBusy(true);
     fetchNode(p.startsWith(":") ? p : p.startsWith("/") ? ":" + p.slice(1).split("/").join(":") : ":" + p, 1)
@@ -330,21 +415,56 @@ export function AnnotationMenu({
           ))}
         </div>
       )}
-      <input
-        className="annotate-taginput"
-        type="text"
-        placeholder={busy ? "creating tag…" : `${verb}: tag path or new name… ⏎`}
-        value={path}
-        disabled={busy}
-        onChange={(e) => setPath(e.target.value)}
-        onKeyDown={(e) => { if (e.key === "Enter") pickPath(); }}
-      />
+      <div className="annotate-typeahead">
+        <input
+          className="annotate-taginput"
+          type="text"
+          placeholder={busy ? "creating tag…" : `${verb}: tag path or new name… ⏎`}
+          value={path}
+          disabled={busy}
+          autoComplete="off"
+          onChange={(e) => setPath(e.target.value)}
+          onKeyDown={(e) => {
+            // Plain Arrow/Enter never reach App.tsx's global nav (it bails on focused inputs),
+            // but guard anyway and keep the caret from jumping while we drive the list.
+            if (suggestions.length && e.key === "ArrowDown") { e.preventDefault(); e.stopPropagation(); setHi((i) => (i + 1) % suggestions.length); return; }
+            if (suggestions.length && e.key === "ArrowUp") { e.preventDefault(); e.stopPropagation(); setHi((i) => (i - 1 + suggestions.length) % suggestions.length); return; }
+            if (e.key === "Escape" && path) { e.preventDefault(); e.stopPropagation(); setPath(""); return; }
+            if (e.key === "Enter") {
+              e.preventDefault(); e.stopPropagation();
+              if (hi >= 0 && suggestions[hi]) pickPath(suggestions[hi].path); // the highlighted tag wins
+              else pickPath(); // else the typed path / create-on-miss
+            }
+          }}
+        />
+        {!busy && suggestions.length > 0 && (
+          <div className="annotate-suggest" role="listbox">
+            {suggestions.map((t, i) => (
+              <span key={t.path} className={"tagframe" + (i === hi ? " sel" : "")}>
+                <button
+                  type="button"
+                  role="option"
+                  aria-selected={i === hi}
+                  className="tagtag"
+                  style={{ background: resolveTagColor(t) }}
+                  title={displayPath(t.path)}
+                  // mousedown (not click) + preventDefault: fire before the input blurs, keep focus.
+                  onMouseDown={(e) => { e.preventDefault(); pickPath(t.path); }}
+                  onMouseEnter={() => setHi(i)}
+                >
+                  {t.name}
+                </button>
+              </span>
+            ))}
+          </div>
+        )}
+      </div>
     </div>
   );
 }
 
 type MenuState =
-  | { mode: "create"; selector: Record<string, unknown>; copy?: () => void; x: number; y: number }
+  | { mode: "create"; selector: Record<string, unknown>; copy?: () => void; imageBase64?: string; x: number; y: number }
   | { mode: "edit"; ann: Annotation; x: number; y: number };
 
 /** Drives the floating picker for a material: `openCreate` after a fresh selection, `openEdit` on
@@ -352,7 +472,7 @@ type MenuState =
  *  CREATE's selector + tag, so a renderer can keep the rectangle drawn while the picker is open).
  *  Outside-click commits a create (with the pre-selected tag) but only closes an edit. */
 export function useAnnotationMenu(a: MaterialAnnotations): {
-  openCreate: (selector: Record<string, unknown>, screen: { x: number; y: number }, copy?: () => void) => void;
+  openCreate: (selector: Record<string, unknown>, screen: { x: number; y: number }, copy?: () => void, imageBase64?: string) => void;
   openEdit: (ann: Annotation, screen: { x: number; y: number }) => void;
   palette: ReactNode;
   preview: { selector: Record<string, unknown>; tag: TagRef; color: string } | null;
@@ -363,12 +483,12 @@ export function useAnnotationMenu(a: MaterialAnnotations): {
   const menuRef = useRef<HTMLDivElement>(null);
   const close = () => setMenu(null);
 
-  const openCreate = (selector: Record<string, unknown>, screen: { x: number; y: number }, copy?: () => void) =>
-    setMenu({ mode: "create", selector, copy, x: screen.x, y: screen.y });
+  const openCreate = (selector: Record<string, unknown>, screen: { x: number; y: number }, copy?: () => void, imageBase64?: string) =>
+    setMenu({ mode: "create", selector, copy, imageBase64, x: screen.x, y: screen.y });
   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, silent = false) => { if (m.mode !== "create") return; setTag(t); a.create(m.selector, t, { silent }); close(); };
+  const commitCreate = (t: TagRef, m: MenuState, silent = false) => { if (m.mode !== "create") return; setTag(t); a.create(m.selector, t, { silent, imageBase64: m.imageBase64 }); 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.
@@ -401,7 +521,7 @@ export function useAnnotationMenu(a: MaterialAnnotations): {
         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(); }}
+        onTrash={() => { a.remove(menu.ann); close(); }}
       />
     );
   }