yamlover 0.3.0

package/src/client/api.ts

@@ -0,0 +1,186 @@
+// Typed wrappers over the server's JSON API.
+
+export interface TreeNode {
+  path: string;
+  label: string;
+  type: string;
+  format: string | null;
+  concrete: string | null; // how it is stored; `dir` → a plain-folder icon
+  hasChildren: boolean;
+  children: TreeNode[];
+}
+
+export interface NodeJson {
+  path: string;
+  type: string;
+  format?: string | null; // schema `format`; with `type` it keys the renderer
+  concrete: string | null;
+  documentPath?: string; // the document (nearest yamlover entity) this node is in —
+                         // the anchor a document-relative (`/…`) link resolves against
+  title: string | null;
+  description: string | null;
+  value: unknown;
+  relations?: Record<string, unknown>; // named up-edges (+ `..`) as ref markers
+}
+
+async function getJson<T>(url: string): Promise<T> {
+  const res = await fetch(url);
+  const body = await res.json();
+  if (!res.ok) throw new Error((body && body.error) || `HTTP ${res.status}`);
+  return body as T;
+}
+
+/** Server info: the ROOT path as given on the CLI (breadcrumb head; "" if omitted). */
+export function fetchInfo(): Promise<{ root: string }> {
+  return getJson<{ root: string }>("/api/info");
+}
+
+/** A long-running server task (indexing, hashing, …) — mirrors server/tasks.ts. Updates ride
+ *  /api/events as `{type:"task", task}` frames; this shape is also what GET /api/tasks lists. */
+export interface TaskInfo {
+  id: string;
+  label: string;
+  state: "running" | "done" | "error";
+  progress: { done: number; total?: number; message?: string };
+  startedAt: number;
+  finishedAt?: number;
+  error?: string;
+}
+
+/** Server tasks in flight (or just finished) — the snapshot a freshly loaded page needs. */
+export function fetchTasks(): Promise<TaskInfo[]> {
+  return getJson<TaskInfo[]>("/api/tasks");
+}
+
+/** The TOC subtree rooted at `path`, `depth` levels deep (server default 3). */
+export function fetchTree(path = ":", depth?: number): Promise<TreeNode> {
+  const q = new URLSearchParams({ path });
+  if (depth != null) q.set("depth", String(depth));
+  return getJson<TreeNode>(`/api/tree?${q}`);
+}
+
+export function fetchNode(
+  path: string,
+  depth?: number,
+  opts?: { binary?: boolean },
+): Promise<NodeJson> {
+  const q = new URLSearchParams({ path });
+  if (depth != null) q.set("depth", String(depth));
+  if (opts?.binary) q.set("binary", "1"); // request a binary leaf's base64 bytes
+  return getJson<NodeJson>(`/api/json?${q}`);
+}
+
+/** URL of a file-backed node's raw bytes (image / pdf / html / djvu source). */
+export function blobUrl(path: string): string {
+  return `/api/blob?path=${encodeURIComponent(path)}`;
+}
+
+/** The node's instance schema, one level deep (nested containers as link markers). */
+export function fetchSchema(path: string, depth?: number): Promise<unknown> {
+  const q = new URLSearchParams({ path });
+  if (depth != null) q.set("depth", String(depth));
+  return getJson<unknown>(`/api/schema?${q}`);
+}
+
+/** A tag as the annotation API hands it around: its node path, display name (the taxonomy key),
+ *  and explicit color — null for a named tag, whose hue the client derives from the name. */
+export interface TagRef {
+  path: string;
+  name: string;
+  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. */
+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 };
+  description?: string;
+  created?: string;
+}
+
+/** The annotations whose `target` is the material at `path` (the engine's reverse link). */
+export function fetchAnnotations(path: string): Promise<Annotation[]> {
+  return getJson<Annotation[]>(`/api/annotations?path=${encodeURIComponent(path)}`);
+}
+
+/** The materials filed under the tag at `path` — `$yamloverLink` markers, annotations already
+ *  resolved to their `target` and deduped (the explorer's member list for a tag page). */
+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 };
+    },
+  );
+}
+
+/** Create a named tag at the project's default tags location (settings.yamlover; `/tags` by
+ *  default) — the picker's create-on-miss. Idempotent: an existing tag at that path is returned
+ *  as-is; a non-tag node already occupying the path is an error. */
+export function createTag(name: string): Promise<TagRef> {
+  return fetch("/api/tag", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ name }) }).then(
+    async (res) => {
+      const body = await res.json();
+      if (!res.ok) throw new Error((body && body.error) || `HTTP ${res.status}`);
+      return body as TagRef;
+    },
+  );
+}
+
+/** The result of pasting/uploading a file or text: the new file's node path (for a text chunk,
+ *  the chapter it joined), and (for a chapter) the chapter path plus any chunk pointer appended. */
+export interface PasteResult {
+  path: string; // the new file's node path (a text chunk: the chapter's own path)
+  chapter?: string; // the chapter the chunk was appended to (chapter paste only)
+  pointer?: string; // the `*…` chunk pointer appended (chapter FILE paste only)
+  dir?: string; // the enclosing directory the file landed in (directory/member paste)
+  open?: boolean; // true when the page was a MEMBER of a directory → open the new file
+}
+
+function postPaste(body: Record<string, unknown>): Promise<PasteResult> {
+  return fetch("/api/paste", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  }).then(async (res) => {
+    const json = await res.json();
+    if (!res.ok) throw new Error((json && json.error) || `HTTP ${res.status}`);
+    return json as PasteResult;
+  });
+}
+
+/** Upload a pasted file onto the page at `target` (a directory or a chapter). */
+export function pasteFile(target: string, filename: string, contentBase64: string): Promise<PasteResult> {
+  return postPaste({ path: target, filename, contentBase64 });
+}
+
+/** Paste plain TEXT onto the page at `target`: a chapter gains it as a new chunk; anywhere else
+ *  it becomes a new chapter .yamlover file in the nearest enclosing directory. */
+export function pasteText(target: string, text: string): Promise<PasteResult> {
+  return postPaste({ path: target, text });
+}
+
+/** Paste RICH content (an HTML selection: text + images + heading-nested subchapters) onto the
+ *  page at `target`. A chapter appends the chunks and subchapters; anywhere else a new chapter
+ *  is created — directory-backed when files are present, a standalone .yamlover file otherwise.
+ *  `rich` is the RichNode tree from paste-html.ts (images already inline as base64 files). */
+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) => {
+    if (!res.ok) throw new Error(((await res.json().catch(() => null))?.error) || `HTTP ${res.status}`);
+  });
+}

