@appsoftwareltd/etherpk-mcp 0.7.1 → 0.8.1

package/dist/main.js

@@ -3,7 +3,7 @@ import { createInterface } from "node:readline/promises";
 import { availableParallelism, homedir, hostname, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
-import { access, chmod, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { access, chmod, lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { x25519 } from "@noble/curves/ed25519.js";
 import "@noble/hashes/argon2.js";
@@ -23,15 +23,18 @@ import * as encoding from "lib0/encoding";
 import { parse, stringify } from "yaml";
 import "fake-indexeddb/auto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import "@codemirror/language";
-import { languages } from "@codemirror/language-data";
 import { classHighlighter, highlightTree } from "@lezer/highlight";
+import { LanguageDescription } from "@codemirror/language";
+import { languages } from "@codemirror/language-data";
 import MarkdownIt from "markdown-it";
 import katex from "katex";
 import Mustache from "mustache";
+import { lookup } from "node:dns";
+import { request } from "node:https";
+import { BlockList, isIP } from "node:net";
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.7.1",
+	version: "0.8.1",
 	license: "Elastic-2.0",
 	description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
 	type: "module",
@@ -39,10 +42,11 @@ var package_default = {
 	bin: { "etherpk-mcp": "./bin/etherpk-mcp.js" },
 	files: ["bin", "dist"],
 	scripts: {
-		"build": "vite build",
+		"client-tsconfig": "pnpm --dir ../client exec svelte-kit sync",
+		"build": "pnpm client-tsconfig && vite build",
 		"check": "tsc -p tsconfig.json --noEmit",
-		"test": "vitest run",
-		"test:watch": "vitest",
+		"test": "pnpm client-tsconfig && vitest run",
+		"test:watch": "pnpm client-tsconfig && vitest",
 		"prepack": "pnpm build"
 	},
 	dependencies: {
@@ -51,20 +55,20 @@ var package_default = {
 		"@huggingface/tokenizers": "0.2.0",
 		"@lezer/highlight": "^1.2.3",
 		"@lezer/markdown": "^1.6.4",
-		"@modelcontextprotocol/sdk": "^1.30.0",
-		"@noble/curves": "^2.2.0",
-		"@noble/hashes": "^2.2.0",
+		"@modelcontextprotocol/sdk": "1.30.0",
+		"@noble/curves": "2.2.0",
+		"@noble/hashes": "2.2.0",
 		"@sqlite.org/sqlite-wasm": "3.53.0-build1",
 		"fake-indexeddb": "^6.2.5",
 		"katex": "^0.17.0",
-		"lib0": "^0.2.117",
+		"lib0": "0.2.117",
 		"markdown-it": "15.0.2",
 		"mermaid": "^11.16.1",
 		"mustache": "4.2.0",
 		"playwright-core": "1.59.1",
-		"y-protocols": "^1.0.7",
+		"y-protocols": "1.0.7",
 		"yaml": "^2.9.0",
-		"yjs": "^13.6.31",
+		"yjs": "13.6.31",
 		"zod": "^4.3.6"
 	},
 	devDependencies: {
@@ -80,7 +84,7 @@ var package_default = {
 	homepage: "https://docs.etherpk.com/using-ai-agents-with-your-notes",
 	repository: {
 		"type": "git",
-		"url": "https://github.com/appsoftwareltd/etherpk",
+		"url": "https://github.com/appsoftwareltd/etherpk-client",
 		"directory": "apps/mcp"
 	},
 	keywords: [
@@ -1393,50 +1397,6 @@ function wrapOo1Db(db) {
 	};
 }
 //#endregion
-//#region ../client/src/lib/storage/fs/frontmatter-span.ts
-/** A line that is exactly a `---` delimiter (trailing spaces and tabs allowed). */
-var DELIMITER = /^---[ \t]*\r?$/;
-/** The Frontmatter of `text`, or `null` when it has none — including an unterminated opener. */
-function frontmatterSpan(text) {
-	const firstBreak = text.indexOf("\n");
-	if (firstBreak === -1 || !DELIMITER.test(text.slice(0, firstBreak))) return null;
-	const bodyFrom = firstBreak + 1;
-	let lineStart = bodyFrom;
-	let lines = 1;
-	while (lineStart <= text.length) {
-		const nextBreak = text.indexOf("\n", lineStart);
-		const lineEnd = nextBreak === -1 ? text.length : nextBreak;
-		lines += 1;
-		if (DELIMITER.test(text.slice(lineStart, lineEnd))) {
-			let bodyTo = Math.max(bodyFrom, lineStart - 1);
-			if (bodyTo > bodyFrom && text[bodyTo - 1] === "\r") bodyTo -= 1;
-			return {
-				end: nextBreak === -1 ? text.length : nextBreak + 1,
-				lines,
-				body: text.slice(bodyFrom, bodyTo),
-				bodyFrom,
-				bodyTo
-			};
-		}
-		if (nextBreak === -1) break;
-		lineStart = nextBreak + 1;
-	}
-	return null;
-}
-/**
-* How many lines a document's [[Frontmatter]] occupies - opener and closer included - given the
-* document already split into lines, or 0 when it has none. The same rule as {@link frontmatterSpan}
-* (a lone `---` is not a block; an unterminated one is not a block), for the line-shaped consumers
-* in the editor that treat the block as opaque: the outliner's scans, the bullet dots, the guides,
-* the clamp. Those already hold `lines`, and re-joining them per keystroke to ask the text form
-* would be the only O(n) step in an otherwise line-local pass.
-*/
-function frontmatterLines(lines) {
-	if (lines.length < 2 || !DELIMITER.test(lines[0])) return 0;
-	for (let i = 1; i < lines.length; i++) if (DELIMITER.test(lines[i])) return i + 1;
-	return 0;
-}
-//#endregion
 //#region ../client/src/lib/document/fenced-code.ts
 /** A backtick fence line, tolerant of a leading plain-bullet marker (`- `) so `- ``` ` is a fence.
 *  Backticks only (this slice) — tildes are left untouched, so they are not auto-completed. */
@@ -1518,6 +1478,57 @@ function fencedBlocks(lines, closerTolerance = 0) {
 	}
 	return blocks;
 }
+/**
+* A line of a fenced block as code: the indentation up to the fence's column is structure (the
+* block's place in the outline) and goes; whatever lies past it is the code's own and stays.
+*/
+function codeLineText(line, fenceColumn) {
+	return line.length - line.trimStart().length >= fenceColumn ? line.slice(fenceColumn) : line.trimStart();
+}
+//#endregion
+//#region ../client/src/lib/storage/fs/frontmatter-span.ts
+/** A line that is exactly a `---` delimiter (trailing spaces and tabs allowed). */
+var DELIMITER = /^---[ \t]*\r?$/;
+/** The Frontmatter of `text`, or `null` when it has none — including an unterminated opener. */
+function frontmatterSpan(text) {
+	const firstBreak = text.indexOf("\n");
+	if (firstBreak === -1 || !DELIMITER.test(text.slice(0, firstBreak))) return null;
+	const bodyFrom = firstBreak + 1;
+	let lineStart = bodyFrom;
+	let lines = 1;
+	while (lineStart <= text.length) {
+		const nextBreak = text.indexOf("\n", lineStart);
+		const lineEnd = nextBreak === -1 ? text.length : nextBreak;
+		lines += 1;
+		if (DELIMITER.test(text.slice(lineStart, lineEnd))) {
+			let bodyTo = Math.max(bodyFrom, lineStart - 1);
+			if (bodyTo > bodyFrom && text[bodyTo - 1] === "\r") bodyTo -= 1;
+			return {
+				end: nextBreak === -1 ? text.length : nextBreak + 1,
+				lines,
+				body: text.slice(bodyFrom, bodyTo),
+				bodyFrom,
+				bodyTo
+			};
+		}
+		if (nextBreak === -1) break;
+		lineStart = nextBreak + 1;
+	}
+	return null;
+}
+/**
+* How many lines a document's [[Frontmatter]] occupies - opener and closer included - given the
+* document already split into lines, or 0 when it has none. The same rule as {@link frontmatterSpan}
+* (a lone `---` is not a block; an unterminated one is not a block), for the line-shaped consumers
+* in the editor that treat the block as opaque: the outliner's scans, the bullet dots, the guides,
+* the clamp. Those already hold `lines`, and re-joining them per keystroke to ask the text form
+* would be the only O(n) step in an otherwise line-local pass.
+*/
+function frontmatterLines(lines) {
+	if (lines.length < 2 || !DELIMITER.test(lines[0])) return 0;
+	for (let i = 1; i < lines.length; i++) if (DELIMITER.test(lines[i])) return i + 1;
+	return 0;
+}
 " ".repeat(2);
 /** Width of the `- ` marker, which sets a bullet's content column (`indent + MARKER_WIDTH`). */
 var MARKER_WIDTH = 2;
@@ -1729,11 +1740,17 @@ function normaliseIndentUnit(text) {
 *  3. **Continuation lines** — non-bullet lines indented to a bullet's content
 *     column belong to the *same* block (the soft-newline-within-a-block).
 *
+* A complete [[Fenced Code Block]] is opaque to all three: it belongs whole to the block its
+* opener sits in, so a blank line, a `# comment` or a `- item` inside it is code, never a block
+* boundary, a heading or a bullet. "Complete" is the editor's pairing (`fencedBlocks`), the same
+* one the outline walk (`indent-unit.ts`) takes fences whole by.
+*
 * A block has a kind (heading / paragraph / bullet / task). Blocks have no
 * persistent identity: a block is its source range in the current parse.
 *
-* Pure and DOM-free; the editor (keyboard ops, fold) and the derived index consume
-* it. See Dual Mode Editor.md.
+* Pure and DOM-free; the derived index (`index-derive.ts`) and the publisher's navigation
+* (`publish/nav.ts`) consume it. The editor reads the same outline through `indent-unit.ts`.
+* See Dual Mode Editor.md.
 */
 function indentOf(line) {
 	return line.length - line.trimStart().length;
@@ -1762,7 +1779,21 @@ function taskDone(line) {
 */
 function parseBlocks(markdown) {
 	const lines = markdown.split("\n");
-	const outline = outlineLines(lines);
+	const fences = fencedBlocks(lines);
+	const outline = outlineLines(lines, fences);
+	const fenceAt = new Map(fences.map((f) => [f.start, f]));
+	/**
+	* Add line `k` to a block's `buf` and return the line after it. A line that opens a complete
+	* fenced block brings the whole block with it, so nothing inside the fence is read as structure.
+	* A fence nested inside it starts within the range taken, so only outermost fences reach here.
+	*/
+	const take = (k, buf) => {
+		buf.push(lines[k].trimStart());
+		const fence = fenceAt.get(k);
+		if (!fence) return k + 1;
+		for (let n = k + 1; n <= fence.end; n++) buf.push(codeLineText(lines[n], fence.fenceColumn));
+		return fence.end + 1;
+	};
 	const flat = [];
 	let i = 0;
 	while (i < lines.length) {
@@ -1788,12 +1819,9 @@ function parseBlocks(markdown) {
 			const contentCol = indentOf(lines[i]) + 2;
 			const done = taskDone(lines[i]);
 			const start = i;
-			const buf = [lines[i].trimStart()];
-			i++;
-			while (i < lines.length && lines[i].trim() !== "" && headingLevel(lines[i]) === void 0 && !isBullet(lines[i]) && indentOf(lines[i]) >= contentCol) {
-				buf.push(lines[i].trimStart());
-				i++;
-			}
+			const buf = [];
+			i = take(i, buf);
+			while (i < lines.length && lines[i].trim() !== "" && headingLevel(lines[i]) === void 0 && !isBullet(lines[i]) && indentOf(lines[i]) >= contentCol) i = take(i, buf);
 			flat.push({
 				type: done === void 0 ? "bullet" : "task",
 				depth,
@@ -1805,12 +1833,9 @@ function parseBlocks(markdown) {
 			continue;
 		}
 		const start = i;
-		const buf = [lines[i].trimStart()];
-		i++;
-		while (i < lines.length && lines[i].trim() !== "" && headingLevel(lines[i]) === void 0 && !isBullet(lines[i]) && indentOf(lines[i]) === indentOf(lines[start])) {
-			buf.push(lines[i].trimStart());
-			i++;
-		}
+		const buf = [];
+		i = take(i, buf);
+		while (i < lines.length && lines[i].trim() !== "" && headingLevel(lines[i]) === void 0 && !isBullet(lines[i]) && indentOf(lines[i]) === indentOf(lines[start])) i = take(i, buf);
 		flat.push({
 			type: "paragraph",
 			depth,
@@ -1997,14 +2022,12 @@ function serialiseTags(tags) {
 /**
 * A predicate over source line numbers: is this line inside a [[Fenced Code Block]]?
 *
-* The [[Block]] model does not treat fences as opaque, so `- [ ] x` written inside a fence
-* parses as a [[Task]] like any other bullet. That was invisible while nothing listed tasks;
-* the [[Tasks View]] makes it visible, as phantom tasks lifted out of code examples. Two
-* things follow from excluding them here rather than in the block model: the editor's outliner
-* behaviour is untouched (a fence's lines still belong to their block, which is what the
-* keyboard layer expects), and a [[Protected Document]] - an `etherpk-cipher` fence - can never
-* contribute a task, whatever it holds. That last one is a rule, not an optimisation: the
-* [[Derived Index]] is plaintext at rest and outlives the session.
+* A `- [ ] x` written inside a fence must not become a [[Task]]: the [[Tasks View]] would list
+* phantom tasks lifted out of code examples. The [[Block]] model now takes a complete fence
+* whole (block-model.ts), so no task starts inside one; this scan stays for what the block model
+* cannot know, that a [[Protected Document]] - an `etherpk-cipher` fence - never contributes a
+* task, whatever it holds. That is a rule, not an optimisation: the [[Derived Index]] is
+* plaintext at rest and outlives the session.
 *
 * "Inside a fence" is the EDITOR's answer, not a second one: the column-scoped pairing of
 * `fencedBlocks` (Editor Content Rules → "Inside a block"), so a task is indexed exactly when
@@ -2040,6 +2063,15 @@ function blockLabel(block) {
 	return bulletLabel(first);
 }
 /**
+* A block as a reader sees it: the marker stripped as in its {@link blockLabel}, and every line
+* after the first kept - continuation lines and fenced code, which a label drops. What a
+* references [[View]] quotes and a semantic passage embeds.
+*/
+function blockContent(block) {
+	const newline = block.text.indexOf("\n");
+	return newline === -1 ? block.label : block.label + block.text.slice(newline);
+}
+/**
 * The label of a bullet or [[Task]] line — its marker and checkbox stripped, indentation
 * ignored. Exported because the [[Tasks View]]'s write-back guard has to ask "is the line in
 * the document still the task the index recorded?", and the only honest way to answer is with
@@ -2225,9 +2257,7 @@ var OVERLAP_MAX_CHARS = Math.floor(PASSAGE_BUDGET_CHARS / 4);
 var CRUMB = " > ";
 /** A block's text with its bullet / task / heading marker gone, continuation lines kept. */
 function blockBody(block) {
-	const newline = block.text.indexOf("\n");
-	const rest = newline === -1 ? "" : block.text.slice(newline);
-	return stripWikilinkBrackets(block.label + rest);
+	return stripWikilinkBrackets(blockContent(block));
 }
 /** `[[Physics]]` embeds as `Physics`: the brackets are syntax, not meaning. */
 function stripWikilinkBrackets(text) {
@@ -2545,7 +2575,7 @@ function createSchema(db) {
 	db.exec(SCHEMA$1);
 	db.run("INSERT OR IGNORE INTO index_metadata (key, value) VALUES ('active_generation', 1)");
 	db.run("INSERT OR IGNORE INTO index_metadata (key, value) VALUES ('revision', 0)");
-	db.exec(`PRAGMA user_version = 11`);
+	db.exec(`PRAGMA user_version = 12`);
 }
 function activeIndexGeneration(db) {
 	return db.all("SELECT value FROM index_metadata WHERE key = 'active_generation'")[0]?.value ?? 1;
@@ -2566,7 +2596,7 @@ function advanceIndexRevision(db) {
 */
 function isUsableIndex(db) {
 	try {
-		return db.all("PRAGMA user_version")[0]?.user_version === 11;
+		return db.all("PRAGMA user_version")[0]?.user_version === 12;
 	} catch {
 		return false;
 	}
@@ -3077,16 +3107,40 @@ function collectSubtree(blocks, rootId) {
 		const b = blocks[id];
 		if (!b) return;
 		out.push({
-			label: b.label,
+			text: blockContent(b),
 			depth,
-			isMatch: id === rootId
+			isMatch: id === rootId,
+			...b.kind === "task" ? { done: b.done === true } : {}
 		});
 		for (const child of childrenByParent.get(id) ?? []) walk(child.localId, depth + 1);
 	};
 	walk(rootId, 0);
 	return out;
 }
-/** Truncate `text` to MAX_CONTEXT chars centred on the match, with ellipses. */
+/**
+* Widen `[start, end)` so that neither end falls inside a complete fenced code block. Half a code
+* block is no excerpt at all, and an opener cut from its closer would render as raw backticks.
+*/
+function widenToFences(text, start, end) {
+	const lines = text.split("\n");
+	const lineStarts = [];
+	let offset = 0;
+	for (const line of lines) {
+		lineStarts.push(offset);
+		offset += line.length + 1;
+	}
+	for (const fence of fencedBlocks(lines)) {
+		const from = lineStarts[fence.start];
+		const to = lineStarts[fence.end] + lines[fence.end].length;
+		if (start > from && start < to) start = from;
+		if (end > from && end < to) end = to;
+	}
+	return [start, end];
+}
+/**
+* Truncate `text` to MAX_CONTEXT chars centred on the match, with ellipses. The window grows past
+* MAX_CONTEXT rather than cut a fenced code block in two ({@link widenToFences}).
+*/
 function truncateContext(text, matchStart, matchEnd) {
 	if (text.length <= MAX_CONTEXT) return {
 		text,
@@ -3095,17 +3149,17 @@ function truncateContext(text, matchStart, matchEnd) {
 		truncated: false
 	};
 	const mid = Math.floor((matchStart + matchEnd) / 2);
-	let start = Math.max(0, mid - Math.floor(MAX_CONTEXT / 2));
-	const end = Math.min(text.length, start + MAX_CONTEXT);
-	start = Math.max(0, end - MAX_CONTEXT);
-	const prefix = start > 0 ? "…" : "";
-	const suffix = end < text.length ? "…" : "";
+	const windowStart = Math.max(0, mid - Math.floor(MAX_CONTEXT / 2));
+	const windowEnd = Math.min(text.length, windowStart + MAX_CONTEXT);
+	const [start, end] = widenToFences(text, Math.max(0, windowEnd - MAX_CONTEXT), windowEnd);
+	const prefix = start === 0 ? "" : text[start - 1] === "\n" ? "…\n" : "…";
+	const suffix = end === text.length ? "" : text[end] === "\n" ? "\n…" : "…";
 	const shift = prefix.length - start;
 	return {
 		text: prefix + text.slice(start, end) + suffix,
 		matchStart: Math.max(0, matchStart + shift),
 		matchEnd: Math.max(0, matchEnd + shift),
-		truncated: true
+		truncated: prefix !== "" || suffix !== ""
 	};
 }
 /** Build a reference: a block subtree for bullets/tasks, prose context otherwise. */
@@ -3167,7 +3221,7 @@ function backlinksFor(db, concept) {
          WHERE p.generation=? AND l.concept_key IN (${placeholders})`, [generation, ...names]);
 	const blocksByPage = /* @__PURE__ */ new Map();
 	for (const pid of new Set(hits.map((h) => h.page_id))) {
-		const rows = db.all("SELECT local_id, parent_local_id, ord, kind, depth, label, text FROM blocks WHERE page_id=? ORDER BY local_id", [pid]);
+		const rows = db.all("SELECT local_id, parent_local_id, ord, kind, depth, done, label, text FROM blocks WHERE page_id=? ORDER BY local_id", [pid]);
 		const blocks = [];
 		for (const r of rows) blocks[r.local_id] = {
 			localId: r.local_id,
@@ -3175,6 +3229,7 @@ function backlinksFor(db, concept) {
 			ord: r.ord,
 			kind: r.kind,
 			depth: r.depth,
+			...r.done === null ? {} : { done: r.done === 1 },
 			startLine: 0,
 			endLine: 0,
 			text: r.text,
@@ -3863,7 +3918,7 @@ function cacheRoot(env) {
 * recovered from a joined path (see there).
 */
 var CACHE_FILE_NAME = `local-cache.v${CACHE_DB_VERSION}.bin`;
-var INDEX_FILE_NAME = `index.v11.sqlite`;
+var INDEX_FILE_NAME = `index.v12.sqlite`;
 var VECTORS_FILE_NAME = `vectors.v1.sqlite`;
 function cacheFile(dir) {
 	return join(dir, CACHE_FILE_NAME);
@@ -3874,7 +3929,7 @@ function indexFile(dir) {
 function vectorsFile(dir) {
 	return join(dir, VECTORS_FILE_NAME);
 }
-function request(req) {
+function request$1(req) {
 	return new Promise((resolve, reject) => {
 		req.onsuccess = () => resolve(req.result);
 		req.onerror = () => reject(req.error);
@@ -3889,7 +3944,7 @@ function done(tx) {
 }
 /** Open the cache database the sync engine already created; never creates or upgrades it. */
 async function openCacheDb() {
-	const db = await request(indexedDB.open(CACHE_DB, CACHE_DB_VERSION));
+	const db = await request$1(indexedDB.open(CACHE_DB, CACHE_DB_VERSION));
 	for (const store of CACHE_STORES) if (!db.objectStoreNames.contains(store)) {
 		db.close();
 		throw new Error(`Local Cache database has no "${store}" store; open the graph cache before restoring it.`);
@@ -3927,7 +3982,7 @@ async function captureLocalCache(graphId) {
 	try {
 		const tx = db.transaction([...CACHE_STORES], "readonly");
 		const rows = {};
-		for (const store of CACHE_STORES) rows[store] = (await request(tx.objectStore(store).getAll())).filter((row) => row.graphId === graphId).map(withStandaloneBuffers);
+		for (const store of CACHE_STORES) rows[store] = (await request$1(tx.objectStore(store).getAll())).filter((row) => row.graphId === graphId).map(withStandaloneBuffers);
 		await done(tx);
 		return {
 			version: CACHE_DB_VERSION,
@@ -4649,13 +4704,8 @@ var performanceRecorder = createPerformanceRecorder({ enabled: typeof window !==
 var ENTITLEMENT_AUDIENCE = "urn:etherpk:sync-entitlements";
 var ENTITLEMENT_SERVICE = "managed-sync";
 /**
-* Version-agnostic, like `isUuid` on the Server. The subject was matched by four different
-* hand-rolled patterns that happened to agree only because billing account ids are v4 today:
-* one accepted v1 to v5, another v1 to v8, another any 36 characters of hex and dashes
-* (quality audit B4). If an id ever became a uuidv7 - which is what better-auth already mints
-* - the strictest of them would have silently stopped matching, and the Stripe webhook's
-* metadata fallback would have answered 409 "Unknown Stripe customer" for a real subscription.
-* One pattern, here, next to the claim it belongs to.
+* Version-agnostic, like `isUuid` on the Server: any UUID version matches, so an id minted as a
+* uuidv7 is recognised as readily as a v4. One pattern, here, next to the claim it belongs to.
 */
 var ENTITLEMENT_SUBJECT_PATTERN = /^billing-account:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var httpsUrl = z.url().refine((value) => {
@@ -5093,7 +5143,7 @@ function createSyncProtocol(overrides = {}) {
 }
 var defaultProtocol = createSyncProtocol();
 defaultProtocol.parseClientMessage;
-var parseServerMessage$1 = defaultProtocol.parseServerMessage;
+var parseServerMessage = defaultProtocol.parseServerMessage;
 var serializeClientMessage$1 = defaultProtocol.serializeClientMessage;
 defaultProtocol.serializeServerMessage;
 //#endregion
@@ -5102,13 +5152,10 @@ defaultProtocol.serializeServerMessage;
 * The asset chunking contract, shared by the Client that uploads and the Sync Server that
 * signs the upload URLs.
 *
-* These constants used to live only in the Client, which made the declared `size` on
-* `POST /api/v1/sync/assets` a number the server had to take on trust: it counted the
-* declared figure against the storage entitlement and then handed back presigned PUT URLs
-* that bound nothing, so `size: 1024` bought unlimited bytes in the bucket (quality audit
-* S2). With the contract stated here the server can derive exactly how many chunks an asset
-* of a given size has, and exactly how long each chunk's ciphertext must be, and sign that
-* length into the URL.
+* Shared so that the declared `size` on `POST /api/v1/sync/assets` is not taken on trust: from
+* the contract stated here the server derives exactly how many chunks an asset of a given size
+* has, and exactly how long each chunk's ciphertext must be, and signs that length into each
+* presigned PUT URL.
 *
 * Changing either constant is a protocol change: the Client's chunking and the Server's
 * signed lengths must move together, or every upload fails with an opaque 403.
@@ -5852,13 +5899,41 @@ function createDocSync(deps) {
 * added and checked only at the serialisation boundary so the document engine does not repeat
 * a transport constant on every operation.
 */
-/** Returns null for anything malformed, oversized or from an unsupported protocol version. */
-function parseServerMessage(raw) {
-	const result = parseServerMessage$1(raw);
-	if (!result.ok) return null;
-	const { v: _version, ...message } = result.value;
-	return message;
+function readServerMessage(raw) {
+	const result = parseServerMessage(raw);
+	if (result.ok) {
+		const { v: _version, ...message } = result.value;
+		return {
+			kind: "message",
+			message
+		};
+	}
+	if (result.code === "unsupported_version") {
+		const { v } = JSON.parse(raw);
+		if (typeof v === "number" && Number.isInteger(v)) return {
+			kind: "protocol_mismatch",
+			serverVersion: v
+		};
+	}
+	return { kind: "malformed" };
 }
+/**
+* The Sync Server speaks another sync protocol version, so nothing it sends can be read and
+* nothing this Client sends will be accepted. Retrying cannot fix it; one side has to be
+* upgraded. The message is for logs and the Headless Client; the browser maps the error to
+* its own copy in `sync-error-copy.ts`.
+*/
+var SyncProtocolMismatchError = class extends Error {
+	name = "SyncProtocolMismatchError";
+	constructor(serverVersion, clientVersion = 2) {
+		super(serverVersion < clientVersion ? `The Sync Server speaks sync protocol ${serverVersion} and this Client speaks ${clientVersion}: the server is older, and its operator needs to upgrade it.` : `The Sync Server speaks sync protocol ${serverVersion} and this Client speaks ${clientVersion}: this Client is older and needs upgrading.`);
+		this.serverVersion = serverVersion;
+		this.clientVersion = clientVersion;
+	}
+	get serverIsOlder() {
+		return this.serverVersion < this.clientVersion;
+	}
+};
 function serializeClientMessage(message) {
 	return serializeClientMessage$1({
 		v: 2,
@@ -6019,6 +6094,39 @@ function sanitizeQuickNotes(raw) {
 	}
 	return out;
 }
+new Intl.Segmenter(void 0, { granularity: "word" });
+/**
+* The spelling a dictionary is asked about: a curly apostrophe (`’`), which keyboards and
+* pastes produce, straightened, since Hunspell dictionaries spell contractions with `'`.
+*/
+function spellingForm(word) {
+	return word.replace(/’/g, "'");
+}
+/** Longer than any real word; a line this long is not one. */
+var MAX_WORD_LENGTH = 100;
+/**
+* The word as the dictionary keeps it, or null when it cannot be one entry. A curly apostrophe is
+* straightened, the form the checker compares (`spelling/words.ts` → `spellingForm`), so a word
+* added from `don’t` also accepts `don't`.
+*/
+function normaliseDictionaryWord(raw) {
+	const word = spellingForm(raw.trim().normalize("NFC"));
+	if (word === "" || /\s/u.test(word) || word.length > MAX_WORD_LENGTH) return null;
+	return word;
+}
+/** Well-formed words, deduped (first seen wins), capped: tolerant of a peer's or a newer client's list. */
+function sanitizeDictionaryWords(raw) {
+	if (!Array.isArray(raw)) return [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of raw) {
+		if (typeof entry !== "string") continue;
+		const word = normaliseDictionaryWord(entry);
+		if (word === null || seen.has(word)) continue;
+		seen.add(word);
+		if (seen.size >= 5e4) break;
+	}
+	return [...seen];
+}
 //#endregion
 //#region ../client/src/lib/storage/fs/frontmatter.ts
 /**
@@ -6391,6 +6499,12 @@ function createGraphSync(deps) {
 	let socket;
 	let open = false;
 	let disposed = false;
+	/**
+	* Set when the Sync Server turned out to speak another protocol version. The session then
+	* stops for good: every reconnect would meet the same server, and nothing either side
+	* sends can be read by the other. Pending appends stay in the cache for a later session.
+	*/
+	let protocolMismatch;
 	const reportError = (error) => {
 		if (!disposed) deps.onError?.(error instanceof Error ? error : new Error(String(error)));
 	};
@@ -6412,6 +6526,7 @@ function createGraphSync(deps) {
 	function waitForCurrentConnection() {
 		if (open && socket) return Promise.resolve();
 		if (disposed) return Promise.reject(/* @__PURE__ */ new Error("the graph sync session was disposed"));
+		if (protocolMismatch) return Promise.reject(protocolMismatch);
 		return new Promise((resolve, reject) => {
 			connectionWaiters.add({
 				resolve,
@@ -6451,7 +6566,7 @@ function createGraphSync(deps) {
 	}
 	/**
 	* Documents the CURRENT socket has subscribed to. The relay keeps and forwards presence
-	* only for a subscribed document (ASTRA F11), and this mirrors that rule at the source:
+	* only for a subscribed document, and this mirrors that rule at the source:
 	* y-protocols renews every engine's awareness state every fifteen seconds, and an engine
 	* created for a background walk starts with an empty `{}` state, so without the gate every
 	* unretained engine encrypted and sent presence the relay would only drop. Cleared with
@@ -6469,9 +6584,9 @@ function createGraphSync(deps) {
 	}
 	/**
 	* Subscribe to every retained document on a freshly opened socket, in batches the relay
-	* accepts. One message used to carry the whole set, and above the protocol's per-message
-	* limit the relay rejects it as invalid, which left a tab with many open views silently
-	* without live updates for anything after a reconnect (ASTRA F11).
+	* accepts. Above the protocol's per-message limit the relay rejects a subscribe as invalid,
+	* which would leave a tab with many open views silently without live updates after a
+	* reconnect.
 	*/
 	function subscribeRetained() {
 		const docIds = [...retained.keys()];
@@ -6609,6 +6724,7 @@ function createGraphSync(deps) {
 	if (deps.onRegistryChange) registryMap.observe(() => deps.onRegistryChange?.());
 	const metaMap = root.doc.getMap("meta");
 	const quickNotesArray = root.doc.getArray("quickNotes");
+	const dictionaryMap = root.doc.getMap("spellingDictionary");
 	const themesMap = root.doc.getMap("themes");
 	/** A stored theme as a plain object, or null when the entry is not one. */
 	function readTheme(id) {
@@ -6662,9 +6778,23 @@ function createGraphSync(deps) {
 			publishNameOnceCaughtUp();
 		}, () => {});
 	}
+	/** Report once, fail everything waiting for a connection, and close without reconnecting. */
+	function stopForProtocolMismatch(serverVersion) {
+		if (protocolMismatch) return;
+		protocolMismatch = new SyncProtocolMismatchError(serverVersion);
+		reportError(protocolMismatch);
+		for (const waiter of connectionWaiters) waiter.reject(protocolMismatch);
+		connectionWaiters.clear();
+		socket?.close();
+	}
 	function handleMessage(raw) {
-		const message = parseServerMessage(raw);
-		if (!message) return;
+		const read = readServerMessage(raw);
+		if (read.kind === "protocol_mismatch") {
+			stopForProtocolMismatch(read.serverVersion);
+			return;
+		}
+		if (read.kind === "malformed") return;
+		const message = read.message;
 		if (message.type === "catchup_batch") performanceRecorder.mark("sync.catchup.batch", {
 			rows: message.updates.length,
 			bytes: new TextEncoder().encode(raw).byteLength,
@@ -6710,7 +6840,7 @@ function createGraphSync(deps) {
 	* on open. Only rebuildable snapshot uploads use a volatile queue.
 	*/
 	function connect() {
-		if (disposed) return;
+		if (disposed || protocolMismatch) return;
 		deps.token().then((token) => {
 			if (disposed) return;
 			const s = deps.connect(`${deps.relayUrl}?token=${encodeURIComponent(token)}`);
@@ -6752,7 +6882,7 @@ function createGraphSync(deps) {
 					pending.reject(new WatermarkConnectionInterruptedError());
 				}
 				watermarkRequests.clear();
-				if (!disposed) setTimeout(connect, RECONNECT_MS);
+				if (!disposed && !protocolMismatch) setTimeout(connect, RECONNECT_MS);
 			});
 		}, () => {
 			if (!disposed) setTimeout(connect, TOKEN_RETRY_MS);
@@ -6859,6 +6989,21 @@ function createGraphSync(deps) {
 				return () => quickNotesArray.unobserve(listener);
 			}
 		}),
+		spellingDictionary: () => ({
+			list: () => sanitizeDictionaryWords([...dictionaryMap.keys()]),
+			add(word) {
+				dictionaryMap.set(word, true);
+			},
+			remove(words) {
+				root.doc.transact(() => {
+					for (const word of words) dictionaryMap.delete(word);
+				});
+			},
+			observe(listener) {
+				dictionaryMap.observe(listener);
+				return () => dictionaryMap.unobserve(listener);
+			}
+		}),
 		themes: () => ({
 			list() {
 				const out = [];
@@ -8861,6 +9006,32 @@ function assetHashFromName(fileName) {
 		ext: (match[3] ?? "").toLowerCase()
 	};
 }
+/**
+* Whether a decoded asset name is one file inside `assets/`, and so safe to join onto a folder.
+*
+* An asset reference comes from a document, and a document can come from a collaborator, an
+* import or an agent, so the name it decodes to is untrusted: `../assets/..%2Fpages%2FSecret.md`
+* decodes to a path that leaves `assets/`. Every place that turns a reference into a file path
+* (the asset stores, the publisher's bundle) checks this first, before any directory adapter
+* or site writer sees the name.
+*/
+function isSafeAssetName(name) {
+	if (!isSingleFileName(name)) return false;
+	for (const char of name) {
+		const code = char.codePointAt(0) ?? 0;
+		if (code < 32 || code === 127) return false;
+	}
+	return true;
+}
+/**
+* Whether `name` is one entry of a directory rather than a path: not empty, not `.` or `..`, and
+* free of separators and NUL. What a directory adapter requires of every name it is handed, which
+* is looser than {@link isSafeAssetName}: a file already on disk may carry other odd characters.
+*/
+function isSingleFileName(name) {
+	if (name === "" || name === "." || name === "..") return false;
+	return !name.includes("/") && !name.includes("\\") && !name.includes("\0");
+}
 //#endregion
 //#region ../client/src/lib/storage/fs/asset-store.ts
 /**
@@ -8961,11 +9132,22 @@ var MIME_TYPES = {
 function mimeTypeForExt(ext) {
 	return MIME_TYPES[ext.replace(/^\./, "").toLowerCase()] ?? "";
 }
-/** The on-disk name referenced by a doc-relative asset ref, or `null` if `ref` is not an asset reference. */
+/**
+* The on-disk name referenced by a doc-relative asset ref, or `null` if `ref` is not an asset
+* reference. A reference whose name decodes to anything but one file inside `assets/`, or does not
+* decode at all, is not one: it can never name a file on disk (see `isSafeAssetName`).
+*/
 function assetNameFromRef(ref) {
 	const clean = ref.split(/[?#]/)[0];
 	const match = ASSET_REF$1.exec(clean);
-	return match ? decodeURIComponent(match[1]) : null;
+	if (!match) return null;
+	let name;
+	try {
+		name = decodeURIComponent(match[1]);
+	} catch {
+		return null;
+	}
+	return isSafeAssetName(name) ? name : null;
 }
 /**
 * The markdown to embed a saved asset: an inline image, or a plain link that downloads on click.
@@ -9455,6 +9637,16 @@ function isCalendarDay(value) {
 function isJournalConcept(concept) {
 	return isCalendarDay(concept);
 }
+/**
+* Why a [[Page]] cannot be called `day`: a day is the name of that day's [[Journal Entry]].
+*
+* A page given one sits in `pages/` answering to the day, which is what an older version left
+* behind when a Draft for a date promoted to a page. Creating a page and renaming one both
+* refuse with this, on both backends, so the copy is the same wherever the user meets it.
+*/
+function dayIsNotAPageName(day) {
+	return `“${day.trim()}” is a date, and a date is the name of that day's journal entry, so a page cannot be called that. Choose a different name.`;
+}
 //#endregion
 //#region ../client/src/lib/document/wikilink/rename.ts
 /**
@@ -9736,11 +9928,17 @@ var RenameUnconfirmedError = class extends Error {
 * journal-shaped [[Pageless Concept]] (a day nobody has written yet) is refused for the same
 * reason: its name is its day whether or not the entry exists.
 *
+* The same holds in the other direction: a page renamed TO a day is refused, rather than left
+* in `pages/` answering to the day or merged into its journal entry with a `title` block the
+* entry never carries (ADR 0056).
+*
 * A collision is NOT a refusal (ADR 0038 §4): it is a [[Merge]], confirmed in the dialog.
 */
 function renameRefusal(options) {
-	if (options.to.trim() === "") return "A page needs a non-empty name.";
+	const to = options.to.trim();
+	if (to === "") return "A page needs a non-empty name.";
 	if (options.kind === "journal" || options.kind === null && isJournalConcept(options.from)) return "A journal entry cannot be renamed - its name is its date, and there is exactly one per day.";
+	if (options.kind === "page" && isJournalConcept(to)) return dayIsNotAPageName(to);
 	return null;
 }
 /** Every step, direct first - what an applier iterates. */
@@ -9896,17 +10094,29 @@ function reconcileDecision({ dirty, baseText, diskText }) {
 //#endregion
 //#region ../client/src/lib/storage/fs/scan.ts
 var SCANNED_SUBDIRS = ["journals", "pages"];
-function isMarkdown(name) {
+/** Whether a listed name is a document file: `.md`, in any case. A `.crswap` swap file is not. */
+function isDocumentFile(name) {
 	return /\.md$/i.test(name);
 }
-async function scanGraph(adapter) {
+function fileKey(subdir, fileName) {
+	return `${subdir}/${fileName}`;
+}
+async function scanGraph(adapter, options = {}) {
+	const previous = /* @__PURE__ */ new Map();
+	for (const entry of options.previous ?? []) previous.set(fileKey(entry.subdir, entry.fileName), entry);
+	const writeInFlight = options.writeInFlight ?? (() => false);
 	const journals = [];
 	const pages = [];
 	for (const subdir of SCANNED_SUBDIRS) {
 		const kind = documentKindOf(subdir);
 		if (!kind) continue;
 		for (const { name, lastModified, size } of await adapter.list(subdir)) {
-			if (!isMarkdown(name)) continue;
+			if (!isDocumentFile(name)) continue;
+			const known = previous.get(fileKey(subdir, name));
+			if (known !== void 0 && (known.lastModified === lastModified && known.size === size || writeInFlight(subdir, name))) {
+				(kind === "journal" ? journals : pages).push(known);
+				continue;
+			}
 			const { text } = await adapter.read(subdir, name);
 			const fm = parseFrontmatter(text);
 			const concept = kind === "journal" ? journalConceptOf(name) : conceptOf$1(fm, fileStem(name));
@@ -9939,7 +10149,7 @@ async function scanGraph(adapter) {
 * debounce) so it is exercised in Node over createMemoryDirectoryAdapter before
 * any browser code exists.
 *
-* Async-seam note (see docs/docs/technical/Document Editor.md): the seam's
+* Async-seam note: the seam's
 * `getText()` is synchronous but disk reads are async, so `open()` returns a
 * handle whose buffer is empty on first open and is hydrated by an internal
 * awaited read that then notifies subscribers the *external* way — which is safe
@@ -10045,9 +10255,22 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		open.set(doc.key, doc);
 		for (const listener of documentRenamed) listener(from, entry.concept);
 	}
-	/** Replace the registry from a fresh scan; fire onDocumentsChanged iff it changed. */
+	/**
+	* Replace the registry from a fresh scan; fire onDocumentsChanged iff it changed. The scan
+	* is given the entries it has and reuses each whose file has not moved, so a pass over an
+	* unchanged graph reads nothing, and it is told which files have a write in flight so it
+	* never opens one the store is saving - on Windows that read handle would make the
+	* browser's rename of its swap file over the target fail. A fresh store has no entries, so
+	* graph open reads every file and learns every identity.
+	*/
 	async function refreshRegistry() {
-		const entries = await scanGraph(adapter);
+		const entries = await scanGraph(adapter, {
+			previous: registry.values(),
+			writeInFlight: (subdir, fileName) => {
+				for (const doc of open.values()) if (doc.saving && doc.subdir === subdir && doc.fileName === fileName) return true;
+				return false;
+			}
+		});
 		registry.clear();
 		for (const entry of entries) registry.set(entry.key, entry);
 		const sig = registrySignature(entries);
@@ -10490,6 +10713,7 @@ function createFilesystemDocumentStore(adapter, options = {}) {
 		async createPage(title, body = "") {
 			const concept = title.trim();
 			if (concept === "") throw new Error("A page needs a non-empty title.");
+			if (isJournalConcept(concept)) throw new Error(dayIsNotAPageName(concept));
 			const key = conceptKey(concept);
 			if (registry.get(key)) throw new Error(`A document for "${concept}" already exists.`);
 			await adapter.ensureSkeleton();
@@ -10610,6 +10834,7 @@ function describeFilesystemSaveFailure(error, concept) {
 		case "NoModificationAllowedError": return `${opening} The file is locked by another program - a sync tool, or an editor holding it open. Close that, then retry. ${KEPT}`;
 		case "NotFoundError": return `${opening} The folder is no longer where it was - a drive unplugged, or the folder moved. Make it available again, then retry. ${KEPT}`;
 		case "NotReadableError": return `${opening} The file could not be read when it was opened, so nothing is written over it. Once it can be read the app reloads it, or asks you to choose if you have typed since. ${KEPT}`;
+		case "InvalidStateError": return `${opening} Another program was using the file at the same time. Retry in a moment. If it keeps happening, check what else is using this folder. ${KEPT}`;
 		default: return `${opening}${error instanceof Error && error.message ? ` The browser reported: ${error.message}.` : ""} Retry in a moment. ${KEPT}`;
 	}
 }
@@ -11346,6 +11571,7 @@ function createServerDocumentStore(graph, options) {
 			return day;
 		},
 		async createPage(title, body = "") {
+			if (isJournalConcept(title)) throw new Error(dayIsNotAPageName(title));
 			if (docIdFor(title)) throw new Error(`A page for "${title}" already exists`);
 			const docId = crypto.randomUUID();
 			registry.set(docId, {
@@ -11668,6 +11894,16 @@ function isTransient(error) {
 function kebabStem(name) {
 	return name.replace(/\.[^.]+$/, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "asset";
 }
+/**
+* The MIME type a downloaded asset is given: its extension's, from the same short list the
+* Filesystem Backend uses, or `application/octet-stream`. Never the type recorded in the asset's
+* metadata, which is whatever the uploader's client sent: a collaborator could type an asset
+* `text/html`, and a blob opened in its own tab would then be a same-origin HTML document. The
+* extension is the reference's, the one the viewers are chosen by.
+*/
+function assetTypeFor(ref) {
+	return mimeTypeForExt(extOf(ref)) || "application/octet-stream";
+}
 function extOf(name) {
 	const m = /\.([^.]+)$/.exec(name);
 	return m ? m[1].toLowerCase() : "bin";
@@ -11761,7 +11997,7 @@ function createServerAssetStore(deps) {
 		return {
 			bytes: joined,
 			name: metadata.name,
-			type: metadata.type
+			type: assetTypeFor(ref)
 		};
 	}
 	return {
@@ -12227,17 +12463,22 @@ async function openHeadlessFolder(deps) {
 	});
 	const indexHost = deps.persistDir ? nodeIndexHost(deps.persistDir) : void 0;
 	/**
-	* The folder's listing as one string: every document file's name, mtime and size. The
-	* store's own reconcile re-reads every file to learn titles and aliases, which is right
-	* for the browser's poll but too much for a pass before every tool call on a large
-	* graph, so a pass first lists the two document subdirectories - a stat per file, no
-	* reads - and runs the full reconcile only when this differs from the last pass. An
-	* edit that keeps both mtime and size (an mtime-preserving copy) is missed until
+	* The folder's listing as one string: every document file's name, mtime and size. A pass
+	* first lists the two document subdirectories - a stat per file, no reads - and runs the
+	* store's reconcile only when this differs from the last pass, so a pass before every
+	* tool call on a large graph costs nothing when nothing moved. Only document files count:
+	* a browser saving into the same folder writes a `.crswap` swap file first and renames it
+	* over the document when the save lands, and a pass started by the swap file would read
+	* the documents while that rename is due, which on Windows makes the browser's save fail.
+	* An edit that keeps both mtime and size (an mtime-preserving copy) is missed until
 	* something else changes, the same blind spot the store's own fast path accepts.
 	*/
 	const listingSignature = async () => {
 		const parts = [];
-		for (const subdir of ["journals", "pages"]) for (const entry of await deps.adapter.list(subdir)) parts.push(`${subdir}/${entry.name}@${entry.lastModified}:${entry.size}`);
+		for (const subdir of ["journals", "pages"]) for (const entry of await deps.adapter.list(subdir)) {
+			if (!isDocumentFile(entry.name)) continue;
+			parts.push(`${subdir}/${entry.name}@${entry.lastModified}:${entry.size}`);
+		}
 		return parts.sort().join("|");
 	};
 	let lastListing;
@@ -13318,31 +13559,48 @@ function archiveHtml(journals) {
 	return `<ul class="journal-archive">${journals.map((j) => `<li><time datetime="${escapeHtml$6(j.date ?? "")}">${escapeHtml$6(j.date ?? "")}</time> <a href="${escapeHtml$6(j.url)}">${escapeHtml$6(j.title)}</a>${j.excerpt ? `<p>${escapeHtml$6(j.excerpt)}</p>` : ""}</li>`).join("")}</ul>`;
 }
 //#endregion
-//#region ../client/src/lib/document/publish/highlight.ts
-function escapeHtml$5(text) {
-	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-}
+//#region ../client/src/lib/document/code-languages.ts
+/**
+* The grammar for a [[Fenced Code Block]]'s info-string, from the registry the editor nests inside
+* fences (`@codemirror/language-data`, see `view/augmentations/code-highlight.ts`). Every surface
+* that highlights code outside an editor - the publisher (`publish/highlight.ts`) and the
+* read-only quotes (`code-tokens.ts`) - resolves a language here, so each knows the languages
+* the editor knows, by the same names and aliases.
+*
+* The match is exact: a language's name or one of its aliases, in any case. The editor's own
+* lookup (`@codemirror/lang-markdown`) also matches an alias found inside the info-string, which
+* reads `text`, `plaintext` and `context` as LaTeX (alias `tex`), so a plain-text block turned
+* into a LaTeX one, `%` starting a comment. That fuzzy step is not repeated here.
+*/
 var loaded = /* @__PURE__ */ new Map();
-function describe(lang) {
-	const byName = languages.find((d) => d.name.toLowerCase() === lang.toLowerCase());
-	if (byName) return byName;
-	return languages.find((d) => d.alias.some((a) => a.toLowerCase() === lang.toLowerCase())) ?? null;
-}
 /** The grammar for an info-string, loaded once; null for a language the editor does not know either. */
-async function loadLanguage(lang) {
+async function loadCodeLanguage(lang) {
 	const key = lang.toLowerCase();
 	let pending = loaded.get(key);
 	if (!pending) {
-		const description = describe(key);
+		const description = LanguageDescription.matchLanguageName(languages, key, false);
 		pending = description ? description.load().catch(() => null) : Promise.resolve(null);
 		loaded.set(key, pending);
 	}
 	return pending;
 }
+//#endregion
+//#region ../client/src/lib/document/publish/highlight.ts
+/**
+* Code highlighting for the site with the grammars the editor already ships: the same
+* `@codemirror/language-data` registry `code-highlight.ts` nests inside fences, resolved by
+* `code-languages.ts`, run headless over the fence's text and emitted as `<span class="tok-…">`
+* (the `classHighlighter` names), so a site knows exactly the languages the editor knows and needs
+* no script for it. A theme colours the `tok-*` classes. Unknown languages come back as null and
+* render escaped.
+*/
+function escapeHtml$5(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
 /** The fence's code as highlighted HTML (the `<code>` element's inner HTML), or null when the language is unknown. */
 async function highlightCode(lang, code) {
 	if (lang === "") return null;
-	const support = await loadLanguage(lang);
+	const support = await loadCodeLanguage(lang);
 	if (!support) return null;
 	const tree = support.language.parser.parse(code);
 	let out = "";
@@ -13607,15 +13865,22 @@ function wikilinkRule(md, resolve) {
 */
 /** A document-relative asset reference: any number of `../`, `assets/`, the name. */
 var ASSET_REF = /^(?:\.\.\/)*assets\/(.+)$/;
+/**
+* The asset a reference names, decoded, or null when it names none. A name that decodes to
+* anything but one file inside `assets/` is not an asset: it would become a bundle path, and a site
+* folder, outside `assets/` (see `isSafeAssetName`). The link is then left as the author wrote it.
+*/
 function assetNameOf(ref) {
 	const match = ASSET_REF.exec(ref);
 	if (!match) return null;
 	const raw = match[1].split(/[?#]/)[0];
+	let name;
 	try {
-		return decodeURIComponent(raw);
+		name = decodeURIComponent(raw);
 	} catch {
-		return raw;
+		name = raw;
 	}
+	return isSafeAssetName(name) ? name : null;
 }
 function escapeHtml$3(text) {
 	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -13823,7 +14088,7 @@ function linkTargetPattern(excluded = "") {
 * A regex may not repeat a group name, so compose this **once** per pattern. Wrap it in a group of
 * your own where you need the whole link as one capture.
 */
-var MARKDOWN_LINK = `(?<bang>!?)\\[(?<label>[^\\]]*)\\]\\((?<target>${linkTargetPattern()})\\)`;
+var MARKDOWN_LINK = `(?<bang>!?)\\[(?<label>(?:[^\\[\\]]|\\[[^\\[\\]]*\\])*)\\]\\((?<target>${linkTargetPattern()})\\)`;
 /** A match's groups, typed. Every {@link MARKDOWN_LINK} match has all three. */
 function linkGroups(match) {
 	return match.groups;
@@ -13925,6 +14190,24 @@ function contentOf(block) {
 	return first.replace(/^-\s+/, "").trim();
 }
 var WHOLE_LINK = new RegExp(`^${MARKDOWN_LINK}$`);
+/** The schemes an outline link may carry onto a published page; a target with no scheme is a path on the site. */
+var NAV_LINK_SCHEMES = new Set([
+	"http",
+	"https",
+	"mailto"
+]);
+/**
+* An outline link's target, or null when a published page must not carry it. Links in page bodies
+* go through markdown-it's validateLink; the outline is parsed here, so it gets its own rule. The
+* scheme is read after removing the control characters and spaces a browser would ignore, so
+* '\u0001javascript:' is read as javascript.
+*/
+function navLinkTarget(target) {
+	const visible = [...target].filter((c) => c.charCodeAt(0) > 32 && c.charCodeAt(0) !== 127).join("");
+	const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(visible);
+	if (!scheme) return target;
+	return NAV_LINK_SCHEMES.has(scheme[1].toLowerCase()) ? target : null;
+}
 function buildNav(outline, resolver) {
 	const issues = [];
 	function convert(blocks) {
@@ -13958,10 +14241,24 @@ function buildNav(outline, resolver) {
 				const link = WHOLE_LINK.exec(content);
 				if (link && !linkGroups(link).bang) {
 					const { label, target } = linkGroups(link);
+					const href = navLinkTarget(target);
+					if (href === null) {
+						issues.push({
+							level: "warning",
+							code: "nav-link-unsafe",
+							message: `The navigation links "${label}" to a target a published page does not carry (only http, https, mailto and site paths); the entry is shown without its link.`
+						});
+						out.push({
+							label,
+							labelHtml: escapeHtml$1(label),
+							children
+						});
+						continue;
+					}
 					out.push({
 						label,
 						labelHtml: escapeHtml$1(label),
-						href: target,
+						href,
 						external: true,
 						children
 					});
@@ -14573,7 +14870,7 @@ async function publishPublication(source, publication, env, options = {}) {
 	let assetsDone = 0;
 	for (const [name, from] of wanted) {
 		progress("assets", assetsDone++, wanted.size);
-		const asset = await source.readAsset(`../assets/${name}`);
+		const asset = await source.readAsset(`../assets/${encodeURIComponent(name)}`);
 		if (!asset) {
 			report.assets.missing.push({
 				name,
@@ -14723,6 +15020,8 @@ function themeFilesOfBundled(theme) {
 		files
 	};
 }
+/** Far more files than any theme uses, and a bound on the fetches one publish can trigger. */
+var MAX_URL_THEME_FILES = 500;
 /** Fetch a theme from its manifest URL; every file the manifest lists, relative to it. */
 async function fetchTheme(url, fetchText) {
 	let json;
@@ -14734,10 +15033,12 @@ async function fetchTheme(url, fetchText) {
 	const { manifest, errors } = parseThemeManifest(json);
 	if (!manifest) throw new Error(`The theme at ${url} cannot be used: ${errors.join(" ")}`);
 	if (manifest.files.length === 0) throw new Error(`The theme at ${url} lists no files in its manifest, so nothing can be fetched.`);
+	if (manifest.files.length > MAX_URL_THEME_FILES) throw new Error(`The theme at ${url} lists ${manifest.files.length} files; a theme may list at most ${MAX_URL_THEME_FILES}.`);
 	const base = new URL(url);
 	const files = /* @__PURE__ */ new Map();
 	for (const path of manifest.files) {
 		const fileUrl = new URL(path, base).toString();
+		if (!isThemeFilePath(path) || new URL(fileUrl).origin !== base.origin) throw new Error(`The theme at ${url} lists "${path}", which is not a theme file beside its manifest (layouts/, partials/ or assets/).`);
 		try {
 			files.set(path, await fetchText(fileUrl));
 		} catch (error) {
@@ -15069,6 +15370,150 @@ async function openDiagramRenderer(env) {
 	};
 }
 //#endregion
+//#region src/public-fetch.ts
+/**
+* Fetching text from the public internet, and nowhere else: the only network reads a tool makes
+* with an address it did not choose itself (a theme published at a URL, and every file its
+* manifest lists). The URL comes from a document or a tool argument, so a collaborator or a
+* prompt-injected agent could otherwise point this process at a service on the local machine or
+* the network it sits on, and read the answer back through `read_theme_file`.
+*
+* The rules: https only, no credentials in the URL, every address the host resolves to must be
+* public, redirects are followed by hand and each hop checked the same way, and a response is cut
+* off by a deadline and a size cap. The address check runs inside the socket's own DNS lookup, so
+* the address connected to is the address checked; resolving first and connecting afterwards
+* would let a second resolution answer differently.
+*/
+/** Ranges no theme is served from: loopback, private, link-local, shared, reserved, documentation, multicast. */
+var blocked = new BlockList();
+for (const [network, prefix] of [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.0.0.0", 24],
+	["192.0.2.0", 24],
+	["192.168.0.0", 16],
+	["198.18.0.0", 15],
+	["198.51.100.0", 24],
+	["203.0.113.0", 24],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4]
+]) blocked.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+	["::", 128],
+	["::1", 128],
+	["64:ff9b::", 96],
+	["100::", 64],
+	["2001:db8::", 32],
+	["fc00::", 7],
+	["fe80::", 10],
+	["ff00::", 8]
+]) blocked.addSubnet(network, prefix, "ipv6");
+/** Whether an IP address is one on the public internet. Anything that is not an address is not. */
+function isPublicAddress(address) {
+	const family = isIP(address);
+	if (family === 4) return !blocked.check(address, "ipv4");
+	if (family !== 6) return false;
+	const dotted = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(address);
+	if (dotted) return isPublicAddress(dotted[1]);
+	const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(address);
+	if (hex) {
+		const [high, low] = [parseInt(hex[1], 16), parseInt(hex[2], 16)];
+		return isPublicAddress(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`);
+	}
+	return !blocked.check(address, "ipv6");
+}
+var DEFAULT_TIMEOUT_MS = 15e3;
+/** Far above any real theme file, and a bound on what one response can hold in memory. */
+var DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
+var DEFAULT_MAX_REDIRECTS = 3;
+var NotPublicError = class extends Error {
+	code = "ENOTPUBLIC";
+};
+/** A lookup that answers only when every address the name resolves to is public. */
+function publicOnly(lookup) {
+	return (hostname, options, callback) => {
+		lookup(hostname, { all: true }, (error, addresses) => {
+			if (error) return callback(error);
+			const refused = addresses.find((entry) => !isPublicAddress(entry.address));
+			if (refused || addresses.length === 0) return callback(new NotPublicError(`${hostname} resolves to ${refused?.address ?? "no address"}, which is not a public address.`));
+			if (options.all) callback(null, addresses);
+			else callback(null, addresses[0].address, addresses[0].family);
+		});
+	};
+}
+function checkUrl(url) {
+	if (url.protocol !== "https:") throw new Error(`Only https URLs can be fetched, not ${url.protocol}//${url.host}.`);
+	if (url.username || url.password) throw new Error("A URL with credentials in it cannot be fetched.");
+}
+function fetchOnce(url, deps, deadline) {
+	return new Promise((resolve, reject) => {
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) return reject(/* @__PURE__ */ new Error(`Fetching ${url.href} took longer than ${deps.timeoutMs / 1e3} seconds.`));
+		const req = deps.request(url, {
+			method: "GET",
+			lookup: publicOnly(deps.lookup),
+			headers: {
+				accept: "*/*",
+				"user-agent": "etherpk-mcp"
+			}
+		}, (res) => {
+			const status = res.statusCode ?? 0;
+			if (status >= 300 && status < 400 && res.headers.location) {
+				res.resume();
+				return resolve({ redirect: new URL(res.headers.location, url) });
+			}
+			if (status < 200 || status >= 300) {
+				res.resume();
+				return reject(new Error(`${status} ${res.statusMessage ?? ""}`.trim()));
+			}
+			const chunks = [];
+			let size = 0;
+			res.on("data", (chunk) => {
+				size += chunk.byteLength;
+				if (size > deps.maxBytes) {
+					req.destroy(/* @__PURE__ */ new Error(`${url.href} is larger than ${deps.maxBytes} bytes.`));
+					return;
+				}
+				chunks.push(chunk);
+			});
+			res.on("end", () => {
+				clearTimeout(timer);
+				if (size <= deps.maxBytes) resolve({ text: Buffer.concat(chunks).toString("utf8") });
+			});
+			res.on("error", reject);
+		});
+		const timer = setTimeout(() => req.destroy(/* @__PURE__ */ new Error(`Fetching ${url.href} took longer than ${deps.timeoutMs / 1e3} seconds.`)), remaining);
+		req.on("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		req.end();
+	});
+}
+/** The text at a public https URL, under the rules at the top of this module. */
+async function fetchPublicText(href, options = {}) {
+	const deps = {
+		lookup: options.lookup ?? lookup,
+		request: options.request ?? request,
+		timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
+		maxRedirects: options.maxRedirects ?? DEFAULT_MAX_REDIRECTS
+	};
+	const deadline = Date.now() + deps.timeoutMs;
+	let url = new URL(href);
+	for (let hops = 0;; hops += 1) {
+		checkUrl(url);
+		const hop = await fetchOnce(url, deps, deadline);
+		if ("text" in hop) return hop.text;
+		if (hops >= deps.maxRedirects) throw new Error(`${href} redirected more than ${deps.maxRedirects} times.`);
+		url = hop.redirect;
+	}
+}
+//#endregion
 //#region src/publish-environment.ts
 /**
 * The publisher's environment in Node (ADR 0082, ADR 0084): themes resolved the way the Client
@@ -15078,11 +15523,8 @@ async function openDiagramRenderer(env) {
 * counterpart of `host/browser-environment.ts`; the core is shared.
 */
 var require = createRequire(import.meta.url);
-async function fetchText$1(url) {
-	const response = await fetch(url);
-	if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
-	return response.text();
-}
+/** A url theme's files, from public https hosts only (see public-fetch.ts). */
+var fetchText$1 = (url) => fetchPublicText(url);
 var katexAssetsPromise = null;
 /** `katex.min.css` plus its woff2 fonts under `fonts/`, as the stylesheet references them. */
 async function katexAssets() {
@@ -15237,6 +15679,56 @@ function withPublishFolder(folders, graphKey, publicationId, folder) {
 	} };
 }
 //#endregion
+//#region src/local-folders.ts
+/**
+* Where the tools may write on this machine. A tool argument is chosen by the agent, and the agent
+* can be steered by what it reads in the notes, so a folder it names is only ever a place under
+* the graph's downloads directory (ADR 0086 keeps even that choice from `publish`). A name that
+* resolves outside it, directly or through a symbolic link, is refused.
+*/
+/** A folder the agent named that is not under the base; the tools report it as `invalid_argument`. */
+var FolderRefused = class extends Error {};
+/** Whether `child` is `parent` or a path beneath it; both already resolved. */
+function within(parent, child) {
+	return child === parent || child.startsWith(parent.endsWith(sep) ? parent : parent + sep);
+}
+/** The nearest part of `path` that exists on disk: the path itself, or its closest existing parent. */
+async function existingPart(path) {
+	let at = path;
+	for (;;) try {
+		await lstat(at);
+		return at;
+	} catch {
+		const up = dirname(at);
+		if (up === at) return at;
+		at = up;
+	}
+}
+/**
+* The folder the agent asked for under `base`, or `fallback` (a path relative to `base`) when it
+* named none. A relative name is taken relative to `base`; an absolute one must already be under
+* it. Checked twice: as written, and after resolving every symbolic link in the part that exists.
+*/
+async function folderUnder(base, requested, fallback) {
+	const root = resolve(base);
+	const wanted = requested?.trim() ? requested.trim() : fallback;
+	const target = resolve(root, wanted);
+	if (!within(root, target)) throw new FolderRefused(`"${wanted}" is outside ${root}. Name a folder under it, or leave it out for the default.`);
+	await mkdir(root, { recursive: true });
+	if (!within(await realpath(root), await realpath(await existingPart(target)))) throw new FolderRefused(`"${wanted}" leads outside ${root} through a symbolic link.`);
+	return target;
+}
+/**
+* Whether a preview page may load `url`: its own files and inline data, nothing else. A theme's
+* script runs when the preview is photographed, and a theme can come from a collaborator or a URL,
+* so the page is kept off the network and away from the rest of the disk.
+*/
+function previewRequestAllowed(url, folder) {
+	if (url.startsWith("data:") || url.startsWith("blob:") || url === "about:blank") return true;
+	const own = pathToFileURL(folder.endsWith(sep) ? folder : folder + sep).href;
+	return url.startsWith(own);
+}
+//#endregion
 //#region src/headless-assets.ts
 /**
 * What the asset tools need from a graph's [[Asset]]s, behind one seam for both backends
@@ -15247,9 +15739,46 @@ function withPublishFolder(folders, graphKey, publicationId, folder) {
 * reference names an asset (`identify`), which is what the index is asked about when the tools
 * decide whether an asset is reachable from a document the agent can read.
 */
-/** A local file as `upload_asset` reads it. */
-async function readLocalFile(path) {
-	const buffer = await readFile(path);
+/**
+* The largest file `upload_asset` reads. The Sync Server applies its own, usually smaller, limit;
+* this one bounds what a single call can pull into memory whatever the backend.
+*/
+var MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+async function realOrResolved(path) {
+	try {
+		return await realpath(path);
+	} catch {
+		return resolve(path);
+	}
+}
+/**
+* Refuse a file an agent should not be able to put into a graph. The path is a tool argument, and
+* an agent can be steered by what it reads, so an upload is a way to copy a local file somewhere
+* collaborators can read it. Refused: the Headless Client's cache (the graph's decrypted
+* contents) and config (sign-in tokens), and anything hidden (a dot-file, or a file inside a
+* dot-folder such as `.ssh` or `.aws`), which is where credentials and settings live. `real` has
+* every link resolved, so a link is judged by the file it leads to.
+*/
+async function refuseProtected(path, real, rules) {
+	if (within(await realOrResolved(rules.downloadsDir), real)) return;
+	if (within(await realOrResolved(cacheRoot(rules.env)), real)) throw new Error(`${path} is in the Headless Client's cache, which holds the graph's decrypted contents.`);
+	const configFile = await realOrResolved(defaultConfigPath(rules.env));
+	const configDir = await realOrResolved(dirname(defaultConfigPath({
+		...rules.env,
+		ETHERPK_MCP_CONFIG: void 0
+	})));
+	if (real === configFile || within(configDir, real)) throw new Error(`${path} is the Headless Client's config, which holds its sign-in tokens.`);
+	const hidden = real.split(sep).find((part) => part.startsWith("."));
+	if (hidden) throw new Error(`${path} is hidden (${hidden}), where credentials and settings are kept. Copy it to an ordinary folder to upload it.`);
+}
+/** A local file as `upload_asset` reads it: an ordinary file, not refused above, within the size limit. */
+async function readLocalFile(path, rules) {
+	const real = await realpath(path);
+	await refuseProtected(path, real, rules);
+	const info = await stat(real);
+	if (!info.isFile()) throw new Error(`${path} is not a file.`);
+	if (info.size > 104857600) throw new Error(`${path} is larger than ${MAX_UPLOAD_BYTES / (1024 * 1024)} MiB.`);
+	const buffer = await readFile(real);
 	const bytes = new Uint8Array(new ArrayBuffer(buffer.byteLength));
 	bytes.set(buffer);
 	return {
@@ -15257,24 +15786,54 @@ async function readLocalFile(path) {
 		bytes
 	};
 }
+/** Names Windows reserves for devices, whatever the extension. */
+var RESERVED = /^(con|prn|aux|nul|com\d|lpt\d)$/i;
+var MAX_NAME_LENGTH = 120;
 /**
-* Write an asset's bytes under `directory` as `name`, never over a different file of the same
-* name: a second asset that happens to share a display name lands beside it with a suffix, so
-* an agent reading two `diagram.png`s from two pages gets both.
+* A file name for an asset's stored name. The stored name is metadata any collaborator can set,
+* so it is reduced to one plain file: the last path segment, letters, digits, marks, spaces and
+* `. _ - ( )` kept and everything else replaced, no leading dot (so never hidden, never `..`),
+* no trailing dot or space (Windows drops them), not a Windows device name, and short.
+*/
+function downloadName(name) {
+	let safe = (name.split(/[\\/]/).pop() ?? "").replace(/[^\p{L}\p{M}\p{N} ._()-]/gu, "_").replace(/^[.\s]+/, "").replace(/[.\s]+$/, "");
+	if (safe === "") return "asset";
+	if (RESERVED.test(safe.split(".")[0])) safe = `_${safe}`;
+	if (Array.from(safe).length <= MAX_NAME_LENGTH) return safe;
+	const dot = safe.lastIndexOf(".");
+	const ext = dot > 0 && safe.length - dot <= 20 ? safe.slice(dot) : "";
+	return Array.from(safe.slice(0, safe.length - ext.length)).slice(0, MAX_NAME_LENGTH - ext.length).join("") + ext;
+}
+/** Whether `path` is an ordinary file (not a link) holding exactly `bytes`. */
+async function holds(path, bytes) {
+	const info = await lstat(path);
+	if (!info.isFile() || info.size !== bytes.byteLength) return false;
+	return (await readFile(path)).equals(bytes);
+}
+/**
+* Write an asset's bytes under `directory`, named by {@link downloadName}, and never over
+* anything already there: the write fails rather than replace a file or follow a link left in
+* its place, and the next candidate is tried. A second asset that shares a display name lands
+* beside the first with a suffix, so an agent reading two `diagram.png`s from two pages gets
+* both; the same bytes again answer the file already written.
 */
 async function writeDownload(directory, name, bytes) {
 	await mkdir(directory, { recursive: true });
-	const dot = name.lastIndexOf(".");
-	const stem = dot > 0 ? name.slice(0, dot) : name;
-	const ext = dot > 0 ? name.slice(dot) : "";
-	let candidate = join(directory, name);
-	for (let n = 2; existsSync(candidate); n += 1) {
-		const existing = await readFile(candidate);
-		if (existing.byteLength === bytes.byteLength && existing.every((b, i) => b === bytes[i])) return candidate;
-		candidate = join(directory, `${stem}-${n}${ext}`);
-	}
-	await writeFile(candidate, bytes);
-	return candidate;
+	const safe = downloadName(name);
+	const dot = safe.lastIndexOf(".");
+	const stem = dot > 0 ? safe.slice(0, dot) : safe;
+	const ext = dot > 0 ? safe.slice(dot) : "";
+	for (let n = 1; n <= 1e3; n += 1) {
+		const candidate = join(directory, n === 1 ? safe : `${stem}-${n}${ext}`);
+		try {
+			await writeFile(candidate, bytes, { flag: "wx" });
+			return candidate;
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
+		if (await holds(candidate, bytes)) return candidate;
+	}
+	throw new Error(`${directory} already holds a thousand files named like ${safe}.`);
 }
 /** UTF-16 units of document text returned before `truncated` is set. */
 var READ_TEXT_CAP = 2e5;
@@ -15516,7 +16075,7 @@ async function backlinks(graph, concept) {
 				kind: ref.kind,
 				line: ref.line,
 				breadcrumb: ref.breadcrumb,
-				text: ref.kind === "block" ? ref.subtree.map((node) => node.label).join("\n") : ref.context?.text ?? ""
+				text: ref.kind === "block" ? ref.subtree.map((node) => node.text).join("\n") : ref.context?.text ?? ""
 			}))
 		}))
 	};
@@ -15821,7 +16380,10 @@ async function uploadAsset(graph, args) {
 	if (!args.path || args.path.trim() === "") throw new ToolError("invalid_argument", "path must name a file on this machine.");
 	let file;
 	try {
-		file = await readLocalFile(args.path.trim());
+		file = await readLocalFile(args.path.trim(), {
+			env: process.env,
+			downloadsDir: assets.downloadsDir
+		});
 	} catch (error) {
 		throw new ToolError("invalid_argument", `Cannot read "${args.path}": ${error instanceof Error ? error.message : String(error)}`);
 	}
@@ -15866,8 +16428,15 @@ async function readAsset(graph, args) {
 	if (!documents) throw new ToolError("asset_not_found", `No document you can read references "${displayNameOf(ref)}", so it is not available here.`);
 	const asset = await assets.store.readBytes(ref);
 	if (!asset) throw new ToolError("asset_not_found", `The graph does not hold "${displayNameOf(ref)}" (the reference may be broken).`);
+	let directory;
+	try {
+		directory = await folderUnder(assets.downloadsDir, args.out_dir, ".");
+	} catch (error) {
+		if (error instanceof FolderRefused) throw new ToolError("invalid_argument", error.message);
+		throw error;
+	}
 	return {
-		path: await writeDownload(args.out_dir?.trim() || assets.downloadsDir, asset.name || displayNameOf(ref), asset.bytes),
+		path: await writeDownload(directory, asset.name || displayNameOf(ref), asset.bytes),
 		name: asset.name || displayNameOf(ref),
 		type: asset.type,
 		bytes: asset.bytes.byteLength,
@@ -16418,15 +16987,25 @@ function hostOf(host) {
 		cmd: host?.cmd ?? "etherpk-mcp"
 	};
 }
+/** The graph's downloads directory: every folder these tools write to, or read a theme back from, is under it. */
+function downloadsOf(graph) {
+	return graph.assets?.downloadsDir ?? join(process.cwd(), "etherpk-downloads");
+}
+/** A folder under the downloads directory, or the tool's refusal. */
+async function toolFolder(graph, requested, fallback) {
+	try {
+		return await folderUnder(downloadsOf(graph), requested, fallback);
+	} catch (error) {
+		if (error instanceof FolderRefused) throw new ToolError("invalid_argument", error.message);
+		throw error;
+	}
+}
 async function settle(graph) {
 	const result = await graph.settle();
 	if (!result.settled) throw new ToolError("not_settled", result.message);
 }
-async function fetchText(url) {
-	const response = await fetch(url);
-	if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
-	return response.text();
-}
+/** A url theme's files, from public https hosts only (see public-fetch.ts). */
+var fetchText = (url) => fetchPublicText(url);
 /** The publications whose saved mapping names a theme: what makes it undeletable. */
 async function publicationsUsing(graph, themeId) {
 	const { source } = await graph.publishing.readSource();
@@ -16523,12 +17102,11 @@ async function readTheme(graph, args) {
 	await graph.store.refresh();
 	const ref = args.ref.trim();
 	const { source, files, theme } = await filesOf(graph, ref);
-	const folder = resolve(args.out_dir?.trim() || join(graph.assets?.downloadsDir ?? join(process.cwd(), "etherpk-downloads"), "themes", ref.replace(/[^A-Za-z0-9._-]/g, "_")));
+	const folder = await toolFolder(graph, args.out_dir, join("themes", ref.replace(/[^A-Za-z0-9._-]/g, "_")));
+	const site = nodeSiteFolder(folder);
 	const written = [];
 	for (const [path, text] of [...files.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-		const full = join(folder, ...path.split("/"));
-		await mkdir(dirname(full), { recursive: true });
-		await writeFile(full, text);
+		await site.writeFile(path, text);
 		written.push({
 			path,
 			bytes: Buffer.byteLength(text)
@@ -16680,22 +17258,43 @@ async function deleteThemeFile(graph, args) {
 		errors: validationOf(after)
 	};
 }
-/** Every allowed file under a directory, as the theme's whole file set. */
-async function filesUnder(dir) {
-	const base = resolve(dir);
+/** Bounds on a theme folder: far beyond a real theme, and short of a whole disk. */
+var THEME_FOLDER_LIMITS = {
+	files: 500,
+	depth: 6,
+	fileBytes: 1024 * 1024,
+	totalBytes: 8 * 1024 * 1024
+};
+/**
+* Every allowed file under a directory, as the theme's whole file set. Symbolic links are not
+* followed, so a folder cannot pull in a file from elsewhere on disk, and the walk stops at the
+* limits above rather than reading whatever tree it was pointed at.
+*/
+async function filesUnder(base) {
 	const files = /* @__PURE__ */ new Map();
-	const walk = async (at) => {
+	let seen = 0;
+	let total = 0;
+	const walk = async (at, depth) => {
+		if (depth > THEME_FOLDER_LIMITS.depth) return;
 		for (const entry of await readdir(at, { withFileTypes: true })) {
+			if (entry.isSymbolicLink()) continue;
 			const full = join(at, entry.name);
 			if (entry.isDirectory()) {
-				if (entry.name !== ".git" && entry.name !== "node_modules") await walk(full);
+				if (entry.name !== ".git" && entry.name !== "node_modules") await walk(full, depth + 1);
 				continue;
 			}
+			if (!entry.isFile()) continue;
+			if (++seen > THEME_FOLDER_LIMITS.files) throw new Error(`it holds more than ${THEME_FOLDER_LIMITS.files} files`);
 			const path = relative(base, full).split(sep).join("/");
-			if (isThemeFilePath(path)) files.set(path, await readFile(full, "utf8"));
+			if (!isThemeFilePath(path)) continue;
+			const { size } = await lstat(full);
+			if (size > THEME_FOLDER_LIMITS.fileBytes) throw new Error(`${path} is larger than ${THEME_FOLDER_LIMITS.fileBytes} bytes`);
+			total += size;
+			if (total > THEME_FOLDER_LIMITS.totalBytes) throw new Error(`its theme files come to more than ${THEME_FOLDER_LIMITS.totalBytes} bytes`);
+			files.set(path, await readFile(full, "utf8"));
 		}
 	};
-	await walk(base);
+	await walk(base, 0);
 	return files;
 }
 /**
@@ -16706,9 +17305,11 @@ async function filesUnder(dir) {
 async function importThemeFolder(graph, args) {
 	await graph.store.refresh();
 	const theme = await requireEditable(graph, args.id.trim());
+	if (!args.dir?.trim()) throw new ToolError("invalid_argument", "dir must name the theme folder, as read_theme returned it.");
+	const dir = await toolFolder(graph, args.dir, "");
 	let files;
 	try {
-		files = await filesUnder(args.dir);
+		files = await filesUnder(dir);
 	} catch (error) {
 		throw new ToolError("invalid_argument", `Cannot read "${args.dir}": ${error instanceof Error ? error.message : String(error)}`);
 	}
@@ -16745,8 +17346,8 @@ async function deleteTheme(graph, args) {
 /**
 * Render a theme to a folder on this machine and say where: the publication's real site when
 * one is named, the sample site the Theme editor previews over otherwise. A preview is scratch,
-* not a [[Publish Folder]]: the default location is under the graph's downloads directory and is
-* emptied first; a named `out_dir` is written into as it is. With `screenshots`, the browser
+* not a [[Publish Folder]]: it is always under the graph's downloads directory, the default folder
+* there is emptied first, and a named `out_dir` (also under it) is written into as it is. With `screenshots`, the browser
 * photographs the front page and the first other page at desktop and phone widths, so the agent
 * can look at what it changed.
 */
@@ -16779,7 +17380,7 @@ async function previewTheme(graph, args, host) {
 		});
 		const { bundle, report } = await publishPublication(source, publication, environment);
 		const scratch = !args.out_dir?.trim();
-		const folder = resolve(args.out_dir?.trim() || join(graph.assets?.downloadsDir ?? join(process.cwd(), "etherpk-downloads"), "previews", themeRef.replace(/[^A-Za-z0-9._-]/g, "_")));
+		const folder = await toolFolder(graph, args.out_dir, join("previews", themeRef.replace(/[^A-Za-z0-9._-]/g, "_")));
 		if (scratch) await rm(folder, {
 			recursive: true,
 			force: true
@@ -16810,12 +17411,10 @@ async function previewTheme(graph, args, host) {
 		await renderer?.dispose();
 	}
 }
+/** The rendered site into the folder, through the writer `publish` uses: no path may leave the folder. */
 async function writeBundle(folder, bundle) {
-	for (const [path, content] of bundle) {
-		const full = join(folder, ...path.split("/"));
-		await mkdir(dirname(full), { recursive: true });
-		await writeFile(full, content);
-	}
+	const site = nodeSiteFolder(folder);
+	for (const [path, content] of bundle) await site.writeFile(path, content);
 }
 /** The front page and the first other page, desktop and phone, as PNGs beside the site. */
 async function photograph(env, folder, pages) {
@@ -16825,12 +17424,16 @@ async function photograph(env, folder, pages) {
 		const shots = [];
 		const targets = ["index.html", ...pages.filter((p) => p !== "index.html" && p !== "404.html").slice(0, 1)];
 		for (const page of targets) for (const width of [1280, 390]) {
-			const context = await browser.newContext({ viewport: {
-				width,
-				height: width === 390 ? 844 : 800
-			} });
+			const context = await browser.newContext({
+				viewport: {
+					width,
+					height: width === 390 ? 844 : 800
+				},
+				offline: true
+			});
+			await context.route("**/*", (route) => previewRequestAllowed(route.request().url(), folder) ? route.continue() : route.abort());
 			const tab = await context.newPage();
-			await tab.goto(`file://${join(folder, page)}`, { waitUntil: "load" });
+			await tab.goto(pathToFileURL(join(folder, page)).href, { waitUntil: "load" });
 			const out = join(folder, `preview-${page.replace(/\.html$/, "")}-${width}.png`);
 			await tab.screenshot({
 				path: out,
@@ -16910,7 +17513,7 @@ function createMcpServer(graph, info) {
 		"Start with graph_info to see what you are connected to. read_documents reads several documents in one call; tasks lists tasks and set_task changes one (status, priority, due and scheduled dates) by document and line.",
 		"Publishing: list_publications shows the publications this graph defines (a publication is a page whose frontmatter defines it; its outline is the site navigation) and the public documents none takes; a document is on a site when its frontmatter has public: true and names the publication in publications. create_publication and update_publication change the settings; publish writes the site into the publish folder the user set for it on this machine with the etherpk-mcp publish command (the tool cannot choose a folder) and returns the report. Diagrams need a browser the user installs once with \"diagrams setup\".",
 		"Themes: a publication's look is a theme - Mustache templates, a stylesheet, a script and a manifest. list_themes shows the bundled ones (read-only) and the graph's own; read_theme writes a theme's files to a folder on this machine to read and edit; customise_publication_theme copies a publication's bundled theme into the graph and points the publication at the copy (create_theme copies any theme); write_theme_file, delete_theme_file and import_theme_folder change a graph theme; preview_theme renders a theme to a folder (with screenshots when a browser is set up) to check before publish. For a snippet such as an analytics script, an include slot (update_publication includes, e.g. head) filled by a page may be lighter than a theme copy.",
-		"Images and files are assets: upload_asset adds a file from this machine and returns the markdown to paste into a document; read_asset writes an asset to a local file you can open; list_assets shows the assets documents reference. An asset is available only where a document you can read references it (or you uploaded it this session).",
+		"Images and files are assets: upload_asset adds a file from this machine and returns the markdown to paste into a document; read_asset writes an asset to a local file you can open; list_assets shows the assets documents reference. An asset is available only where a document you can read references it (or you uploaded it this session). read_asset, read_theme and preview_theme write under the graph's downloads directory and return the path; name a folder relative to it, never elsewhere.",
 		"The user documentation is at https://docs.etherpk.com."
 	].join("\n") });
 	server.registerTool("list_documents", {
@@ -17069,18 +17672,18 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => setFrontmatter(graph, args)));
 	server.registerTool("upload_asset", {
 		title: "Upload an asset",
-		description: "Add a file on this machine (an image, a PDF, any file) to the graph as an asset. Returns the reference and the markdown to paste into a document (an image tag for an image, a link otherwise). Bytes the graph already holds are not stored twice: the result then says reused: true and points at the existing asset. The file is stored as it is, without image optimisation. Refused with error \"asset_refused\" when the server declines it on a quota.",
+		description: "Add a file on this machine (an image, a PDF, any file) to the graph as an asset. Returns the reference and the markdown to paste into a document (an image tag for an image, a link otherwise). Bytes the graph already holds are not stored twice: the result then says reused: true and points at the existing asset. The file is stored as it is, without image optimisation. Refused with error \"invalid_argument\" for a folder, a file over 100 MiB, a hidden file or one in a hidden folder (.ssh, .env), and the Headless Client's own config and cache; with error \"asset_refused\" when the server declines it on a quota.",
 		inputSchema: {
-			path: z.string().min(1).describe("Absolute path of the file on this machine."),
+			path: z.string().min(1).describe("Absolute path of an ordinary file on this machine."),
 			name: z.string().min(1).optional().describe("The name to store it under; the file's own name by default.")
 		}
 	}, async (args) => run(() => uploadAsset(graph, args)));
 	server.registerTool("read_asset", {
 		title: "Read an asset",
-		description: "Write an asset's bytes to a file on this machine and return the path, so you can open or view it. Pass the reference as a document shows it (\"../assets/<name>\") or the name alone. Available only where a document you can read references the asset (or you uploaded it this session); otherwise error \"asset_not_found\".",
+		description: "Write an asset's bytes to a file on this machine and return the path, so you can open or view it. Pass the reference as a document shows it (\"../assets/<name>\") or the name alone. Available only where a document you can read references the asset (or you uploaded it this session); otherwise error \"asset_not_found\". The file is written under the graph's downloads directory, named after the asset, and never over an existing file.",
 		inputSchema: {
 			ref: z.string().min(1),
-			out_dir: z.string().min(1).optional().describe("Directory to write into; the graph's downloads directory by default.")
+			out_dir: z.string().min(1).optional().describe("A folder under the graph's downloads directory, relative to it; the downloads directory itself by default. A folder outside it is refused.")
 		}
 	}, async (args) => run(() => readAsset(graph, args)));
 	server.registerTool("list_assets", {
@@ -17141,7 +17744,7 @@ function createMcpServer(graph, info) {
 		description: "Write a theme's files (theme.json, layouts/, partials/, assets/) to a folder on this machine and return the path and file list, so you can read and edit them with your own tools. ref is a graph theme id, a bundled theme name or a url. Editing the folder changes nothing until write_theme_file or import_theme_folder brings it back; a bundled or url theme cannot be edited in place at all (create_theme copies it).",
 		inputSchema: {
 			ref: z.string().min(1),
-			out_dir: z.string().min(1).optional().describe("Directory to write into; the graph's downloads directory by default.")
+			out_dir: z.string().min(1).optional().describe("A folder under the graph's downloads directory, relative to it; themes/<ref> there by default. A folder outside it is refused.")
 		}
 	}, async (args) => run(() => readTheme(graph, args)));
 	server.registerTool("read_theme_file", {
@@ -17189,7 +17792,7 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => deleteThemeFile(graph, args)));
 	server.registerTool("import_theme_folder", {
 		title: "Import a theme folder",
-		description: "Replace a graph theme's files with a folder's contents - the way back after editing what read_theme wrote. Files the folder no longer has are removed from the theme; the folder needs a theme.json at its top. Validated afterwards.",
+		description: "Replace a graph theme's files with a folder's contents - the way back after editing what read_theme wrote. Files the folder no longer has are removed from the theme; the folder needs a theme.json at its top. dir is the folder read_theme returned, or another under the graph's downloads directory; a folder outside it is refused, and symbolic links in it are skipped. Validated afterwards.",
 		inputSchema: {
 			id: z.string().min(1),
 			dir: z.string().min(1)
@@ -17202,7 +17805,7 @@ function createMcpServer(graph, info) {
 	}, async (args) => run(() => deleteTheme(graph, args)));
 	server.registerTool("preview_theme", {
 		title: "Preview a theme",
-		description: "Render a theme to a folder on this machine and return where: a publication's real pages when a publication is given (with its own theme, or the theme named), or a sample site covering every construct when only a theme is given. Open the HTML to check markup and styles. With screenshots: true and a browser set up (diagrams setup or ETHERPK_CHROMIUM), the front page and one content page are photographed at desktop and phone widths as PNGs you can view. A preview is scratch, not the publish folder.",
+		description: "Render a theme to a folder on this machine and return where: a publication's real pages when a publication is given (with its own theme, or the theme named), or a sample site covering every construct when only a theme is given. Open the HTML to check markup and styles. With screenshots: true and a browser set up (diagrams setup or ETHERPK_CHROMIUM), the front page and one content page are photographed at desktop and phone widths as PNGs you can view. A preview is scratch, not the publish folder. The page loads nothing from the network while it is photographed. out_dir is a folder under the graph's downloads directory (previews/<name> there by default); a folder outside it is refused.",
 		inputSchema: {
 			theme: z.string().min(1).optional(),
 			publication: z.string().min(1).optional(),
@@ -17252,9 +17855,18 @@ function standalone(bytes) {
 	copy.set(bytes);
 	return copy;
 }
+/**
+* `name` as one file of `folder`, or a refusal. The store passes names that came from documents
+* (an asset reference decodes to one), and `join` would follow a `..` or a separator out of the
+* graph; the browser's directory handles refuse such names, and this keeps the two adapters alike.
+*/
+function fileIn(folder, name) {
+	if (!isSingleFileName(name)) throw new Error(`"${name}" is not a file name.`);
+	return join(folder, name);
+}
 function createNodeDirectoryAdapter(root) {
 	const dir = resolve(root);
-	const path = (subdir, name) => join(dir, subdir, name);
+	const path = (subdir, name) => fileIn(join(dir, subdir), name);
 	/**
 	* The file's mtime as integer milliseconds, as the browser's `File.lastModified` is. Node's
 	* `mtimeMs` is a float built from seconds plus nanoseconds, and on some filesystems the
@@ -17335,7 +17947,7 @@ function createNodeDirectoryAdapter(root) {
 			for (const subdir of SUBDIRS) await mkdir(join(dir, subdir), { recursive: true });
 		},
 		async readRootFile(name) {
-			const file = join(dir, name);
+			const file = fileIn(dir, name);
 			let text;
 			try {
 				text = await readFile(file, "utf8");
@@ -17349,7 +17961,7 @@ function createNodeDirectoryAdapter(root) {
 			};
 		},
 		async writeRootFile(name, text) {
-			const file = join(dir, name);
+			const file = fileIn(dir, name);
 			await writeFile(file, text, "utf8");
 			return {
 				text,
@@ -17462,9 +18074,9 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
   ${CMD} diagrams status
       Which browser a publish would use, if any.
 
-This machine can be signed in to several Sync Servers at once (a self-hosted one beside the
-managed service, say); --sync-server says which one a command means, and can be left out
-while only one is signed in. The config file is ${defaultConfigPath()} (override with
+This machine can be signed in to several Sync Servers at once; --sync-server says which one
+a command means, and can be left out while only one is signed in. The config file is
+${defaultConfigPath()} (override with
 ETHERPK_MCP_CONFIG); cached graphs live under ~/.cache/etherpk/mcp (override with
 ETHERPK_MCP_CACHE_DIR).
 Docs: https://docs.etherpk.com/using-ai-agents-with-your-notes