@dev.fast/whiteboard 0.3.3 → 0.3.4-preview.20261019.125

package/dist/{stored-document-migration-CChxtFAy.js → stored-document-migration-dFbewRTG.js}

@@ -1,196 +1,12 @@
-import { f as isNumberValue, l as jsonValueSchema, m as isStringValue, n as isJsonObject } from "./src-X9phtB2j.js";
-import "./src-DsM3jO8G.js";
+import { d as isBooleanValue, f as isNumberValue, l as jsonValueSchema, m as isStringValue, n as isJsonObject } from "./src-X9phtB2j.js";
+import "./src-BiWNbcF_.js";
+import { a as commitLinkTarget, c as parseAnchor, d as selectionProblem, f as sourceAnchors, i as anchorSelection, r as anchorSchema, s as formatAnchor } from "./lens-selection-CyJapcsl.js";
 import { t as ReviewInputError } from "./input-error-OLgB_h31.js";
 import { z } from "zod";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { gfmFromMarkdown } from "mdast-util-gfm";
 import { mathFromMarkdown } from "mdast-util-math";
 import { gfm } from "micromark-extension-gfm";
-//#region src/viewed-coverage.ts
-const coverageSchema = z.object({
-	base: z.array(z.tuple([z.number().int().nonnegative(), z.number().int().nonnegative()])),
-	head: z.array(z.tuple([z.number().int().nonnegative(), z.number().int().nonnegative()]))
-});
-const emptyCoverage = () => ({
-	base: [],
-	head: []
-});
-function unionIntervals(ranges) {
-	const result = [];
-	for (const [start, end] of [...ranges].sort((a, b) => a[0] - b[0])) {
-		if (end <= start) continue;
-		const last = result.at(-1);
-		if (last && start <= last[1]) last[1] = Math.max(last[1], end);
-		else result.push([start, end]);
-	}
-	return result;
-}
-function intersectIntervals(left, right) {
-	const result = [];
-	const a = unionIntervals(left), b = unionIntervals(right);
-	let i = 0, j = 0;
-	while (i < a.length && j < b.length) {
-		const start = Math.max(a[i][0], b[j][0]), end = Math.min(a[i][1], b[j][1]);
-		if (start < end) result.push([start, end]);
-		if (a[i][1] < b[j][1]) i++;
-		else j++;
-	}
-	return result;
-}
-function subtractIntervals(left, right) {
-	const result = [];
-	const removed = unionIntervals(right);
-	for (const [start, end] of unionIntervals(left)) {
-		let cursor = start;
-		for (const [from, to] of removed) {
-			if (to <= cursor) continue;
-			if (from >= end) break;
-			if (from > cursor) result.push([cursor, from]);
-			cursor = Math.min(end, Math.max(cursor, to));
-		}
-		if (cursor < end) result.push([cursor, end]);
-	}
-	return result;
-}
-function updateCoverage(current, scope, viewed) {
-	const apply = (side) => viewed ? unionIntervals([...current[side], ...scope[side]]) : subtractIntervals(current[side], scope[side]);
-	return {
-		base: apply("base"),
-		head: apply("head")
-	};
-}
-function scopedCoverage(file, sources) {
-	if (!sources) return file.changed;
-	const side = (side) => intersectIntervals(file.changed[side], sources.flatMap((source) => source.side === side && source.file === (side === "base" ? file.previousPath ?? file.path : file.path) ? [[source.fromLine - 1, source.toLine]] : []));
-	return {
-		base: side("base"),
-		head: side("head")
-	};
-}
-function coverageSources(file, coverage = file.viewed) {
-	return ["base", "head"].flatMap((side) => coverage[side].map(([start, end]) => ({
-		side,
-		file: side === "base" ? file.previousPath ?? file.path : file.path,
-		fromLine: start + 1,
-		toLine: end
-	})));
-}
-//#endregion
-//#region src/lens-selection.ts
-const ANCHOR_FORMS = "\"head/path#L10-L24\" or \"base/path#L7\" (one side, lines 10–24 or line 7); across sides, GitHub diff style \"diff/path#L84-R90\" (L = base line, R = head line)";
-const sameSideAnchor = /^(head|base)\/(.+)#L(\d+)(?:-L(\d+))?$/;
-const crossSideAnchor = /^diff\/(.+)#([LR])(\d+)-([LR])(\d+)$/;
-/** An anchor's selection, as markdown source links write it too (without
-* their `review-source:` scheme). Undefined when it isn't one. */
-function parseAnchor(text) {
-	const same = sameSideAnchor.exec(text);
-	if (same) {
-		const side = same[1] === "base" ? "base" : "head";
-		return {
-			file: same[2],
-			start: {
-				side,
-				line: Number(same[3])
-			},
-			end: {
-				side,
-				line: Number(same[4] ?? same[3])
-			}
-		};
-	}
-	const cross = crossSideAnchor.exec(text);
-	if (!cross || cross[2] === cross[4]) return void 0;
-	const side = (letter) => letter === "L" ? "base" : "head";
-	return {
-		file: cross[1],
-		start: {
-			side: side(cross[2]),
-			line: Number(cross[3])
-		},
-		end: {
-			side: side(cross[4]),
-			line: Number(cross[5])
-		}
-	};
-}
-/** Why a parsed selection can't be quoted, or undefined when it can. */
-function selectionProblem(selection) {
-	if (selection.start.line < 1 || selection.end.line < 1) return "Source lines count from 1.";
-	if (selection.start.side === selection.end.side && selection.start.line > selection.end.line) return "Source range ends before it starts.";
-	if (selection.pins && selection.pins.base === void 0 && (selection.start.side === "base" || selection.end.side === "base")) return "A base-side anchor needs base pins.";
-}
-const anchorSchema = z.string({ error: `Expected a source anchor: ${ANCHOR_FORMS}.` }).superRefine((text, context) => {
-	const selection = parseAnchor(text);
-	const problem = selection ? selectionProblem(selection) : `Use ${ANCHOR_FORMS} for a source anchor.`;
-	if (problem) context.addIssue({
-		code: "custom",
-		message: problem
-	});
-}).describe("head/path#L10-L24, base/path#L7, or diff/path#L84-R90");
-/** A stored anchor's selection, read at the pins of whatever holds it. */
-function anchorSelection(anchor, pins) {
-	const selection = parseAnchor(anchor);
-	if (!selection) throw new Error(`Not a source anchor: ${anchor}`);
-	return pins ? {
-		...selection,
-		pins
-	} : selection;
-}
-/** The anchor that writes a selection; its pins belong to its holder. */
-function formatAnchor(selection) {
-	const { file, start, end } = selection;
-	if (start.side === end.side) return start.line === end.line ? `${start.side}/${file}#L${start.line}` : `${start.side}/${file}#L${start.line}-L${end.line}`;
-	const letter = (side) => side === "base" ? "L" : "R";
-	return `diff/${file}#${letter(start.side)}${start.line}-${letter(end.side)}${end.line}`;
-}
-/** Pins-less selections keep the key they always had. */
-function selectionKey(source) {
-	return JSON.stringify([
-		source.file,
-		source.start.side,
-		source.start.line,
-		source.end.side,
-		source.end.line,
-		...source.pins ? [sourcePinsKey(source.pins)] : []
-	]);
-}
-function sourcePinsKey(pins) {
-	return `${pins.repositoryId}:${pins.base ?? ""}:${pins.head}`;
-}
-/** The comparison a source's pins name: head alone means head against
-* itself. Reference coverage is grouped under this key on both sides. */
-function comparisonKey(pins) {
-	return `${pins.repositoryId}:${pins.base ?? pins.head}:${pins.head}`;
-}
-/** Navigation/quote anchors only; never use these as lens coverage. */
-function sourceAnchors(source) {
-	return ["head", "base"].flatMap((side) => {
-		const lines = [source.start, source.end].flatMap((endpoint) => endpoint.side === side ? [endpoint.line] : []);
-		if (!lines.length) return [];
-		const anchor = {
-			file: source.file,
-			side,
-			fromLine: Math.min(...lines),
-			toLine: Math.max(...lines)
-		};
-		if (source.pins) anchor.pins = source.pins;
-		return [anchor];
-	});
-}
-/** Resolve once against the renderer's rows. No matching or context expansion. */
-function resolveDiffSelection(source, rows, file) {
-	const locate = (endpoint) => rows.findIndex((row) => row[endpoint.side === "base" ? 0 : 1] === endpoint.line - 1);
-	const start = locate(source.start);
-	const end = locate(source.end);
-	if (start < 0 || end < start) throw new Error("Lens endpoints do not identify an ordered interval in this diff.");
-	const selected = rows.slice(start, end + 1);
-	return ["base", "head"].flatMap((side, index) => unionIntervals(selected.flatMap((row) => row[index] === null ? [] : [[row[index], row[index] + 1]])).map(([from, to]) => ({
-		file: side === "base" ? file.previousPath ?? file.path : file.path,
-		side,
-		fromLine: from + 1,
-		toLine: to
-	})));
-}
 /**
 * Check whether a character code is a markdown line ending.
 *
@@ -1036,7 +852,7 @@ const identity = { id: text$1.optional() };
 /** The repository and commits an element's anchors quote. A step, frame,
 * attachment or operation without them reads its block's; a block without
 * them reads its document's. */