package/src/client/icons.ts

@@ -0,0 +1,91 @@
+// Type/format icon for a TOC node — chosen by the schema `format`, falling back
+// to `type`. One exception to being concrete-agnostic: a node stored as an
+// on-disk directory gets a folder icon, since it really is a filesystem folder —
+// plain (`dir`, no `.yamlover/` marker) or a yamlover entity (`yamlover`).
+
+export interface Glyph {
+  glyph: string;
+  cls: string; // CSS class (color)
+  title: string; // tooltip
+}
+
+// Type → a monochrome glyph, colored by category (matches the value highlighting).
+const TYPE: Record<string, { glyph: string; cls: string }> = {
+  object: { glyph: "{}", cls: "t-struct" },
+  array: { glyph: "[]", cls: "t-struct" },
+  string: { glyph: "“”", cls: "t-str" },
+  integer: { glyph: "#", cls: "t-num" },
+  number: { glyph: "½", cls: "t-num" },
+  boolean: { glyph: "◧", cls: "t-bool" },
+  null: { glyph: "∅", cls: "t-null" },
+  binary: { glyph: "0110", cls: "t-bin binsq" }, // bits in a little square
+};
+
+// Exact-match formats → an icon.
+const FORMAT: Record<string, string> = {
+  "date-time": "🕑",
+  date: "📅",
+  time: "🕑",
+  duration: "⏳",
+  email: "✉️",
+  "idn-email": "✉️",
+  hostname: "🖥️",
+  "idn-hostname": "🖥️",
+  ipv4: "🌐",
+  ipv6: "🌐",
+  uri: "🔗",
+  iri: "🔗",
+  "uri-reference": "🔗",
+  "iri-reference": "🔗",
+  "uri-template": "🔗",
+  url: "🔗",
+  uuid: "🆔",
+  regex: "🔣",
+  "json-pointer": "📍",
+  "relative-json-pointer": "📍",
+  password: "🔑",
+  color: "🎨",
+};
+
+// Media-type / binary-encoding / custom formats → an icon, chosen by prefix.
+function mediaIcon(format: string): string | null {
+  if (format === "x-yamlover-chapter") return "§"; // a chapter — the section sign
+  if (format === "x-yamlover-tag") return "🏷️";
+  if (format.startsWith("x-yamlover-")) return "🧩"; // a custom yamlover renderer
+  if (format === "application/pdf") return "📕";
+  if (format === "application/x-fictionbook+xml") return "📘";
+  if (format === "application/epub+zip") return "📗";
+  if (format === "image/vnd.djvu") return "📓";
+  if (format.startsWith("image/")) return "🖼️";
+  if (format === "text/markdown") return "📝";
+  if (format === "text/asciidoc") return "📃";
+  if (format === "text/csv" || format === "text/tab-separated-values") return "▦"; // a table
+  if (format === "text/x-plantuml") return "📊"; // source that compiles to a diagram
+  if (format === "application/vnd.ms-excel") return "▦"; // legacy .xls workbook
+  if (format === "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet") return "▦"; // .xlsx
+  if (format === "application/rtf") return "📄";
+  if (format === "application/msword") return "📄"; // legacy .doc
+  if (format === "application/vnd.openxmlformats-officedocument.wordprocessingml.document") return "📄"; // .docx
+  if (format === "application/vnd.google-earth.kml+xml" || format === "application/vnd.google-earth.kmz") return "🗺️"; // map overlay
+  if (format.startsWith("text/")) return "📄";
+  if (format.startsWith("audio/")) return "🔊";
+  if (format.startsWith("video/")) return "🎬";
+  if (/^(u?int|float)\d/.test(format)) return "💾"; // int32/le, float64, …
+  return null;
+}
+
+/** The type/format icon for a node — `format` wins, then a directory concrete
+ *  (`dir`/`yamlover`) shows a folder, else `type`. */
+export function typeIcon(type: string, format: string | null, concrete?: string | null): Glyph {
+  if (format) {
+    const g = FORMAT[format] ?? mediaIcon(format);
+    if (g) return { glyph: g, cls: "t-fmt", title: format };
+  }
+  // a plain directory (no `.yamlover/`) — a real OS folder
+  if (concrete === "dir") return { glyph: "📁", cls: "t-struct", title: "folder" };
+  // a yamlover entity stored as a directory (a folder with a `.yamlover/` marker)
+  if (concrete === "yamlover") return { glyph: "🗂️", cls: "t-struct", title: "yamlover folder" };
+  const t = TYPE[type];
+  if (t) return { glyph: t.glyph, cls: t.cls, title: type };
+  return { glyph: "•", cls: "t-bin", title: type || "unknown" };
+}

