isorite 0.9.1 → 0.10.0

package/dist/main.js

@@ -18,7 +18,7 @@ import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
 import { z } from "zod";
 import { OpenCode } from "@opencode/client";
-import { appendFile, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 import { createServer } from "node:net";
 import { isSea } from "node:sea";
@@ -142,7 +142,7 @@ function normpath(p) {
 	}
 	return "/".repeat(initial) + out.join("/") || ".";
 }
-/** SHA-256 as hex, synchronous and dependency-free, so the core runs anywhere. */
+/** SHA-256 as hex, synchronous and dependency-free, so the core runs anywhere: of text (as UTF-8), or of bytes. */
 function sha256(message) {
 	const K = new Uint32Array([
 		1116352408,
@@ -210,7 +210,7 @@ function sha256(message) {
 		3204031479,
 		3329325298
 	]);
-	const data = new TextEncoder().encode(message);
+	const data = typeof message === "string" ? new TextEncoder().encode(message) : message;
 	const len = data.length;
 	const padded = new Uint8Array(len + 9 + 63 >> 6 << 6);
 	padded.set(data);
@@ -377,7 +377,7 @@ function linkTexts(body) {
 	return out;
 }
 /** Every link and image in a body, in order: where it points, its title, and whether it is an image
-*  (`![…](…)`, which for an artifact or a picture means "shown here", an embed). */
+*  (`![…](…)`, which for an artifact or a picture means "shown here", an embed), with an image's alt text. */
 function citeRefs(body) {
 	const { tokens } = parse$1(body);
 	const out = [];
@@ -391,7 +391,8 @@ function citeRefs(body) {
 		else if (c.type === "image") out.push({
 			href: c.attrGet("src") ?? "",
 			title: c.attrGet("title"),
-			embed: true
+			embed: true,
+			alt: c.content
 		});
 	}
 	return out;
@@ -446,6 +447,64 @@ var init_markdown = __esmMin((() => {
 	SPACES = /[\s_]+/gu;
 }));
 //#endregion
+//#region packages/core/src/picture.ts
+/** Width and height in pixels, or null. */
+function pictureSize(bytes, type) {
+	const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength), n = bytes.length;
+	const at = (i, s) => [...s].every((c, k) => bytes[i + k] === c.charCodeAt(0));
+	const ok = (w, h) => w > 0 && h > 0 ? {
+		width: w,
+		height: h
+	} : null;
+	try {
+		if (type === "image/png" && n >= 24 && at(12, "IHDR")) return ok(v.getUint32(16), v.getUint32(20));
+		if (type === "image/gif" && n >= 10 && at(0, "GIF")) return ok(v.getUint16(6, true), v.getUint16(8, true));
+		if (type === "image/jpeg") {
+			for (let i = 2; i + 9 < n;) {
+				if (bytes[i] !== 255) return null;
+				const m = bytes[i + 1];
+				if (m >= 192 && m <= 207 && m !== 196 && m !== 200 && m !== 204) return ok(v.getUint16(i + 7), v.getUint16(i + 5));
+				i += 2 + v.getUint16(i + 2);
+			}
+			return null;
+		}
+		if (type === "image/webp" && n >= 30 && at(0, "RIFF") && at(8, "WEBP")) {
+			if (at(12, "VP8 ")) return ok(v.getUint16(26, true) & 16383, v.getUint16(28, true) & 16383);
+			if (at(12, "VP8L")) {
+				const b = v.getUint32(21, true);
+				return ok((b & 16383) + 1, (b >> 14 & 16383) + 1);
+			}
+			if (at(12, "VP8X")) return ok(1 + (bytes[24] | bytes[25] << 8 | bytes[26] << 16), 1 + (bytes[27] | bytes[28] << 8 | bytes[29] << 16));
+			return null;
+		}
+		if (type === "image/svg+xml") {
+			const head = new TextDecoder().decode(bytes.subarray(0, 4096)), tag = /<svg\b[^>]*>/i.exec(head)?.[0] ?? "";
+			const attr = (name) => new RegExp(`\\s${name}\\s*=\\s*["']\\s*([\\d.]+)\\s*(px)?\\s*["']`, "i").exec(tag);
+			const w = attr("width"), h = attr("height");
+			if (w && h) return ok(Math.round(Number(w[1])), Math.round(Number(h[1])));
+			const box = /\sviewBox\s*=\s*["']\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)[\s,]+([\d.]+)/i.exec(tag);
+			return box ? ok(Math.round(Number(box[1])), Math.round(Number(box[2]))) : null;
+		}
+	} catch {}
+	return null;
+}
+var TYPES$1, pictureType;
+var init_picture = __esmMin((() => {
+	TYPES$1 = {
+		png: "image/png",
+		jpg: "image/jpeg",
+		jpeg: "image/jpeg",
+		gif: "image/gif",
+		svg: "image/svg+xml",
+		webp: "image/webp",
+		avif: "image/avif"
+	};
+	pictureType = (path) => {
+		const dot = path.lastIndexOf(".");
+		return dot < 0 || path.lastIndexOf("/") > dot ? null : TYPES$1[path.slice(dot + 1).toLowerCase()] ?? null;
+	};
+}));
+//#endregion
 //#region packages/core/src/kinds.ts
 function kindOf(type) {
 	const t = type.trim().toLowerCase();
@@ -518,11 +577,25 @@ function outwardLinks(body) {
 		}
 		seen.add(href);
 	}
+	for (const { href, embed, alt } of citeRefs(body)) {
+		if (!embed || seen.has(href)) continue;
+		const c = codeTarget(href);
+		if (!c || !pictureType(c.path)) continue;
+		out.push({
+			kind: "code",
+			href,
+			text: alt || c.path.split("/").at(-1),
+			path: c.path,
+			picture: true
+		});
+		seen.add(href);
+	}
 	return out;
 }
 var ABOUT, DONE, EMBED;
 var init_kinds = __esmMin((() => {
 	init_markdown();
+	init_picture();
 	init_text();
 	ABOUT = {
 		question: "about",
@@ -725,7 +798,7 @@ var init_bundle = __esmMin((() => {
 				concept.links = links;
 				concept.outward = outwardLinks(concept.body);
 				for (const link of links) if (link.broken) this.issue(concept.path, "warning", "broken-link", `broken link to ${link.target}`);
-				for (const { href, title, embed } of citeRefs(concept.body)) {
+				for (const { href, title, embed, alt } of citeRefs(concept.body)) {
 					const path = this.filePath(concept, href), kind = path === null ? null : citeKind(path);
 					if (path === null || kind === null) continue;
 					const t = strip((title ?? "").toLowerCase());
@@ -735,10 +808,11 @@ var init_bundle = __esmMin((() => {
 						embed,
 						broken: !this.files.has(path),
 						rel: rating(title),
-						align: t === "left" ? "left" : t === "center" || t === "centre" ? "center" : null
+						align: t === "left" ? "left" : t === "center" || t === "centre" ? "center" : null,
+						...embed && alt ? { alt } : {}
 					};
 					concept.cites.push(cite);
-					if (cite.broken) this.issue(concept.path, "warning", "broken-link", `broken link to ${path}`);
+					if (cite.broken) this.issue(concept.path, "warning", "broken-link", kind === "image" ? `picture not in the notes: ${path}` : `broken link to ${path}`);
 				}
 			}
 			const byName = /* @__PURE__ */ new Map();
@@ -1809,13 +1883,16 @@ function mapModel(base) {
 			s
 		]);
 	}
+	const holdsFiles = /* @__PURE__ */ new Set();
+	for (const f of base.files) holdsFiles.add(f.includes("/") ? f.slice(0, f.lastIndexOf("/")) : "");
 	const dir = (id) => {
 		const d = base.directories.get(id);
-		return {
+		const children = [...[...d.children].sort().map(dir).filter((c) => c !== null), ...[...d.concepts].sort().map(note)];
+		return id && !children.length && (holdsFiles.has(id) || d.children.length) ? null : {
 			kind: "dir",
 			id: "d:" + id,
 			ref: id,
-			children: [...[...d.children].sort().map(dir), ...[...d.concepts].sort().map(note)]
+			children
 		};
 	};
 	return {
@@ -1830,6 +1907,7 @@ var init_map = __esmMin((() => {
 //#region packages/core/src/index.ts
 var init_src$1 = __esmMin((() => {
 	init_bundle();
+	init_picture();
 	init_frontmatter();
 	init_source();
 	init_markdown();
@@ -1884,8 +1962,9 @@ function loadBundle(root) {
 }
 //#endregion
 //#region packages/engine/src/api.ts
-var EngineError, Conflict;
+var MAX_FILE_BYTES, EngineError, Conflict;
 var init_api = __esmMin((() => {
+	MAX_FILE_BYTES = 2e7;
 	EngineError = class extends Error {
 		status;
 		constructor(message, status = 400) {
@@ -2699,6 +2778,9 @@ something at one place in the note they have open.`;
   is drawn as the diagram. Draw one where a picture of how things stand to
   each other helps, or when asked; not by habit. Maths in a label goes
   between $$ and $$.
+- A picture is shown as ![what it shows](its/path.png). You can't see it: what
+  you know of it is the words in the brackets. Keep a picture's line as it is
+  when you rewrite around it, and never make up a picture's path.
 - Ordinary Markdown otherwise. No HTML.`;
 	FORMAT_RULES = FORMAT;
 	LOOKUP = (rounds, meaning) => `# Looking things up
@@ -2807,7 +2889,7 @@ var init_lookup = __esmMin((() => {
 			...str$1,
 			description: "The note's id or path: basics/entropy or /basics/entropy.md."
 		} }, ["id"]),
-		fn$1("read_note", "Read one section of a note, by its heading, or the whole note when no section is named. Prefer a section.", {
+		fn$1("read_note", "Read one section of a note, by its heading, or the whole note when no section is named. Prefer a section. A picture in it is ![what it shows](path): you have its words, not the picture.", {
 			id: str$1,
 			section: {
 				...str$1,
@@ -4030,18 +4112,41 @@ var init_engine = __esmMin((() => {
 			const notes = {}, broken = await this.brokenCode();
 			for (const c of this.bundle.concepts.values()) {
 				const bad = broken.get(c.id) ?? [];
-				const links = c.outward.map((o) => ({
+				const links = c.outward.filter((o) => !(o.kind === "code" && o.picture)).map((o) => ({
 					kind: o.kind,
 					href: o.href,
 					text: o.text,
 					...bad.includes(o.href) ? { broken: true } : {}
 				}));
+				const pictures = [], shown = /* @__PURE__ */ new Set();
+				for (const p of c.cites) {
+					if (p.kind !== "image" || !p.embed || shown.has(p.target)) continue;
+					shown.add(p.target);
+					pictures.push({
+						href: p.target,
+						path: p.target,
+						from: "notes",
+						text: p.alt || p.target.split("/").at(-1),
+						...p.broken ? { broken: true } : {}
+					});
+				}
+				for (const o of c.outward) {
+					if (o.kind !== "code" || !o.picture) continue;
+					pictures.push({
+						href: o.href,
+						path: o.path,
+						from: "code",
+						text: o.text,
+						...bad.includes(o.href) ? { broken: true } : {}
+					});
+				}
 				notes[c.id] = {
 					title: c.title,
 					tokens: estimate(c.body.trim()),
 					...c.kind !== "note" ? { kind: c.kind } : {},
 					...c.done ? { done: c.done } : {},
-					...links.length ? { links } : {}
+					...links.length ? { links } : {},
+					...pictures.length ? { pictures } : {}
 				};
 			}
 			return {
@@ -4438,6 +4543,107 @@ var init_engine = __esmMin((() => {
 			this.queue = run.catch(() => void 0);
 			return run;
 		}
+		/** A picture (M22), in the notes or in the base's repository. The path must be a picture's, within its folder,
+		*  and (in the notes) never in a hidden folder such as `.isorite/`: nothing but a picture is given this way. */
+		async file(path, from = "notes") {
+			const type = pictureType(path);
+			if (!type) return null;
+			let files, at;
+			if (from === "code") {
+				const target = codeTarget(`code:${path}`), where = (await this.settingsOfBase()).repository;
+				files = target && where ? this.opts.repository?.(where) ?? null : null;
+				at = target?.path ?? "";
+			} else {
+				at = path.replace(/^\/+/, "");
+				files = at.split("/").some((p) => !p || p === "." || p === ".." || p.startsWith(".")) ? null : this.opts.notes;
+			}
+			const bytes = files ? await files.readBytes(at) : null;
+			if (!bytes) return null;
+			if (bytes.length > 2e7) throw new EngineError(`${path} is larger than isorite gives (${MAX_FILE_BYTES / 1e6} MB)`, 413);
+			return {
+				bytes,
+				type,
+				version: sha256(bytes).slice(0, 16)
+			};
+		}
+		/** What was read of each picture, kept while its size and time are the same. */
+		pictureCache = /* @__PURE__ */ new Map();
+		/** Every picture in the notes (M22), found afresh: one put in the folder by hand since the base was opened is
+		*  among them, and from then on in the bundle too, so a link to it isn't broken. A hidden folder is never looked in. */
+		async pictures() {
+			const found = [];
+			const visit = async (dir) => {
+				for (const f of await this.opts.notes.list(dir)) {
+					if (f.name.startsWith(".")) continue;
+					const path = dir ? `${dir}/${f.name}` : f.name;
+					if (f.dir) await visit(path);
+					else if (pictureType(f.name)) found.push({
+						path,
+						...f.size === void 0 ? {} : { size: f.size },
+						...f.mtime === void 0 ? {} : { mtime: f.mtime }
+					});
+				}
+			};
+			await visit("");
+			const out = [], seen = /* @__PURE__ */ new Set();
+			for (const f of found) {
+				seen.add(f.path);
+				const kept = this.pictureCache.get(f.path);
+				if (kept && f.size !== void 0 && kept.size === f.size && kept.mtime === f.mtime) {
+					out.push(kept.info);
+					continue;
+				}
+				const bytes = f.size !== void 0 && f.size > 2e7 ? null : await this.opts.notes.readBytes(f.path);
+				if (!bytes) continue;
+				const px = pictureSize(bytes, pictureType(f.path));
+				const info = {
+					path: f.path,
+					bytes: bytes.length,
+					width: px?.width ?? null,
+					height: px?.height ?? null,
+					sha256: sha256(bytes)
+				};
+				this.pictureCache.set(f.path, {
+					...f.size === void 0 ? {} : { size: f.size },
+					...f.mtime === void 0 ? {} : { mtime: f.mtime },
+					info
+				});
+				out.push(info);
+			}
+			for (const path of this.pictureCache.keys()) if (!seen.has(path)) this.pictureCache.delete(path);
+			let changed = false;
+			for (const path of seen) if (!this.files.has(path)) {
+				this.files.set(path, { path });
+				changed = true;
+			}
+			for (const path of [...this.files.keys()]) if (pictureType(path) && !seen.has(path)) {
+				this.files.delete(path);
+				changed = true;
+			}
+			if (changed) this.built = this.index = null;
+			return out.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+		}
+		/** Put a picture in the notes (M22). The path must be a picture's, out of any hidden folder, and free: a file
+		*  that's there is never replaced. Not journaled: a picture has no history, and stays when its link goes. */
+		savePicture(path, bytes) {
+			return this.one(async () => {
+				const type = pictureType(path), parts = path.split("/");
+				if (!type || parts.some((p) => !p || p === "." || p === ".." || p.startsWith(".")) || /[\\\x00-\x1f]/.test(path)) throw new EngineError(`not a picture's path: ${path}`, 400);
+				if (bytes.length > 2e7) throw new EngineError(`the picture is larger than isorite takes (${MAX_FILE_BYTES / 1e6} MB)`, 413);
+				if (await this.opts.notes.readBytes(path) !== null) throw new Conflict(`${path} is there already`, null);
+				await this.opts.notes.writeBytes(path, bytes);
+				this.files.set(path, { path });
+				this.built = this.index = null;
+				const px = pictureSize(bytes, type);
+				return {
+					path,
+					bytes: bytes.length,
+					width: px?.width ?? null,
+					height: px?.height ?? null,
+					sha256: sha256(bytes)
+				};
+			});
+		}
 		/** Where a note's file is: drafts and Understanding notes are among isorite's own files. */
 		where(id) {
 			if (!inBase(id)) return {
@@ -6491,6 +6697,8 @@ var init_ports = __esmMin((() => {
 	systemClock = { now: () => Date.now() };
 	MemoryFiles = class {
 		files = /* @__PURE__ */ new Map();
+		/** Files held as bytes (pictures), apart from text. */
+		bytes = /* @__PURE__ */ new Map();
 		constructor(files = {}) {
 			for (const [path, text] of Object.entries(files)) this.files.set(path, text);
 		}
@@ -6503,22 +6711,42 @@ var init_ports = __esmMin((() => {
 		async append(path, text) {
 			this.files.set(path, (this.files.get(path) ?? "") + text);
 		}
+		async readBytes(path) {
+			const b = this.bytes.get(path), t = this.files.get(path);
+			return b ?? (t === void 0 ? null : new TextEncoder().encode(t));
+		}
+		async writeBytes(path, bytes) {
+			this.files.delete(path);
+			this.bytes.set(path, bytes);
+		}
 		async remove(path) {
 			this.files.delete(path);
+			this.bytes.delete(path);
 		}
 		async list(dir) {
 			const prefix = dir ? dir + "/" : "";
 			const found = /* @__PURE__ */ new Map();
-			for (const path of this.files.keys()) {
+			for (const path of [...this.files.keys(), ...this.bytes.keys()]) {
 				if (!path.startsWith(prefix)) continue;
 				const rest = path.slice(prefix.length), cut = rest.indexOf("/");
-				if (cut < 0) found.set(rest, false);
-				else found.set(rest.slice(0, cut), true);
+				if (cut >= 0) {
+					found.set(rest.slice(0, cut), {
+						name: rest.slice(0, cut),
+						dir: true
+					});
+					continue;
+				}
+				const b = this.bytes.get(path);
+				found.set(rest, b ? {
+					name: rest,
+					dir: false,
+					size: b.length
+				} : {
+					name: rest,
+					dir: false
+				});
 			}
-			return [...found].map(([name, isDir]) => ({
-				name,
-				dir: isDir
-			}));
+			return [...found.values()];
 		}
 	};
 	MemorySecrets = class {
@@ -7978,6 +8206,7 @@ var Terminal = class {
 };
 //#endregion
 //#region packages/server/src/http.ts
+init_src$1();
 init_src();
 const LOOPBACK = /* @__PURE__ */ new Set([
 	"localhost",
@@ -7999,6 +8228,8 @@ const TYPES = {
 	".map": "application/json",
 	".txt": "text/plain; charset=utf-8"
 };
+/** What a picture may do when opened on its own: be drawn, and nothing else (no script, no fetch, no form). */
+const PICTURE_CSP = "sandbox; default-src 'none'; img-src data:; style-src 'unsafe-inline'";
 const Edit = z.object({
 	base: z.string().max(64),
 	text: z.string()
@@ -8221,6 +8452,42 @@ function createApp({ api, token, loopback, web, allowHosts = [], notes, terminal
 	app.get("/api/map", (c) => answer(c, () => api.map()));
 	app.get("/api/timeline", (c) => answer(c, () => api.timeline()));
 	app.get("/api/search", (c) => answer(c, () => api.search(c.req.query("q") ?? "")));
+	app.get("/api/pictures", (c) => answer(c, () => api.pictures()));
+	app.post("/api/file", async (c) => {
+		let origin = "";
+		try {
+			origin = new URL(c.req.header("origin") ?? "").host;
+		} catch {}
+		if (!c.req.header("origin") || origin !== c.req.header("host")) return refuse(c, 403, "cross-origin request refused");
+		if (c.req.header("x-isorite-token") !== token) return refuse(c, 403, "bad token");
+		const path = c.req.query("path") ?? "", type = pictureType(path);
+		if (!type || (c.req.header("content-type") ?? "").split(";")[0].trim().toLowerCase() !== type) return refuse(c, 415, "a picture, of the type its name says");
+		if (Number(c.req.header("content-length") ?? 0) > 2e7) return refuse(c, 413, "picture too large");
+		const bytes = new Uint8Array(await c.req.arrayBuffer());
+		if (bytes.length > 2e7) return refuse(c, 413, "picture too large");
+		return answer(c, () => api.savePicture(path, bytes));
+	});
+	app.get("/api/file", async (c) => {
+		const code = c.req.query("code"), path = code ?? c.req.query("path") ?? "";
+		let found;
+		try {
+			found = await api.file(path, code === void 0 ? "notes" : "code");
+		} catch (e) {
+			if (e instanceof EngineError) return refuse(c, e.status, e.message);
+			throw e;
+		}
+		if (!found) return refuse(c, 404, `no picture at ${path}`);
+		const etag = `"${found.version}"`;
+		const headers = {
+			"Content-Type": found.type,
+			"Cache-Control": "no-cache",
+			ETag: etag,
+			"X-Content-Type-Options": "nosniff",
+			"Content-Security-Policy": PICTURE_CSP
+		};
+		if (c.req.header("if-none-match") === etag) return c.body(null, 304, headers);
+		return c.body(found.bytes, 200, headers);
+	});
 	app.put("/api/note", async (c) => {
 		const refused = writeRefused(c);
 		if (refused) return refused;
@@ -8555,12 +8822,26 @@ var NodeFiles = class {
 			throw e;
 		}
 	}
-	/** Written beside the file and renamed over it, so a reader never sees half a note. */
+	async readBytes(path) {
+		try {
+			return new Uint8Array(await readFile(this.at(path)));
+		} catch (e) {
+			if (gone(e)) return null;
+			throw e;
+		}
+	}
 	async write(path, text) {
+		await this.replace(path, text);
+	}
+	async writeBytes(path, bytes) {
+		await this.replace(path, bytes);
+	}
+	/** Written beside the file and renamed over it, so a reader never sees half a note. */
+	async replace(path, data) {
 		const full = this.at(path), beside = `${full}.${process.pid}.${this.n++}.tmp`;
 		await mkdir(dirname(full), { recursive: true });
 		try {
-			await writeFile(beside, text, "utf8");
+			await writeFile(beside, data, typeof data === "string" ? "utf8" : void 0);
 			await rename(beside, full);
 		} catch (e) {
 			await rm(beside, { force: true });
@@ -8574,10 +8855,27 @@ var NodeFiles = class {
 	}
 	async list(dir) {
 		try {
-			return (await readdir(this.at(dir), { withFileTypes: true })).filter((e) => e.isDirectory() || e.isFile()).map((e) => ({
-				name: e.name,
-				dir: e.isDirectory()
-			})).sort((a, b) => a.name < b.name ? -1 : 1);
+			const at = this.at(dir), entries = await readdir(at, { withFileTypes: true });
+			return (await Promise.all(entries.filter((e) => e.isDirectory() || e.isFile()).map(async (e) => {
+				if (e.isDirectory()) return {
+					name: e.name,
+					dir: true
+				};
+				if (e.name.endsWith(".md")) return {
+					name: e.name,
+					dir: false
+				};
+				const s = await stat(resolve(at, e.name)).catch(() => null);
+				return s ? {
+					name: e.name,
+					dir: false,
+					size: s.size,
+					mtime: s.mtimeMs
+				} : {
+					name: e.name,
+					dir: false
+				};
+			}))).sort((a, b) => a.name < b.name ? -1 : 1);
 		} catch (e) {
 			if (gone(e)) return [];
 			throw e;
@@ -8836,7 +9134,7 @@ var Setup = class {
 };
 //#endregion
 //#region packages/server/src/version.ts
-const VERSION = "0.9.1";
+const VERSION = "0.10.0";
 //#endregion
 //#region packages/server/src/git.ts
 /** The top of the repository `folder` is in, or null: the nearest folder holding `.git`, a directory or, in a
@@ -11079,6 +11377,19 @@ const finderHttp = (pace = 0) => scriptedHttp(finderAnswer, pace);
 //#region packages/guide/src/node.ts
 /** In a checkout, the package's notes/; in the npm package, where this is bundled into dist/, the guide/ beside it. */
 const GUIDE_DIR = [join(import.meta.dirname, "..", "guide"), join(import.meta.dirname, "..", "notes")].find((d) => existsSync(join(d, "start-here.md"))) ?? join(import.meta.dirname, "..", "notes");
+/** The guide's pictures (M22), by path, as bytes. */
+function loadGuidePictures(dir = GUIDE_DIR) {
+	const out = {};
+	const visit = (at) => {
+		for (const name of readdirSync(at)) {
+			const path = join(at, name);
+			if (statSync(path).isDirectory()) visit(path);
+			else if (/\.(png|jpe?g|gif|svg|webp|avif)$/i.test(name)) out[relative(dir, path).split(sep).join("/")] = new Uint8Array(readFileSync(path));
+		}
+	};
+	visit(dir);
+	return out;
+}
 /** The guide's files as they stand in the package: its notes and its AGENTS.md, by path. */
 function loadGuide(dir = GUIDE_DIR) {
 	const out = {};
@@ -11106,7 +11417,7 @@ function writeGuide(folder) {
 		fresh: false
 	};
 	if (existsSync(at) && readdirSync(at).some((f) => f !== ".isorite")) throw new StudyError(`${at} has files in it that are not the guide: name another folder, isorite guide <folder>`);
-	for (const [path, text] of Object.entries(loadGuide())) {
+	for (const [path, text] of [...Object.entries(loadGuide()), ...Object.entries(loadGuidePictures())]) {
 		mkdirSync(dirname(join(at, path)), { recursive: true });
 		writeFileSync(join(at, path), text);
 	}
@@ -11155,8 +11466,21 @@ async function writeExample(folder, now = Date.now()) {
 		mkdirSync(dirname(at), { recursive: true });
 		writeFileSync(at, text);
 	}
+	copyPictures(NOTES_DIR, notes);
 	return { notes };
 }
+/** The pictures among a folder's notes (M22), copied as they are: they have no history. */
+function copyPictures(from, to, dir = from) {
+	for (const name of readdirSync(dir)) {
+		const path = join(dir, name);
+		if (statSync(path).isDirectory()) copyPictures(from, to, path);
+		else if (citeKind(name) === "image") {
+			const at = join(to, relative(from, path));
+			mkdirSync(dirname(at), { recursive: true });
+			copyFileSync(path, at);
+		}
+	}
+}
 const GEOMETRY_DIR = join(import.meta.dirname, "..", "geometry");
 /** The geometry example's notes, and the code beside them, as they stand today, by path. */
 function loadGeometry(dir = GEOMETRY_DIR) {
@@ -11287,7 +11611,8 @@ init_model();
 const USAGE = `isorite: an agentic harness for understanding
 
   isorite new <folder>                   start a knowledge base: the folder, empty, with isorite's .isorite/
-  isorite check <notes>                  check a folder of notes: frontmatter, links, cycles
+  isorite check <notes> [--unused]       check a folder of notes: frontmatter, links, cycles; --unused lists
+                                         the pictures no note shows
   isorite serve <notes> [--port <n>] [--allow-host <name>]
                                          open it in the browser, on this machine only
   isorite migrate <study base> [--merge] move a study base (format 1) into its notes' .isorite/; exercises
@@ -11324,7 +11649,7 @@ const USAGE = `isorite: an agentic harness for understanding
                                          the browser; run again, as you left it. Iso is your model, or with
                                          none set up, the guide's finder (also: isorite --tutorial)
 `;
-function check(notes, out = console.log) {
+function check(notes, out = console.log, unused = false) {
 	const root = resolve(notes);
 	if (!existsSync(root) || !statSync(root).isDirectory()) {
 		out(`no folder at ${root}`);
@@ -11335,12 +11660,18 @@ function check(notes, out = console.log) {
 	for (const c of cycles) out(`warning requires cycle: ${c.join(" -> ")}`);
 	const errors = issues.filter((i) => i.level === "error").length;
 	out(`${bundle.concepts.size} notes in ${bundle.directories.size} folders; ${errors} errors, ${issues.length - errors} warnings, ${cycles.length} requires cycles`);
+	if (unused) {
+		const cited = new Set([...bundle.concepts.values()].flatMap((c) => c.cites.map((x) => x.target)));
+		const idle = [...bundle.files].filter((f) => citeKind(f) === "image" && !cited.has(f)).sort();
+		for (const f of idle) out(`unused  ${f}`);
+		out(idle.length ? `${idle.length} ${idle.length === 1 ? "picture" : "pictures"} no note shows` : "every picture is shown by a note");
+	}
 	return errors ? 1 : 0;
 }
 function main(argv) {
 	const [command, ...rest] = argv;
 	try {
-		if (command === "check" && rest[0]) return check(rest[0]);
+		if (command === "check" && rest.find((r) => !r.startsWith("--"))) return check(rest.find((r) => !r.startsWith("--")), console.log, rest.includes("--unused"));
 		if (command === "new" && rest[0]) {
 			const made = newBase(rest[0]);
 			console.log(`${made}: a knowledge base, empty. Open it in the browser, or beside your code in the terminal:\n  isorite serve ${made}\n  cd <your code> && isorite term ${made}`);

package/notes/algorithms/the-quadtree/subdivision.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 260 260" width="260" height="260" font-family="sans-serif">
+  <rect x="2" y="2" width="256" height="256" fill="none" stroke="#7a8794" stroke-width="2"/>
+  <g fill="none" stroke="#7a8794" stroke-width="1.5">
+    <path d="M130 2V258M2 130H258"/>
+    <path d="M66 2V130M2 66H130"/>
+    <path d="M194 130V258M130 194H258"/>
+    <path d="M34 2V66M2 34H66"/>
+  </g>
+  <g fill="#3f7fbf">
+    <circle cx="16" cy="18" r="5"/><circle cx="50" cy="48" r="5"/><circle cx="20" cy="52" r="5"/>
+    <circle cx="98" cy="40" r="5"/><circle cx="96" cy="104" r="5"/><circle cx="200" cy="70" r="5"/>
+    <circle cx="40" cy="190" r="5"/><circle cx="160" cy="160" r="5"/><circle cx="226" cy="168" r="5"/>
+    <circle cx="170" cy="226" r="5"/>
+  </g>
+</svg>

package/notes/algorithms/the-quadtree.md

@@ -6,4 +6,6 @@ description: The plane split into squares, and each square into four, until each
 
 A tree over the bodies in 2D. The root is a square holding them all; a square with more than one body is split into four. Each node also keeps its [centre of mass](/algorithms/centre-of-mass.md "requires"). In 3D it is an octree, with eight children.
 
+![Ten bodies: the square split until each square holds at most one](the-quadtree/subdivision.svg)
+
 How is a body inserted, and what does each node keep? I don't have this straight yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isorite",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "An agentic harness for understanding: your notes as a knowledge base, an Atlas of them, an agent that reads them, and study.",
   "license": "MIT",
   "type": "module",