-const elementPins = sourcePinsSchema.optional().describe("Pins for the anchors here; needed on the scratchpad.");
+const elementPins = sourcePinsSchema.optional().describe("Pins for the anchors here.");
 /** The strict schema for a block's own fields; id and type are added here. */
 function defineBlock(type, props) {
 	return z.strictObject({
@@ -1376,8 +1192,8 @@ const image = {
 const markdown = {
 	type: "markdown",
 	schema: defineBlock("markdown", {
-		markdown: text$1.describe("Safe Markdown. Repository file links must use [label](review-source:head/path#L10-L24) or review-source:base/path#L10-L24, with a repository-relative path and verified line numbers. Relative paths, absolute filesystem paths, and file/editor URLs are rejected. External links use https://, http://, or mailto:; document anchors use #heading."),
-		pins: sourcePinsSchema.optional().describe("Repository and commits this block's review-source links resolve against, instead of the document's pins.")
+		markdown: text$1.describe("Safe Markdown. Repository file links must use [label](whiteboard:source/head/path#L10-L24) or whiteboard:source/base/path#L10-L24, or whiteboard:source/<commit>/path#L10-L24 at any commit of the board's repository, with a repository-relative path and verified line numbers. Link another board as [label](whiteboard:board/<sessionId>) or one of its blocks as whiteboard:board/<sessionId>#<blockId>; both must exist. Relative paths, absolute filesystem paths, and file/editor URLs are rejected. External links use https://, http://, or mailto:; document anchors use #heading."),
+		pins: sourcePinsSchema.optional().describe("Repository and commits this block's whiteboard:source/ links resolve against, instead of the document's pins.")
 	})
 };
 //#endregion
@@ -1581,28 +1397,91 @@ function pinnedRepositoryIds(document) {
 	})) if (source.pins) ids.add(source.pins.repositoryId);
 	return ids;
 }
-const targets = (repository) => z.discriminatedUnion("kind", [z.strictObject({
-	kind: z.literal("worktree"),
-	...repository,
-	base: label.optional()
-}), z.strictObject({
-	kind: z.literal("commits"),
-	...repository,
-	head: label,
-	base: label.optional()
-})]);
+const targets = (repository) => z.discriminatedUnion("kind", [
+	z.strictObject({
+		kind: z.literal("project"),
+		...repository
+	}),
+	z.strictObject({
+		kind: z.literal("worktree"),
+		...repository,
+		base: label.optional()
+	}),
+	z.strictObject({
+		kind: z.literal("commits"),
+		...repository,
+		head: label,
+		base: label.optional()
+	})
+]);
 const reviewTargetSchema = targets({ repositoryId: label });
-/** How agents name a target: by the checkout's path, registered on acceptance. */
-const pathTargetSchema = targets({ repositoryPath: label });
+/** Targets as agents write them: a checkout path instead of a repository id,
+* plus a PR by URL or number. */
+const pathTargetSchema = z.discriminatedUnion("kind", [...targets({ repositoryPath: label }).options, z.strictObject({
+	kind: z.literal("pullRequest"),
+	repositoryPath: label,
+	pullRequest: z.union([label, z.number().int().positive()])
+})]);
 const unitTypes = /* @__PURE__ */ new Set([
 	"step",
 	"flow_node",
 	"flow_edge"
 ]);
 const isUnit = (element) => unitTypes.has(element.type);
+/** Rewrites old review-source: and review-trace: links to their whiteboard: form. */
+function canonicalLink(href) {
+	return href.replace(/^review-(source|trace):/i, (_, kind) => `whiteboard:${kind.toLowerCase()}/`);
+}
+/** Markdown link destinations and definitions that begin with `target`, a
+* regex source; the match's first group is what comes before it. */
+const linkDestination = (target) => new RegExp(String.raw`(\]\(\s*<?|^\s*\[[^\]\n]+\]:\s*<?)` + target, "gim");
+/** Every Markdown text in `value`, rewritten. */
+function rewriteMarkdown(value, rewrite) {
+	return JSON.parse(JSON.stringify(value), (key, field) => key === "markdown" && isStringValue(field) ? rewrite(field) : field);
+}
+const retiredLinks = linkDestination("review-(source|trace):");
+/** Rewrites old link prefixes in Markdown link destinations and definitions. */
+function respellLinks(markdown) {
+	return markdown.replace(retiredLinks, (_, before, kind) => `${before}whiteboard:${kind.toLowerCase()}/`);
+}
+/** Every Markdown text in `document` with its links spelled the current
+* way. */
+function respellDocumentLinks(document) {
+	return rewriteMarkdown(document, respellLinks);
+}
+function respellEditLinks(edit) {
+	return rewriteMarkdown(edit, respellLinks);
+}
+/** Parses whiteboard:board/<id> or whiteboard:board/<id>#<blockId>. */
+function boardLink(href) {
+	const match = /^whiteboard:board\/([^#/]+)(?:#(.+))?$/.exec(href);
+	if (!match) return void 0;
+	try {
+		const board = decodeURIComponent(match[1]);
+		return match[2] === void 0 ? { board } : {
+			board,
+			block: decodeURIComponent(match[2])
+		};
+	} catch {
+		return;
+	}
+}
+/** Every board link in a document. Malformed links are skipped; writes reject them. */
+function boardLinks(board, document) {
+	return elements(document).flatMap((element) => element.type === "markdown" ? [...markdownNodes(parseMarkdown(element.markdown))].flatMap((node) => {
+		const to = node.type === "link" ? boardLink(node.url ?? "") : void 0;
+		return to ? [{
+			from: {
+				board,
+				block: element.id
+			},
+			to
+		}] : [];
+	}) : []);
+}
 /** Inline trace quotes keep paragraph/list layout while using retained resources. */
 function traceQuoteLink(href) {
-	const match = /^review-trace:([^#]+)#(.+)$/.exec(href);
+	const match = /^whiteboard:trace\/([^#]+)#(.+)$/.exec(canonicalLink(href));
 	return match ? {
 		traceId: decodeURIComponent(match[1]),
 		eventId: decodeURIComponent(match[2])
@@ -1629,8 +1508,8 @@ function resourceReferences(document) {
 	return elements(document).flatMap((block) => {
 		if (block.type !== "markdown") return block.type === "image" || block.type === "trace_quote" || block.type === "software_map" ? [block] : [];
 		return [...markdownNodes(parseMarkdown(block.markdown))].flatMap((node) => {
-			if (node.type !== "link" || !node.url?.startsWith("review-trace:")) return [];
-			const quote = traceQuoteLink(node.url);
+			if (node.type !== "link" || !canonicalLink(node.url ?? "").startsWith("whiteboard:trace/")) return [];
+			const quote = traceQuoteLink(node.url ?? "");
 			if (!quote) throw new ReviewInputError("Invalid trace quote link.");
 			return [{
 				type: "trace_quote",
@@ -1645,7 +1524,7 @@ function resourceReferences(document) {
 * `tolerant` skips malformed Markdown source links instead of rejecting, for
 * content that is already stored.
 */
-function documentReferences(document, { tolerant = false, markdown = true } = {}) {
+function documentReferences(document, { tolerant = false, markdown = true, repositoryId } = {}) {
 	const reject = (message) => {
 		if (tolerant) return [];
 		throw new ReviewInputError(message);
@@ -1664,20 +1543,29 @@ function documentReferences(document, { tolerant = false, markdown = true } = {}
 		if (element.type === "markdown" && !markdown) return [];
 		if (element.type === "markdown") return [...markdownNodes(parseMarkdown(element.markdown))].flatMap((node) => {
 			if (node.type !== "link") return [];
-			const href = node.url ?? "";
-			if (!/^review-source:/i.test(href)) {
-				if (href.startsWith("review-trace:")) return [];
+			const href = canonicalLink(node.url ?? "");
+			if (!href.startsWith("whiteboard:source/")) {
+				if (href.startsWith("whiteboard:trace/")) return [];
+				if (href.startsWith("whiteboard:board/")) return boardLink(href) ? [] : reject(`Use whiteboard:board/<sessionId> or whiteboard:board/<sessionId>#<blockId> to link a board, in block ${element.id}.`);
 				if (/^(?:https?:\/\/|mailto:|#)/i.test(href)) return [];
-				return reject(`Unsupported Markdown link ${JSON.stringify(href)} in block ${element.id}. Use [label](review-source:head/path#L10-L24) or review-source:base/path#L10-L24 for repository files, or review-source:diff/path#L84-R90 across sides, with a repository-relative path and verified line numbers. External links must use https://, http://, or mailto:; document anchors use #heading.`);
+				return reject(`Unsupported Markdown link ${JSON.stringify(href)} in block ${element.id}. Use [label](whiteboard:source/head/path#L10-L24) or whiteboard:source/base/path#L10-L24 for repository files, whiteboard:source/diff/path#L84-R90 across sides, or whiteboard:source/<commit>/path#L10-L24 at a commit of the board's repository, with a repository-relative path and verified line numbers. Link another board as whiteboard:board/<sessionId>, or one of its blocks as whiteboard:board/<sessionId>#<blockId>. External links must use https://, http://, or mailto:; document anchors use #heading.`);
 			}
 			let target;
 			try {
-				target = decodeURIComponent(href.slice(14));
+				target = decodeURIComponent(href.slice(18));
 			} catch {
 				return reject("Invalid URL encoding in source link.");
 			}
+			const commit = commitLinkTarget(target);
+			if (commit) return repositoryId ? select(commit.anchor, {
+				repositoryId,
+				head: commit.commit
+			}).map((source) => ({
+				id: `${element.id}:${node.url}`,
+				source
+			})) : reject(`A commit link names a commit of the board's repository, and this board has none, in block ${element.id}.`);
 			const anchor = target.replace(/^(head|base|diff)\//i, (side) => side.toLowerCase());
-			if (!parseAnchor(anchor)) return reject("Use review-source:head/path#L10-L24 (or base, or diff/path#L84-R90 across sides) for a source link.");
+			if (!parseAnchor(anchor)) return reject("Use whiteboard:source/head/path#L10-L24 (or base, diff/path#L84-R90 across sides, or <commit>/path#L10-L24 at a commit of the board's repository) for a source link.");
 			return select(anchor, element.pins).map((source) => ({
 				id: `${element.id}:${node.url}`,
 				source
@@ -1738,6 +1626,58 @@ function documentReferences(document, { tolerant = false, markdown = true } = {}
 }
 /** All authored attachments, including code peeks, select the aligned diff. */
 const selectionReferences = documentReferences;
+const commitLinkDestination = linkDestination(String.raw`whiteboard:source\/([0-9a-f]{7,40})\/`);
+/** The commits a document's Markdown commit links name, as written. */
+function commitLinkCommits(document) {
+	const commits = /* @__PURE__ */ new Set();
+	JSON.stringify(document, (key, value) => {
+		if (key === "markdown" && isStringValue(value)) for (const match of value.matchAll(commitLinkDestination)) commits.add(match[2]);
+		return value;
+	});
+	return [...commits];
+}
+/** Rewrites the commits Markdown commit links name, as a short commit
+* becomes the full one on save. */
+function respellCommitLinks(document, commits) {
+	return rewriteMarkdown(document, (markdown) => markdown.replace(commitLinkDestination, (link, before, commit) => `${before}whiteboard:source/${commits.get(commit) ?? commit}/`));
+}
+/** Blocks that carry pins of their own for the references in them. */
+const pinnedBlockTypes = /* @__PURE__ */ new Set([
+	"markdown",
+	"code_peek",
+	"sequence",
+	"flow_diagram",
+	"call_stack_diff",
+	"database_lens"
+]);
+const sideLinkDestination = linkDestination(String.raw`whiteboard:source\/(head|base)\/`);
+/**
+* Makes every reference that reads at the document's pins carry them
+* itself, for a board about to lose its pins: Markdown head/ and base/
+* links become commit links, and a block whose references still lean on
+* the document's pins (any anchor, or a diff/ link) takes them as its own.
+* Nothing changes what it points at.
+*/
+function pinDocumentReferences(document, pins) {
+	const own = {
+		repositoryId: pins.repositoryId,
+		base: pins.base,
+		head: pins.head
+	};
+	const pinned = structuredClone(document);
+	for (const element of elements(pinned)) {
+		if (!pinnedBlockTypes.has(element.type)) continue;
+		const block = element;
+		if (block.pins) continue;
+		if (block.type === "markdown") block.markdown = respellLinks(block.markdown).replace(sideLinkDestination, (_, before, side) => `${before}whiteboard:source/${side.toLowerCase() === "base" ? pins.base : pins.head}/`);
+		if (documentReferences([block], { tolerant: true }).some((reference) => !reference.source.pins)) block.pins = own;
+	}
+	return pinned;
+}
+/** The repository a board's commit links read from: its target's. */
+function boardRepositoryId(board) {
+	return board.target?.repositoryId ?? board.pins?.repositoryId;
+}
 /** Per-side read coordinates for endpoint validation and retained source quotes. */
 function sourceReferences(document, options = {}) {
 	return selectionReferences(document, options).flatMap((ref) => sourceAnchors(ref.source).map((source) => ({
@@ -1746,8 +1686,10 @@ function sourceReferences(document, options = {}) {
 	})));
 }
 /** Includes lenses and maps without inline ranges. */
-function hasCodeReferences(review) {
-	return Boolean(sourceReferences(review.document).length || review.lenses?.length || resourceReferences(review.document).some((block) => block.type === "software_map"));
+/** Whether a board reads code at its own pins: a commit link or a block
+* with pins of its own names its commits itself. */
+function readsAtBoardPins(review) {
+	return Boolean(sourceReferences(review.document, { tolerant: true }).some((reference) => !reference.source.pins) || review.lenses?.length || resourceReferences(review.document).some((block) => block.type === "software_map"));
 }
 const documentSchema = z.array(blockSchema);
 /** Discriminated by type, like blockSchema, so a malformed insert reports
@@ -1910,20 +1852,27 @@ function adoptFlowUnits(document, allocate) {
 /** Mutate a private candidate. Only the store owns allocation and commits. */
 /** Assign server ids to an element tree that arrives without any. */
 function assignFreshIds(element, allocate) {
-	if (element.id !== void 0) throw new ReviewInputError("IDs are assigned by the server.");
-	element.id = allocate(idPrefix(element));
-	for (const child of children(element)) assignFreshIds(child, allocate);
+	assignIds(element, allocate, true);
+}
+/** Give ids to the parts of an element tree that have none, keeping the
+* rest: a person's save names the blocks it kept and leaves new ones bare. */
+function assignMissingIds(element, allocate) {
+	assignIds(element, allocate, false);
+}
+function assignIds(element, allocate, fresh) {
 	const assign = (item, prefix) => {
-		if (item.id !== void 0) throw new ReviewInputError("IDs are assigned by the server.");
-		item.id = allocate(prefix);
+		if (item.id === void 0) item.id = allocate(prefix);
+		else if (fresh) throw new ReviewInputError("IDs are assigned by the server.");
 	};
+	assign(element, idPrefix(element));
+	for (const child of children(element)) assignIds(child, allocate, fresh);
 	if (element.type === "call_stack_diff") for (const frame of [...element.base, ...element.head]) assign(frame, "frame");
 	if (element.type === "database_lens") for (const useCase of element.useCases) {
 		assign(useCase, "case");
 		for (const op of useCase.operations) assign(op, "operation");
 	}
 }
-function applyEdit(document, edit, allocate, options = {}) {
+function applyEdit(document, edit, allocate) {
 	adoptFlowUnits(document, allocate);
 	const locate = (id) => {
 		const find = (siblings) => {
@@ -1952,7 +1901,7 @@ function applyEdit(document, edit, allocate, options = {}) {
 		if (afterId === element.id) throw new ReviewInputError("An element cannot follow itself.");
 		if (afterId !== void 0 && !siblings.some((s) => s.id === afterId)) throw new ReviewInputError("afterId must identify a sibling.");
 		if (from) from.splice(from.indexOf(element), 1);
-		const index = afterId !== void 0 ? siblings.findIndex((s) => s.id === afterId) + 1 : !parent && !from && options.placement === "first" ? 0 : siblings.length;
+		const index = afterId === void 0 ? siblings.length : siblings.findIndex((s) => s.id === afterId) + 1;
 		siblings.splice(index, 0, element);
 	};
 	if (edit.type === "insert") {
@@ -2546,54 +2495,114 @@ z.strictObject({
 function migrateDiffSelections(input) {
 	return migrateNode(jsonValueSchema.parse(input));
 }
+/** Keys whose values held retired attachments. */
+const ATTACHMENT_KEYS = [
+	"source",
+	"peek",
+	"sources",
+	"contextSources",
+	"callSite"
+];
+/** A retired attachment as a selection, or undefined for anything else. */
+function retiredSelection(value) {
+	if (!isStringValue(value.file)) return void 0;
+	if (isNumberValue(value.fromLine) && isNumberValue(value.toLine)) {
+		const side = value.side ?? value.graph ?? "head";
+		return {
+			file: value.file,
+			start: {
+				side,
+				line: value.fromLine
+			},
+			end: {
+				side,
+				line: value.toLine
+			}
+		};
+	}
+	if (isJsonObject(value.start) && isJsonObject(value.end) && "baseLine" in value.start) {
+		const endpoint = (row) => isNumberValue(row.headLine) ? {
+			side: "head",
+			line: row.headLine
+		} : {
+			side: "base",
+			line: row.baseLine ?? null
+		};
+		return {
+			file: value.file,
+			start: endpoint(value.start),
+			end: endpoint(value.end)
+		};
+	}
+}
 function migrateNode(value, attachment = false) {
 	if (Array.isArray(value)) return value.map((child) => migrateNode(child, attachment));
 	if (!isJsonObject(value)) return value;
-	if (attachment && isStringValue(value.file)) {
-		if (isNumberValue(value.fromLine) && isNumberValue(value.toLine)) {
-			const side = value.side ?? value.graph ?? "head";
-			return {
-				file: value.file,
-				start: {
-					side,
-					line: value.fromLine
-				},
-				end: {
-					side,
-					line: value.toLine
-				}
-			};
-		}
-		if (isJsonObject(value.start) && isJsonObject(value.end) && "baseLine" in value.start) {
-			const endpoint = (row) => isNumberValue(row.headLine) ? {
-				side: "head",
-				line: row.headLine
-			} : {
-				side: "base",
-				line: row.baseLine
-			};
-			return {
-				file: value.file,
-				start: endpoint(value.start),
-				end: endpoint(value.end)
-			};
-		}
-	}
-	return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, migrateNode(child, [
-		"source",
-		"peek",
-		"sources",
-		"contextSources",
-		"callSite"
-	].includes(key))]));
+	const selection = attachment ? retiredSelection(value) : void 0;
+	if (selection) return selection;
+	return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, migrateNode(child, ATTACHMENT_KEYS.includes(key))]));
 }
 //#endregion
 //#region src/stored-document-migration.ts
 /** Upgrade a saved or shared Review document to the current block schema at the
 * read/import boundary. New edits use the strict schema and never accept these
-* retired forms. */
+* retired forms. One walk makes a fresh copy: retired attachments become
+* selections, anchors become strings, sections lose their status, and
+* Markdown links are spelled the current way. */
 function migrateStoredDocument(input) {
-	return anchorStrings(dropSectionStatus(migrateDiffSelections(input)));
+	return upgradeNode(input, {
+		attachment: false,
+		anchors: true
+	});
+}
+function upgradeNode(value, place) {
+	if (isStringValue(value) || isBooleanValue(value) || value === null) return value;
+	if (isNumberValue(value) && Number.isFinite(value)) return value;
+	if (Array.isArray(value)) return value.map((child) => upgradeNode(child, place));
+	if (!isJsonObject(value)) throw new TypeError("A document must be JSON.");
+	const selection = place.attachment ? retiredSelection(value) : void 0;
+	if (selection) return upgradeNode(selection, {
+		attachment: false,
+		anchors: false
+	});
+	const inherited = place.anchors ? value.pins ?? place.blockPins : void 0;
+	let pins;
+	const convert = (anchor) => {
+		if (isStringValue(anchor)) return anchor;
+		const parsed = selectionObjectSchema.safeParse(anchor);
+		if (!parsed.success) return anchor;
+		const { pins: own, ...anchorAt } = parsed.data;
+		if (own) pins = own;
+		return formatAnchor(anchorAt);
+	};
+	const entries = [];
+	for (const [key, child] of Object.entries(value)) {
+		if (key === "status" && value.type === "section") continue;
+		if (key === "markdown" && isStringValue(child)) {
+			entries.push([key, respellLinks(child)]);
+			continue;
+		}
+		const attachment = ATTACHMENT_KEYS.includes(key);
+		if (place.anchors && ANCHOR_KEYS.includes(key)) {
+			const anchors = upgradeNode(child, {
+				attachment,
+				anchors: false
+			});
+			entries.push([key, Array.isArray(anchors) ? anchors.map(convert) : convert(anchors)]);
+		} else entries.push([key, upgradeNode(child, {
+			attachment,
+			anchors: place.anchors,
+			blockPins: inherited
+		})]);
+	}
+	const upgraded = Object.fromEntries(entries);
+	if (pins !== void 0 && value.kind !== "ranges" && JSON.stringify(pins) !== JSON.stringify(place.blockPins)) upgraded.pins = pins;
+	return upgraded;
+}
+/** A stored document as the store reads it: retired forms upgraded, and
+* lens blocks lifted out to the snapshot's own lenses. */
+function readStoredDocument(input) {
+	return liftFileLenses(migrateStoredDocument(input));
 }
 /** Lenses saved before ranges were anchor strings. */
 function migrateStoredLenses(input) {
@@ -2640,14 +2649,6 @@ function anchorStrings(value, blockPins) {
 	if (pins !== void 0 && value.kind !== "ranges" && JSON.stringify(pins) !== JSON.stringify(blockPins)) migrated.pins = pins;
 	return migrated;
 }
-/** Sections once carried an optional `status` (pending, in_progress or
-* complete). The authoring lease is now the only signal of work in progress,
-* so versions saved before it was retired drop the field when read. */
-function dropSectionStatus(value) {
-	if (Array.isArray(value)) return value.map(dropSectionStatus);
-	if (!isJsonObject(value)) return value;
-	return Object.fromEntries(Object.entries(value).filter(([key]) => !(value.type === "section" && key === "status")).map(([key, child]) => [key, dropSectionStatus(child)]));
-}
 /** A saved `file_lens` block, from before lenses left the document. */
 const legacyFileLensSchema = z.object({
 	type: z.literal("file_lens"),
@@ -2686,4 +2687,4 @@ function liftFileLenses(document) {
 	};
 }
 //#endregion
-export { intersectIntervals as $, documentAdvice as A, requireVisibleSource as B, resourceReference as C, sourceReferences as D, selectionReferences as E, lensSchema as F, comparisonKey as G, markdownNodes as H, lensSelections as I, selectionKey as J, formatAnchor as K, SourceRangeError as L, UNCATEGORIZED_LENS_ID as M, applyLensEdit as N, summarizeEdit as O, lensEditSchema as P, emptyCoverage as Q, checkSourcePath as R, publishedEditSchema as S, reviewTargetSchema as T, parseMarkdown as U, sliceSourceRange as V, anchorSelection as W, coverageSchema as X, sourceAnchors as Y, coverageSources as Z, hasCodeReferences as _, defineSoftwareMap as a, pinnedRepositoryIds as b, traceSchema as c, applyEdit as d, scopedCoverage as et, assignFreshIds as f, explicitPins as g, elements as h, SoftwareModelValidationError as i, stepSources as j, checkReferences as k, textIncludesQuote as l, editSchema as m, migrateStoredDocument as n, unionIntervals as nt, normalizedSoftwareElementSchema as o, documentSchema as p, resolveDiffSelection as q, migrateStoredLenses as r, updateCoverage as rt, normalizedSoftwareRelationshipSchema as s, liftFileLenses as t, subtractIntervals as tt, anchorPins as u, isUnit as v, resourceReferences as w, pinsSchema as x, pathTargetSchema as y, fileLineRangeSchema as z };
+export { parseMarkdown as $, resourceReferences as A, stepSources as B, pathTargetSchema as C, publishedEditSchema as D, pinsSchema as E, selectionReferences as F, lensSelections as G, applyLensEdit as H, sourceReferences as I, fileLineRangeSchema as J, SourceRangeError as K, summarizeEdit as L, respellDocumentLinks as M, respellEditLinks as N, readsAtBoardPins as O, reviewTargetSchema as P, markdownText as Q, checkReferences as R, explicitPins as S, pinnedRepositoryIds as T, lensEditSchema as U, UNCATEGORIZED_LENS_ID as V, lensSchema as W, sliceSourceRange as X, requireVisibleSource as Y, markdownNodes as Z, boardRepositoryId as _, SoftwareModelValidationError as a, editSchema as b, normalizedSoftwareRelationshipSchema as c, adoptFlowUnits as d, anchorPins as f, boardLinks as g, assignMissingIds as h, readStoredDocument as i, respellCommitLinks as j, resourceReference as k, traceSchema as l, assignFreshIds as m, migrateStoredDocument as n, defineSoftwareMap as o, applyEdit as p, checkSourcePath as q, migrateStoredLenses as r, normalizedSoftwareElementSchema as s, liftFileLenses as t, textIncludesQuote as u, commitLinkCommits as v, pinDocumentReferences as w, elements as x, documentSchema as y, documentAdvice as z };