package/src/client/links.tsx

@@ -0,0 +1,108 @@
+import { ReactNode } from "react";
+import { segsToStr, strToSegs } from "./paths";
+
+/**
+ * The shared **link** concept: one place that decides what a link *target* means
+ * and how a link is made clickable. Every renderer that emits links routes through
+ * here, so link behaviour is defined once.
+ *
+ * A target is addressed in the app's JSON instance space — the same space the
+ * tree, breadcrumbs, and the URL all navigate — with two anchors, mirroring how an
+ * `x-yamlover` `rel` pointer is written:
+ *
+ *   - **`/some/path`** — relative to the *document* the link appears in (the
+ *     nearest yamlover entity; "document" meaning the literal file/entity, overlays
+ *     and all). Resolved against the `documentPath` the server reports for the node.
+ *   - **`//some/path`** — relative to the *project root* (the location given at
+ *     yamlover startup), i.e. the served root → browser path `/some/path`.
+ *   - **`scheme://…` / `mailto:…`** — an ordinary external link.
+ *
+ * `resolveLink` is deliberately the single seam for interpretation: it is where
+ * refs and rels are expected to plug in later (gaining the full pointer grammar —
+ * `..`, `^name`, virtual children), rather than each renderer re-deciding what a
+ * target points at. (Refs/rels keep their own server-side interpretation for now;
+ * this powers marklower links.)
+ */
+
+/** A link's resolved destination. Exactly one of `path` (an in-app JSON-space path
+ *  for SPA navigation) or `href` (an external URL) is set; both null means the
+ *  target did not resolve and the link renders as plain text. */
+export interface ResolvedLink {
+  path: string | null;
+  href: string | null;
+}
+
+const UNRESOLVED: ResolvedLink = { path: null, href: null };
+
+/** True for an external target carrying a URI scheme (`http:`, `https:`, `mailto:`,
+ *  …). A `//`-rooted project path is *not* a scheme (no leading `scheme:`). */
+const hasScheme = (s: string) => /^[a-z][a-z0-9+.-]*:/i.test(s);
+
+/** Join a document base path with a document-relative path (both JSON-space),
+ *  canonicalizing the result. */
+function joinDoc(documentPath: string, rel: string): string {
+  return segsToStr([...strToSegs(documentPath), ...strToSegs(rel)]);
+}
+
+/** Tokenize a LEGACY slash-spelled link target (`/a/b[0]`) into segments. */
+function slashSegs(str: string): (string | number)[] {
+  const out: (string | number)[] = [];
+  for (const tok of str.match(/\[\d+\]|[^/\[\]]+/g) || []) {
+    out.push(/^\[\d+\]$/.test(tok) ? Number(tok.slice(1, -1)) : tok);
+  }
+  return out;
+}
+
+/** Interpret a link `target` against the `documentPath` it appears in (the JSON-space
+ *  path of its document; defaults to root). Colon spellings (`:a:b`, `::a:b` —
+ *  SEPARATOR.md) are canonical; legacy slash spellings (`/a/b`, `//a/b`) still parse. */
+export function resolveLink(target: string, documentPath = ":"): ResolvedLink {
+  const raw = target.trim();
+  if (!raw) return UNRESOLVED;
+  if (raw.startsWith("::")) return { path: segsToStr(strToSegs(raw.slice(2))), href: null }; // project root
+  if (raw.startsWith(":")) return { path: joinDoc(documentPath, raw), href: null }; // document-relative
+  if (raw.startsWith("//")) return { path: segsToStr(slashSegs(raw)), href: null }; // legacy project root
+  if (hasScheme(raw)) return { path: null, href: raw }; // external (http(s)/mailto/…)
+  if (raw.startsWith("/")) return { path: segsToStr([...strToSegs(documentPath), ...slashSegs(raw)]), href: null }; // legacy doc-relative
+  return UNRESOLVED; // anything else is not (yet) a recognized link target
+}
+
+/** Render a link as the right kind of anchor: an in-app `.descend` link that calls
+ *  `onNavigate` for an internal target, an ordinary external `.extlink` for a URL,
+ *  or plain children when the target doesn't resolve. The single place a link
+ *  becomes clickable — shared by every renderer that emits links. */
+export function NavLink({
+  target,
+  documentPath,
+  onNavigate,
+  children,
+}: {
+  target: string;
+  documentPath?: string;
+  onNavigate: (path: string) => void;
+  children: ReactNode;
+}) {
+  const { path, href } = resolveLink(target, documentPath);
+  if (href) {
+    return (
+      <a className="extlink" href={href} target="_blank" rel="noopener noreferrer">
+        {children}
+      </a>
+    );
+  }
+  if (path) {
+    return (
+      <a
+        className="descend"
+        href={path}
+        onClick={(e) => {
+          e.preventDefault();
+          onNavigate(path);
+        }}
+      >
+        {children}
+      </a>
+    );
+  }
+  return <>{children}</>;
+}

package/src/client/live.ts

@@ -0,0 +1,42 @@
+// live.ts — the client side of the UNIFIED change flow. Every change to the served tree —
+// mediated writes (annotate, tag, paste, mv) and external edits (the FS watcher) — reaches the
+// client as ONE currency: a file-level IndexDiff over /api/events, which App re-broadcasts as a
+// `yamlover:diff` window event. Hooks that hold server-derived state subscribe HERE instead of
+// inventing per-feature push paths; a new surface gets live refresh by adding one useDiffBump.
+
+import { useEffect, useState } from "react";
+
+/** A reindex/write diff as App re-broadcasts it: client JSON paths of the touched FILES
+ *  (added + changed + removed + both ends of moves), with the removals also listed alone. */
+export interface DiffDetail {
+  paths: string[];
+  removed: string[];
+}
+
+export const DIFF_EVENT = "yamlover:diff";
+
+/** Re-broadcast a server diff to the window (App's SSE handler is the only caller). */
+export function broadcastDiff(detail: DiffDetail): void {
+  window.dispatchEvent(new CustomEvent(DIFF_EVENT, { detail }));
+}
+
+/** Diffs that can affect graph-derived state (annotations, tags, document bodies) — any touched
+ *  `.yamlover` source. A binary-only diff (a photo import, say) passes nothing here. */
+export const touchesYamlover = (d: DiffDetail): boolean => d.paths.some((p) => p.endsWith(".yamlover"));
+
+/** A counter that bumps whenever a diff matches `match` (default: every diff) — put it in a
+ *  fetch effect's dependency list and the data refetches on relevant changes. `match` must be
+ *  a stable (module-level) predicate; it is deliberately not a re-subscribe dependency. */
+export function useDiffBump(match: (d: DiffDetail) => boolean = () => true): number {
+  const [bump, setBump] = useState(0);
+  useEffect(() => {
+    const on = (e: Event) => {
+      const det = (e as CustomEvent).detail as DiffDetail | undefined;
+      if (det && match(det)) setBump((b) => b + 1);
+    };
+    window.addEventListener(DIFF_EVENT, on);
+    return () => window.removeEventListener(DIFF_EVENT, on);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  return bump;
+}

package/src/client/main.tsx

@@ -0,0 +1,10 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import "./styles.css";
+
+createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/src/client/paste-html.ts

@@ -0,0 +1,228 @@
+// HTML-clipboard paste: a selection copied from a web page (Wikipedia, docs, …) arrives as
+// text/html alongside the plain text. When it carries STRUCTURE the plain flavor loses —
+// images, headings — it becomes a RICH paste: headings nest subchapters (by level), images
+// become separate chunks (downloaded in the browser — e.g. Wikimedia sends
+// `access-control-allow-origin: *`), text blocks become marklower prose. Formatted text with
+// no images/headings stays a plain text paste. Used by NodeView's paste listener.
+
+/** The client-side draft: images still by URL (downloaded later by resolveImages). */
+export interface RichDraft {
+  title?: string;
+  chunks: Array<{ text: string } | { image: { url: string; alt: string } }>;
+  children: RichDraft[];
+}
+
+/** The wire payload for POST /api/paste {rich}: images resolved to inline file bytes. */
+export interface RichNode {
+  title?: string;
+  chunks: Array<{ text: string } | { file: { name: string; contentBase64: string } }>;
+  children: RichNode[];
+}
+
+type Block =
+  | { kind: "heading"; level: number; text: string }
+  | { kind: "image"; url: string; alt: string }
+  | { kind: "text"; text: string };
+
+const SKIP = new Set(["script", "style", "noscript", "template", "iframe", "svg", "head", "title"]);
+const BLOCKS = new Set(["p", "div", "section", "article", "main", "aside", "header", "footer", "figure", "figcaption", "ul", "ol", "table", "thead", "tbody", "tr", "dl", "dt", "dd", "nav", "form", "body", "html"]);
+
+/** Parse an HTML clipboard fragment into a chapter draft — or null when it has no images and
+ *  no headings (plain formatted text: the normal text paste serves it better). */
+export function htmlToRich(html: string): RichDraft | null {
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  const blocks = mergeBullets(blocksOf(doc.body));
+  if (!blocks.some((b) => b.kind !== "text")) return null;
+
+  // headings nest by level: deeper headings open children of the nearest shallower one
+  const root: RichDraft = { chunks: [], children: [] };
+  const stack: Array<{ node: RichDraft; level: number }> = [{ node: root, level: 0 }];
+  for (const b of blocks) {
+    if (b.kind === "heading") {
+      while (stack.length > 1 && stack[stack.length - 1].level >= b.level) stack.pop();
+      const child: RichDraft = { title: b.text || "Untitled", chunks: [], children: [] };
+      stack[stack.length - 1].node.children.push(child);
+      stack.push({ node: child, level: b.level });
+    } else {
+      const top = stack[stack.length - 1].node;
+      top.chunks.push(b.kind === "image" ? { image: { url: b.url, alt: b.alt } } : { text: b.text });
+    }
+  }
+  return root;
+}
+
+/** Walk the fragment in document order, flushing inline text at block boundaries. */
+function blocksOf(body: HTMLElement): Block[] {
+  const out: Block[] = [];
+  let buf = "";
+  const flush = () => {
+    const t = buf.replace(/[ \t]+/g, " ").replace(/ ?\n ?/g, "\n").replace(/\n{2,}/g, "\n").trim();
+    buf = "";
+    if (t) out.push({ kind: "text", text: t });
+  };
+  const walk = (n: Node): void => {
+    if (n.nodeType === Node.TEXT_NODE) {
+      buf += n.textContent ?? "";
+      return;
+    }
+    if (!(n instanceof Element)) return;
+    const tag = n.tagName.toLowerCase();
+    if (SKIP.has(tag)) return;
+    if (/^h[1-6]$/.test(tag)) {
+      flush();
+      // Wikipedia headings carry an "[edit]" section link — noise in a title
+      out.push({ kind: "heading", level: Number(tag[1]), text: (n.textContent ?? "").replace(/\[edit\]/gi, "").trim() });
+      return;
+    }
+    if (tag === "img") {
+      flush();
+      const url = imageUrl(n);
+      if (url) out.push({ kind: "image", url, alt: n.getAttribute("alt") ?? "" });
+      return;
+    }
+    if (tag === "li") {
+      // one bullet per line; images inside the item still surface as their own chunks
+      flush();
+      n.childNodes.forEach(walk);
+      const t = buf.replace(/\s+/g, " ").trim();
+      buf = "";
+      if (t) out.push({ kind: "text", text: "- " + t });
+      return;
+    }
+    if (tag === "pre") {
+      flush();
+      const t = (n.textContent ?? "").replace(/\n+$/, "");
+      if (t.trim()) out.push({ kind: "text", text: "```\n" + t + "\n```" });
+      return;
+    }
+    if (tag === "blockquote") {
+      flush();
+      n.childNodes.forEach(walk);
+      const t = buf.trim();
+      buf = "";
+      if (t) out.push({ kind: "text", text: t.split("\n").map((l) => "> " + l).join("\n") });
+      return;
+    }
+    if (tag === "br") {
+      buf += "\n";
+      return;
+    }
+    if (tag === "td" || tag === "th") {
+      n.childNodes.forEach(walk);
+      buf += " ";
+      return;
+    }
+    if (BLOCKS.has(tag)) {
+      flush();
+      n.childNodes.forEach(walk);
+      flush();
+      return;
+    }
+    // an inline element: render to marklower — unless an image hides inside (then descend, so
+    // the image becomes its own chunk rather than vanishing into the text)
+    if (!n.querySelector("img")) {
+      buf += inlineMd(n);
+      return;
+    }
+    n.childNodes.forEach(walk);
+  };
+  walk(body);
+  flush();
+  return out;
+}
+
+/** Inline content → marklower: links, emphasis, code; everything else passes through as text. */
+function inlineMd(n: Node): string {
+  if (n.nodeType === Node.TEXT_NODE) return n.textContent ?? "";
+  if (!(n instanceof Element)) return "";
+  const tag = n.tagName.toLowerCase();
+  if (SKIP.has(tag)) return "";
+  if (tag === "br") return "\n";
+  const inner = Array.from(n.childNodes).map(inlineMd).join("");
+  if (tag === "a") {
+    const href = n.getAttribute("href") ?? "";
+    const t = inner.trim();
+    return /^https?:\/\//.test(href) && t ? `[${t}](${href})` : inner;
+  }
+  if (tag === "strong" || tag === "b") return inner.trim() ? `**${inner.trim()}**` : "";
+  if (tag === "em" || tag === "i") return inner.trim() ? `*${inner.trim()}*` : "";
+  if (tag === "code") return inner.trim() ? "`" + inner.trim() + "`" : "";
+  return inner;
+}
+
+/** A usable image URL: absolute http(s) or data:; protocol-relative gains https:; lazy-load
+ *  attributes win over a missing/placeholder src; anything relative is dropped (a clipboard
+ *  fragment has no base to resolve it against). */
+function imageUrl(img: Element): string | null {
+  const raw = img.getAttribute("src") || img.getAttribute("data-src") || "";
+  if (raw.startsWith("//")) return "https:" + raw;
+  if (/^https?:\/\//.test(raw) || raw.startsWith("data:image/")) return raw;
+  return null;
+}
+
+/** Consecutive single-bullet blocks (one per <li>) merge into one list chunk. */
+function mergeBullets(blocks: Block[]): Block[] {
+  const out: Block[] = [];
+  for (const b of blocks) {
+    const prev = out[out.length - 1];
+    if (b.kind === "text" && b.text.startsWith("- ") && prev?.kind === "text" && prev.text.startsWith("- ")) {
+      prev.text += "\n" + b.text;
+    } else out.push(b);
+  }
+  return out;
+}
+
+const MIME_EXT: Record<string, string> = {
+  "image/png": "png", "image/jpeg": "jpg", "image/gif": "gif", "image/webp": "webp",
+  "image/svg+xml": "svg", "image/bmp": "bmp", "image/tiff": "tiff", "image/avif": "avif",
+};
+
+/** Download every image of a draft (order kept) into inline file chunks; a failed fetch
+ *  degrades to a marklower image link, so the reference survives even when the bytes don't. */
+export async function resolveImages(draft: RichDraft): Promise<RichNode> {
+  return {
+    title: draft.title,
+    chunks: await Promise.all(
+      draft.chunks.map(async (c) => {
+        if ("text" in c) return { text: c.text };
+        try {
+          const res = await fetch(c.image.url);
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          const blob = await res.blob();
+          return { file: { name: imageName(c.image.url, blob.type), contentBase64: await blobBase64(blob) } };
+        } catch {
+          return { text: `![${c.image.alt}](${c.image.url})` };
+        }
+      }),
+    ),
+    children: await Promise.all(draft.children.map(resolveImages)),
+  };
+}
+
+/** A filename for a downloaded image: the URL path's basename, extension from the MIME type
+ *  when the URL has none (data: URLs, extensionless CDNs). */
+function imageName(url: string, mime: string): string {
+  let base = "";
+  try {
+    base = decodeURIComponent(new URL(url).pathname.split("/").pop() ?? "");
+  } catch {
+    /* data: or malformed — synthesize below */
+  }
+  if (!base || url.startsWith("data:")) base = "image";
+  if (!/\.[A-Za-z0-9]{2,5}$/.test(base)) base += "." + (MIME_EXT[mime] || "bin");
+  return base;
+}
+
+function blobBase64(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const r = new FileReader();
+    r.onload = () => resolve(String(r.result).split(",")[1] || "");
+    r.onerror = () => reject(new Error("could not read image"));
+    r.readAsDataURL(blob);
+  });
+}
+
+/** How many images a draft holds (for the progress toast). */
+export function countImages(draft: RichDraft): number {
+  return draft.chunks.filter((c) => "image" in c).length + draft.children.reduce((n, k) => n + countImages(k), 0);
+}