@shivaedev/work-board 0.11.0 → 0.12.0

package/src/server/metadata/problems.ts

@@ -0,0 +1,58 @@
+import { attentionProblems } from "./attentionProblems.ts";
+import type { MetadataDocument } from "./model.ts";
+import type { Diagnostic } from "./parse.ts";
+import { referencesOf } from "./referencesOf.ts";
+
+function referenceProblem(target: string, ids: ReadonlyMap<string, readonly MetadataDocument[]>): string | undefined {
+	const [id = "", criterion] = target.split("#");
+	const matches = ids.get(id);
+	if (!matches?.length) {
+		return `Unresolved reference ${target}.`;
+	}
+	if (matches.length > 1) {
+		return `Ambiguous reference ${target}; the ID is duplicated.`;
+	}
+	if (criterion && matches[0]?.parsed.fields.criteria?.filter((item) => item.id === criterion).length !== 1) {
+		return `Unresolved or duplicated criterion ${target}.`;
+	}
+	return undefined;
+}
+function criterionProblems(document: MetadataDocument): readonly Diagnostic[] {
+	const criteria = document.parsed.fields.criteria ?? [];
+	return criteria.flatMap((criterion, index) =>
+		criteria.filter((item) => item.id === criterion.id).length > 1
+			? [{ field: "criteria", line: document.parsed.lines[`criteria.${index}`] ?? 2, message: `Duplicate criterion ID ${criterion.id}.` }]
+			: [],
+	);
+}
+function referenceProblems(document: MetadataDocument, ids: ReadonlyMap<string, readonly MetadataDocument[]>): readonly Diagnostic[] {
+	const { lines } = document.parsed;
+	const references = referencesOf(document);
+	return references.flatMap((reference) => {
+		const message = referenceProblem(reference.target, ids);
+		return message ? [{ field: reference.field, line: lines[reference.key] ?? lines[reference.field] ?? 2, message }] : [];
+	});
+}
+export function metadataProblems(document: MetadataDocument, ids: ReadonlyMap<string, readonly MetadataDocument[]>, unavailable: readonly string[]) {
+	const { parsed } = document;
+	const problems = [...parsed.diagnostics, ...criterionProblems(document), ...attentionProblems(document)];
+	const matches = parsed.fields.id ? ids.get(parsed.fields.id) : undefined;
+	if (matches && matches.length > 1) {
+		problems.push({
+			field: "id",
+			line: parsed.lines.id ?? 2,
+			message: `Duplicate ID ${parsed.fields.id}: ${matches.map((item) => item.file).join(", ")}. No source is selected.`,
+		});
+	}
+	if (unavailable.length > 0) {
+		if (parsed.raw !== undefined) {
+			problems.push({
+				line: 1,
+				message: `Workspace index incomplete; could not read ${unavailable.join(", ")}. Identity and references cannot be validated completely.`,
+			});
+		}
+	} else {
+		problems.push(...referenceProblems(document, ids));
+	}
+	return problems;
+}

package/src/server/metadata/referencesOf.ts

@@ -0,0 +1,23 @@
+import type { MetadataDocument } from "./model.ts";
+
+export function referencesOf(document: MetadataDocument) {
+	const { fields } = document.parsed;
+	return [
+		...(fields.handoff ? [{ field: "handoff", key: "handoff.item", target: fields.handoff.item }] : []),
+		...(fields.question ? [{ field: "question", key: "question.item", target: fields.question.item }] : []),
+		...(fields.response ? [{ field: "response", key: "response.question", target: fields.response.question }] : []),
+		...(fields.response?.supersedes ? [{ field: "response", key: "response.supersedes", target: fields.response.supersedes }] : []),
+		...(fields.requestReceipt ? [{ field: "request_receipt", key: "request_receipt.question", target: fields.requestReceipt.question }] : []),
+		...(fields.requestReceipt?.response
+			? [{ field: "request_receipt", key: "request_receipt.response", target: fields.requestReceipt.response }]
+			: []),
+		...(fields.attention?.flatMap((request, index) =>
+			request.unblocks.map((target, targetIndex) => ({ field: "attention", key: `attention.${index}.unblocks.${targetIndex}`, target })),
+		) ?? []),
+		...(fields.relationships?.map((link, index) => ({ field: "relationships", key: `relationships.${index}.target`, target: link.target })) ?? []),
+		...(fields.items?.map((target, index) => ({ field: "items", key: `items.${index}`, target })) ?? []),
+		...(fields.evidence?.flatMap((item, index) =>
+			item.criterion ? [{ field: "evidence", key: `evidence.${index}.criterion`, target: item.criterion }] : [],
+		) ?? []),
+	];
+}

package/src/server/metadata/updateModel.ts

@@ -0,0 +1,44 @@
+import type { MetadataDocument, MetadataModel } from "./model.ts";
+import { metadataProblems } from "./problems.ts";
+import { referencesOf } from "./referencesOf.ts";
+
+export function updateModel(
+	previous: MetadataModel | undefined,
+	documents: readonly MetadataDocument[],
+	unavailable: readonly string[],
+	rootFile?: string,
+): MetadataModel {
+	const groups = new Map<string, MetadataDocument[]>();
+	for (const document of documents) {
+		const id = document.parsed.fields.id;
+		if (id) {
+			const matches = groups.get(id) ?? [];
+			matches.push(document);
+			groups.set(id, matches);
+		}
+	}
+	const ids = new Map<string, readonly MetadataDocument[]>();
+	const changed = new Set<string>();
+	for (const id of new Set([...groups.keys(), ...(previous?.ids.keys() ?? [])])) {
+		const before = previous?.ids.get(id) ?? [];
+		const after = groups.get(id);
+		const affected = !after || before.length !== after.length || before.some((document, index) => document !== after[index]);
+		if (affected) {
+			changed.add(id);
+		}
+		if (after) {
+			ids.set(id, affected ? after : before);
+		}
+	}
+	const before = new Map(previous?.documents.map((document) => [document.file, document]));
+	const incomplete = unavailable.join("\0") !== previous?.unavailable.join("\0");
+	const diagnostics = new Map(
+		documents.map((document) => {
+			const dependent = referencesOf(document).some((reference) => changed.has(reference.target.split("#")[0] ?? ""));
+			const existing = previous?.diagnostics.get(document.file);
+			const affected = incomplete || before.get(document.file) !== document || changed.has(document.parsed.fields.id ?? "") || dependent;
+			return [document.file, !affected && existing ? existing : metadataProblems(document, ids, unavailable)] as const;
+		}),
+	);
+	return { diagnostics, documents, ids, rootFile, unavailable };
+}

package/src/server/navigation/model.ts

@@ -0,0 +1,79 @@
+import { type Navigation, type NavigationFile, NavigationFolder } from "#browser/navigation/schema.ts";
+import { fileUrl } from "#files/url.ts";
+import { fleetRecords, inboxItems } from "#server/attention/inbox.ts";
+import type { MarkdownFile } from "#server/files/list.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+
+export function inboxCount(snapshot?: Snapshot): number | null {
+	return !snapshot || snapshot.unavailable.length > 0 ? null : inboxItems(snapshot).length;
+}
+
+function fileData(file: MarkdownFile, current: string): NavigationFile {
+	return {
+		current: file.path === current,
+		href: fileUrl(file.path),
+		modified: file.modified,
+		name: file.path.slice(file.path.lastIndexOf("/") + 1).replace(/\.md$/u, ""),
+		path: file.path,
+	};
+}
+
+function homeData(file: string, snapshot: Snapshot | undefined) {
+	const id = snapshot?.documents.find((document) => document.file === file)?.parsed.fields.id;
+	const unique = id !== undefined && snapshot?.unavailable.length === 0 && snapshot.model.ids.get(id)?.length === 1;
+	return { file, ...(unique ? { identity: id } : {}) };
+}
+
+interface Branch {
+	active: boolean;
+	count: number;
+	readonly files: NavigationFile[];
+	readonly folders: Map<string, Branch>;
+	readonly name: string;
+	readonly path: string;
+}
+
+function branch(path: string, name: string): Branch {
+	return { active: false, count: 0, files: [], folders: new Map(), name, path };
+}
+
+function folderData(folder: Branch): NavigationFolder {
+	return new NavigationFolder({
+		...folder,
+		folders: [...folder.folders].sort(([left], [right]) => left.localeCompare(right)).map(([, child]) => folderData(child)),
+	});
+}
+
+export function navigationData(files: readonly MarkdownFile[], current: string, home: string | undefined, snapshot?: Snapshot): Navigation {
+	const generated = snapshot ? fleetRecords(snapshot.model) : new Set<string>();
+	const records = files.filter((file) => generated.has(file.path)).map((file) => fileData(file, current));
+	const visible = files.filter((file) => !generated.has(file.path));
+	const root = branch("", "");
+	const ordered = [
+		...visible.filter((file) => file.path === home),
+		...visible.filter((file) => file.path !== home).toSorted((left, right) => left.path.localeCompare(right.path)),
+	];
+	for (const file of ordered) {
+		let parent = root;
+		parent.count += 1;
+		parent.active ||= file.path === current;
+		const parts = file.path === home ? [] : file.path.split("/").slice(0, -1);
+		for (const name of parts) {
+			let child = parent.folders.get(name);
+			if (child === undefined) {
+				child = branch(parent.path === "" ? name : `${parent.path}/${name}`, name);
+				parent.folders.set(name, child);
+			}
+			child.count += 1;
+			child.active ||= file.path === current;
+			parent = child;
+		}
+		parent.files.push(fileData(file, current));
+	}
+	return {
+		...(home === undefined ? {} : { home: homeData(home, snapshot) }),
+		inboxCount: inboxCount(snapshot),
+		records: { active: records.some((file) => file.current), count: records.length, files: records },
+		tree: folderData(root),
+	};
+}

package/src/server/page/attentionDetails.ts

@@ -0,0 +1,26 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { managedRequestReceipt } from "#server/attention/managedRequestReceipt.ts";
+import { attentionSource } from "#server/attention/requests.ts";
+import { identityUrl } from "#server/metadata/links.ts";
+import type { MetadataModel } from "#server/metadata/model.ts";
+import type { ParsedMetadata } from "#server/metadata/parse.ts";
+import { referenceHtml } from "./metadataLinks.ts";
+
+export function attentionDetails(parsed: ParsedMetadata, file: string, model: MetadataModel): string {
+	const requests = parsed.fields.attention ?? [];
+	if (requests.length === 0) {
+		return "";
+	}
+	return `<h3>Recorded attention requests</h3><p>Open/closed is source state. Closing a request does not establish acceptance or record an answer.</p><ul>${requests
+		.map((request, index) => {
+			const receipt = managedRequestReceipt({ file, parsed }, request, model);
+			const acknowledged = receipt
+				? `<p>Managed request acknowledged: ${receipt.disposition}. Source state remains ${escapeHtml(request.state)}. This receipt does not establish acceptance.</p><p>Reviewed question: ${referenceHtml(receipt.question, receipt.question, model)}</p>`
+				: "";
+			const respond = receipt
+				? ""
+				: `<a href="/_board/respond?item=${encodeURIComponent(parsed.fields.id ?? "")}&amp;request=${encodeURIComponent(request.id)}">Respond to this request</a> · `;
+			return `<li id="${attentionSource({ file, parsed }, index)}" tabindex="-1"><b>${escapeHtml(request.kind)} · ${escapeHtml(request.id)} · ${escapeHtml(request.state)}</b>${acknowledged}<p>${escapeHtml(request.reason)}</p><p>Response needed from: ${request.responseFrom.map(escapeHtml).join(", ")}</p><p>Recorded to unblock: ${request.unblocks.map((target) => referenceHtml(target, target, model)).join(", ")}</p><p>${respond}<a href="${identityUrl(parsed.fields.id ?? "")}">Reviewed item</a></p><p>Source: ${escapeHtml(file)}:${parsed.lines[`attention.${index}`] ?? parsed.lines.attention ?? 2}</p></li>`;
+		})
+		.join("")}</ul>`;
+}

package/src/server/page/backlinksHtml.ts

@@ -0,0 +1,18 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { backlinksOf } from "#server/metadata/backlinks.ts";
+import type { MetadataModel } from "#server/metadata/model.ts";
+import { relationshipLabel } from "#server/metadata/relationshipLabel.ts";
+import { documentReference } from "./metadataLinks.ts";
+
+export function backlinksHtml(file: string, model: MetadataModel): string {
+	const links = backlinksOf(file, model);
+	if (links.length === 0) {
+		return "";
+	}
+	const entries = [...new Map(links.map((link) => [`${link.file}:${link.kind}:${link.line ?? ""}`, link])).values()];
+	const incomplete =
+		model.unavailable.length > 0
+			? "<p>Available source references only; unreadable files prevent complete backlink and identity validation.</p>"
+			: "";
+	return `<section class="work-context" aria-label="Source backlinks"><details data-key="work-backlinks"><summary>Referenced by (${entries.length})</summary>${incomplete}<ul>${entries.map((link) => `<li>${escapeHtml(relationshipLabel(link.kind))}: <a href="${escapeHtml(documentReference(link.file, model))}">${escapeHtml(link.file)}${link.line === undefined ? "" : `:${link.line}`}</a></li>`).join("")}</ul><p>These are explicit source links, not inferred blockers or workflow rules.</p></details></section>`;
+}

package/src/server/page/boardHtml.ts

@@ -0,0 +1,55 @@
+import { Effect } from "effect";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { documentHeadings } from "#render/documentHeadings.ts";
+import { type Board, countsOf, type Section } from "#server/render/board.ts";
+import { renderMarkdown } from "#server/render/markdown.ts";
+import { readingTools } from "./readingTools.ts";
+import { updated } from "./updated.ts";
+
+function counts(board: Board): string {
+	return countsOf(board)
+		.map(({ count, title }) => `<span><b>${count}</b> ${escapeHtml(title.toLowerCase())}</span>`)
+		.join(" · ");
+}
+
+type Render = (fragment: string) => ReturnType<typeof renderMarkdown>;
+
+const section = Effect.fn("WorkBoard.section")(function* ({ heading, items, notes }: Section, render: Render) {
+	const title = yield* render(heading);
+	const note = notes === "" ? "" : `<div class="notes">${yield* render(notes)}</div>`;
+	const rendered = yield* Effect.forEach(items, (item) => Effect.map(render(item), (html) => `<article class="item">${html}</article>`));
+	return `<section>${title}${note}${rendered.join("")}</section>`;
+});
+
+export const boardHtml = Effect.fn("WorkBoard.boardHtml")(function* (
+	board: Board,
+	fallbackTitle: string,
+	modified: number,
+	metadata = "",
+	questionActions?: ReadonlyMap<string, string>,
+) {
+	let fragments = 0;
+	const headings = documentHeadings();
+	const render: Render = (fragment) => {
+		fragments += 1;
+		return renderMarkdown(board.definitions === "" ? fragment : `${fragment}\n\n${board.definitions}`, {
+			file: fallbackTitle,
+			headings,
+			idPrefix: `part-${fragments}-`,
+			...(questionActions ? { questionActions } : {}),
+		});
+	};
+	const title = board.title === "" ? `<h1>${escapeHtml(fallbackTitle)}</h1>` : yield* render(board.title);
+	const intro = board.intro === "" ? "" : `<div class="intro">${yield* render(board.intro)}</div>`;
+	const sections = yield* Effect.forEach(board.sections, (each) => section(each, render));
+	const footer = board.footer === "" ? "" : `<footer>${yield* render(board.footer)}</footer>`;
+	return [
+		readingTools(headings.entries),
+		metadata,
+		`<header class="board-head">${title}${intro}`,
+		`<p class="counts">${counts(board)}</p>`,
+		`<p class="meta">${updated(modified)}</p></header>`,
+		`<div class="board">${sections.join("")}</div>`,
+		footer,
+	].join("");
+});

package/src/server/page/criteriaEvidence.ts

@@ -0,0 +1,36 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { referenceTarget } from "#server/metadata/links.ts";
+import type { MetadataModel } from "#server/metadata/model.ts";
+import type { ParsedMetadata } from "#server/metadata/parse.ts";
+import { documentReference } from "./metadataLinks.ts";
+
+function evidenceFor(reference: string, model: MetadataModel): string {
+	const records = model.documents.flatMap(
+		(document) =>
+			document.parsed.fields.evidence?.flatMap((evidence, index) =>
+				evidence.criterion === reference ? [{ file: document.file, index, line: document.parsed.lines[`evidence.${index}.source`] }] : [],
+			) ?? [],
+	);
+	if (records.length === 0) {
+		return "<p>No recorded evidence naming this criterion. Acceptance is not established.</p>";
+	}
+	return `<p>${records.length} recorded ${records.length === 1 ? "claim" : "claims"}, not verified acceptance:</p><ul>${records.map((record) => `<li><a href="${escapeHtml(documentReference(record.file, model, `#recorded-evidence-${record.index}`))}">${escapeHtml(record.file)}${record.line === undefined ? "" : `:${record.line}`} — open recorded evidence</a></li>`).join("")}</ul>`;
+}
+
+export function criteriaEvidence(parsed: ParsedMetadata, model: MetadataModel): string {
+	const criteria = parsed.fields.criteria ?? [];
+	if (criteria.length === 0) {
+		return "";
+	}
+	return `<h3>Criteria and recorded evidence</h3><ul>${criteria
+		.map((criterion) => {
+			const unique = criteria.filter((candidate) => candidate.id === criterion.id).length === 1;
+			const reference = parsed.fields.id ? `${parsed.fields.id}#${criterion.id}` : "";
+			const evidence =
+				reference && referenceTarget(reference, model)
+					? evidenceFor(reference, model)
+					: "<p>Evidence association requires unique item/criterion IDs and a readable workspace. Acceptance is not established.</p>";
+			return `<li${unique ? ` id="criterion-${escapeHtml(criterion.id)}" tabindex="-1"` : ""}><b>${escapeHtml(criterion.id)}</b>: ${escapeHtml(criterion.text)}${evidence}</li>`;
+		})
+		.join("")}</ul>`;
+}

package/src/server/page/documentHtml.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { documentHeadings } from "#render/documentHeadings.ts";
+import type { MarkdownFile } from "#server/files/list.ts";
+import { renderMarkdown } from "#server/render/markdown.ts";
+import { readingTools } from "./readingTools.ts";
+import { updated } from "./updated.ts";
+
+export const documentHtml = Effect.fn("WorkBoard.documentHtml")(function* (
+	source: string,
+	file: MarkdownFile,
+	metadata = "",
+	introduction = "",
+	questionActions?: ReadonlyMap<string, string>,
+) {
+	const headings = documentHeadings(true);
+	const html = yield* renderMarkdown(source, { file: file.path, headings, ...(questionActions ? { questionActions } : {}) });
+	const title = /^<h1\b[^>]*>[\s\S]*?<\/h1>/u.exec(html)?.[0] ?? "";
+	return `<div class="document-layout"><header class="item-introduction">${title || `<h1>${escapeHtml(file.path)}</h1>`}${introduction}</header>
+ <details class="item-context" data-key="item-context"><summary>Context and tools</summary><div class="context-content">
+ <p class="meta">Source: ${escapeHtml(file.path)} · ${updated(file.modified)}</p>${metadata}${readingTools(headings.entries)}</div></details>
+ <article class="doc">${html.slice(title.length)}</article></div>`;
+});

package/src/server/page/itemIntroduction.ts

@@ -0,0 +1,10 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { ParsedMetadata } from "#server/metadata/parse.ts";
+
+export function itemIntroduction(parsed: ParsedMetadata): string {
+	if (parsed.raw === undefined) {
+		return "";
+	}
+	const fields = parsed.fields;
+	return `<div class="item-summary" aria-label="Authored work"><p>Status (source): <b>${escapeHtml(fields.status ?? "Not recorded")}</b>${fields.owner ? ` · Owner: ${escapeHtml(fields.owner)}` : ""}</p><p>Next action: ${escapeHtml(fields.nextAction ?? "Not recorded")}</p></div>`;
+}

package/src/server/page/itemStyles.ts

@@ -0,0 +1,29 @@
+export function itemStyles(): string {
+	return `
+.document-view:has(.document-layout) { max-width: 1220px; }
+.page:has(.document-layout) > .bar,
+.page:has(.document-layout) > .preferences { max-height: 25vh; overflow: auto; }
+.document-view:has(.document-layout) > .response-panel { max-width: 72ch; margin-inline: 0; }
+.document-layout { display: grid; gap: 20px; grid-template-columns: minmax(0, 1fr); }
+.document-layout > * { min-width: 0; }
+.item-introduction h1 { margin: 0 0 .6em; }
+.item-summary { padding: 12px 16px; background: var(--surface); border-left: 3px solid var(--link); border-radius: 4px; overflow-wrap: anywhere; }
+.item-summary p { margin: 0; }
+.item-summary p + p { margin-top: 8px; }
+.item-context { align-self: start; margin: 0; padding: 12px 16px; border: 1px solid var(--border); border-radius: 8px; font-size: .9rem; overflow-wrap: anywhere; }
+.item-context > summary { color: var(--text); font-weight: 600; }
+.item-context .work-meta, .item-context .work-context { margin: 16px 0; padding: 0; border: 0; background: transparent; }
+.item-context .reading-tools { margin: 16px 0 0; }
+.document-layout > .doc > :first-child { margin-top: 0; }
+@media (min-width: 1100px) {
+  .document-layout { grid-template-columns: minmax(0, 72ch) minmax(240px, 280px); grid-template-rows: auto 1fr; gap: 24px 32px; }
+  .item-introduction { grid-column: 1; grid-row: 1; }
+  .item-context { grid-column: 2; grid-row: 1 / span 2; }
+  .document-layout > .doc { grid-column: 1; grid-row: 2; }
+}
+@media print {
+  .document-layout { display: block; }
+  .item-context { display: none; }
+}
+`;
+}

package/src/server/page/metadata.ts

@@ -0,0 +1,58 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { identityUrl } from "#server/metadata/links.ts";
+import type { MetadataModel } from "#server/metadata/model.ts";
+import type { ParsedMetadata } from "#server/metadata/parse.ts";
+import { backlinksHtml } from "#server/page/backlinksHtml.ts";
+import { metadataDetails } from "#server/page/metadataDetails.ts";
+import { stateOf, viewUrl } from "#server/views/state.ts";
+
+function handoffLink(id: string | undefined, kind: string | undefined, unique: boolean) {
+	return unique && id && !["question", "response", "handoff"].includes(kind ?? "")
+		? `<p><a href="/_board/handoff?item=${encodeURIComponent(id)}">Prepare an agent handoff</a></p>`
+		: "";
+}
+
+function resultLink(id: string | undefined, kind: string | undefined, unique: boolean) {
+	return unique && id && kind === "result" ? `<p><a href="/_board/result?item=${encodeURIComponent(id)}">Review returned result</a></p>` : "";
+}
+
+function recordedSummary(parsed: ParsedMetadata, identity: string, summary: boolean): string {
+	const fields = parsed.fields;
+	return summary
+		? `<p class="metadata-summary">Recorded work · ${identity}${fields.status ? ` · ${escapeHtml(fields.status)}` : ""}${fields.owner ? ` · ${escapeHtml(fields.owner)}` : ""}</p>${fields.nextAction ? `<p>Next action: ${escapeHtml(fields.nextAction)}</p>` : ""}`
+		: `<p class="metadata-summary">Recorded work · ${identity}</p>`;
+}
+
+export function metadataHtml(parsed: ParsedMetadata, file: string, model: MetadataModel, summary = true): string {
+	const backlinks = backlinksHtml(file, model);
+	const diagnostics = model.diagnostics.get(file) ?? parsed.diagnostics;
+	if (parsed.raw === undefined && diagnostics.length === 0) {
+		return backlinks;
+	}
+	const fields = parsed.fields;
+	const unique = model.unavailable.length === 0 && fields.id !== undefined && model.ids.get(fields.id)?.length === 1;
+	const problems =
+		diagnostics.length > 0
+			? `<div class="metadata-problems" role="status"><b>Source diagnostics</b><ul>${diagnostics.map((problem) => `<li>${escapeHtml(file)}:${problem.line} — ${escapeHtml(problem.message)}</li>`).join("")}</ul></div>`
+			: "";
+	const identity =
+		unique && fields.id
+			? `<a href="${identityUrl(fields.id)}">Item link: ${escapeHtml(fields.id)}</a>`
+			: `ID: ${escapeHtml(fields.id ?? "Not recorded")}`;
+	const details = metadataDetails(parsed, file, model);
+	const boardLink =
+		unique && fields.kind === "board" && fields.id
+			? `<p><a href="${escapeHtml(viewUrl(stateOf("/"), { board: fields.id }))}">View this board</a></p>`
+			: "";
+	const lead = recordedSummary(parsed, identity, summary);
+	return `<section class="work-meta" aria-label="Recorded work">${lead}${boardLink}${resultLink(fields.id, fields.kind, unique)}${handoffLink(fields.id, fields.kind, unique)}${problems}<details data-key="work-metadata"><summary>Work details and source</summary>${details}<p>Source: ${escapeHtml(file)}:${parsed.lines.id ?? 1}; prose starts at line ${parsed.bodyLine}.</p>${parsed.raw ? `<details data-key="frontmatter-source"><summary>Original frontmatter</summary><pre>${escapeHtml(parsed.raw)}</pre></details>` : ""}</details></section>${backlinks}`;
+}
+
+export const metadataStyles = `
+.work-meta{font-size:.9rem;margin:16px 0 24px;padding:12px 16px;border:1px solid var(--border);border-radius:8px;background:var(--surface);overflow-wrap:anywhere}
+.metadata-summary{font-weight:600;margin:0}.work-meta>p{margin-bottom:8px}.work-meta details{margin:0}.work-meta summary{color:var(--link)}
+.work-meta dl{display:grid;grid-template-columns:minmax(80px,auto) minmax(0,1fr);gap:4px 12px;margin:12px 0}.work-meta dt{color:var(--muted)}.work-meta dd{margin:0}
+.work-meta pre{max-height:300px;overflow:auto;margin-top:12px}.metadata-problems{color:var(--danger);margin:12px 0}.metadata-problems ul{margin:4px 0 12px;padding-left:20px}
+.work-context{font-size:.9rem;margin:12px 0 24px;padding:12px 16px;border:1px solid var(--border);border-radius:8px;overflow-wrap:anywhere}.work-context details{margin:0}.work-context ul{margin:12px 0}.work-context p{font-size:13px;color:var(--muted);margin:8px 0 0}
+[id^="recorded-evidence-"],[id^="criterion-"]{scroll-margin-top:20px}
+`;

package/src/server/page/metadataDetails.ts

@@ -0,0 +1,38 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { MetadataModel } from "#server/metadata/model.ts";
+import type { ParsedMetadata } from "#server/metadata/parse.ts";
+import { relationshipLabel } from "#server/metadata/relationshipLabel.ts";
+import { attentionDetails } from "./attentionDetails.ts";
+import { criteriaEvidence } from "./criteriaEvidence.ts";
+import { referenceHtml, valueHtml } from "./metadataLinks.ts";
+import { recordedEvidence } from "./recordedEvidence.ts";
+
+export function metadataDetails(parsed: ParsedMetadata, file: string, model: MetadataModel): string {
+	const fields = parsed.fields;
+	const details = [
+		fields.handoff
+			? `<h3>Agent handoff</h3><p>${referenceHtml(fields.handoff.item, fields.handoff.item, model)} · ${escapeHtml(fields.handoff.recipient)} · ${escapeHtml(fields.handoff.state)}</p><p>Receipt is separate from execution and acceptance.</p><p>${escapeHtml(fields.handoff.by ?? "Attribution not recorded")}${fields.handoff.note ? ` · ${escapeHtml(fields.handoff.note)}` : ""}</p><p>Reviewed SHA-256: <code>${fields.handoff.reviewedRevision}</code></p><p><a href="/_board/handoff?item=${encodeURIComponent(fields.handoff.item)}">Read handoff history and copy its prompt</a></p>`
+			: "",
+		`<dl><dt>Kind</dt><dd>${valueHtml(fields.kind)}</dd><dt>Status</dt><dd>${valueHtml(fields.status)}</dd><dt>Owner</dt><dd>${valueHtml(fields.owner)}</dd><dt>Next action</dt><dd>${valueHtml(fields.nextAction)}</dd></dl>`,
+		fields.relationships?.length
+			? `<h3>Relationships</h3><ul>${fields.relationships.map((link) => `<li>${escapeHtml(relationshipLabel(link.kind))}: ${referenceHtml(link.target, link.target, model)}</li>`).join("")}</ul>`
+			: "",
+		fields.items?.length
+			? `<h3>Declared board membership</h3><ul>${fields.items.map((id) => `<li>${referenceHtml(id, id, model)}</li>`).join("")}</ul>`
+			: "",
+
+		fields.question
+			? `<h3>Reviewed question</h3><p>${referenceHtml(fields.question.item, fields.question.item, model)} / ${escapeHtml(fields.question.request)} · ${escapeHtml(fields.question.reason)}</p><p>Reviewed SHA-256: <code>${fields.question.reviewedRevision}</code>. Registered: ${new Date(fields.question.registeredAt).toISOString()}. Unanswered deadline: ${new Date(fields.question.deadline).toISOString()}.</p>`
+			: "",
+		fields.response
+			? `<h3>Recorded response</h3><p>${referenceHtml(fields.response.question, fields.response.question, model)} · ${escapeHtml(fields.response.author)} · ${escapeHtml(fields.response.type)}</p><p>Reviewed SHA-256: <code>${fields.response.reviewedRevision}</code>. This is authored feedback, not verified acceptance.</p>${fields.response.supersedes ? `<p>Explicitly supersedes ${referenceHtml(fields.response.supersedes, fields.response.supersedes, model)}.</p>` : ""}`
+			: "",
+		fields.requestReceipt
+			? `<h3>Managed request receipt</h3><p>${referenceHtml(fields.requestReceipt.question, fields.requestReceipt.question, model)} · ${fields.requestReceipt.disposition}</p><p>Reviewed SHA-256: <code>${fields.requestReceipt.reviewedRevision}</code>. This acknowledges request handling, not execution, acceptance or delivery authority.</p>${fields.requestReceipt.response ? `<p>Applied response: ${referenceHtml(fields.requestReceipt.response, fields.requestReceipt.response, model)}</p>` : ""}`
+			: "",
+		criteriaEvidence(parsed, model),
+		attentionDetails(parsed, file, model),
+		recordedEvidence(parsed, file, model),
+	].join("");
+	return details;
+}

package/src/server/page/metadataLinks.ts

@@ -0,0 +1,35 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { fileUrl } from "#files/url.ts";
+import { referenceTarget } from "#server/metadata/links.ts";
+import type { MetadataModel } from "#server/metadata/model.ts";
+import { sourceFile, sourceHref } from "#server/metadata/sourceLinks.ts";
+
+export function referenceHtml(label: string, target: string, model: MetadataModel): string {
+	const href = referenceTarget(target, model);
+	return href
+		? `<a href="${escapeHtml(href)}">${escapeHtml(label)}</a>`
+		: `<span>${escapeHtml(label)} (unresolved, ambiguous, or unavailable)</span>`;
+}
+
+export function sourceHtml(source: string, file: string, model: MetadataModel): string {
+	const href = sourceHref(source, file);
+	if (!href) {
+		return escapeHtml(source);
+	}
+	const target = sourceFile(source, file, model);
+	const missing = target && !model.documents.some((document) => document.file === target);
+	let problem = "";
+	if (missing) {
+		problem = model.unavailable.includes(target) ? " (source unavailable)" : " (missing Markdown source)";
+	}
+	return `<a href="${escapeHtml(href)}" rel="noreferrer">${escapeHtml(source)}</a>${problem}`;
+}
+
+export function documentReference(file: string, model: MetadataModel, hash = ""): string {
+	const id = model.documents.find((document) => document.file === file)?.parsed.fields.id;
+	return ((id ? referenceTarget(id, model) : undefined) ?? fileUrl(file)) + hash;
+}
+
+export function valueHtml(text: string | undefined): string {
+	return escapeHtml(text ?? "Not recorded");
+}

package/src/server/page/nav.ts

@@ -0,0 +1,12 @@
+import { navigationHtml } from "#browser/navigation/html.ts";
+import type { MarkdownFile } from "#server/files/list.ts";
+import { inboxCount as countOf, navigationData } from "#server/navigation/model.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+
+export function navHtml(files: readonly MarkdownFile[], current: string, home: string | undefined, snapshot?: Snapshot): string {
+	return navigationHtml(navigationData(files, current, home, snapshot));
+}
+
+export function inboxCount(snapshot?: Snapshot): string {
+	return String(countOf(snapshot) ?? "?");
+}

package/src/server/page/readingStyles.ts

@@ -0,0 +1,31 @@
+export function readingStyles(): string {
+	return `
+.reading-tools { display: flex; align-items: start; flex-wrap: wrap; gap: 12px; margin-bottom: 20px; font-size: 13px; }
+.reading-tools button[aria-pressed="true"] { background: var(--surface); border-color: var(--link); }
+.outline { margin: 0; min-width: 180px; max-width: 100%; }
+.outline > summary { padding: 6px 10px; border: 1px solid var(--border); border-radius: 6px; color: var(--text); }
+.outline nav { margin-top: 12px; padding: 0 12px; max-height: 40vh; overflow-y: auto; }
+.outline ol { padding-left: 18px; }
+.outline li { overflow-wrap: anywhere; }
+.outline li[data-depth="3"], .outline li[data-depth="4"] { margin-left: 12px; }
+.outline li[data-depth="5"], .outline li[data-depth="6"] { margin-left: 24px; }
+.heading-anchor { display: inline-block; margin-left: 8px; font-size: 0.7em; text-decoration: none; opacity: 0.35; }
+.heading-anchor::after { content: "#"; }
+.heading-anchor:hover, .heading-anchor:focus-visible { opacity: 1; }
+[id^="heading-"] { scroll-margin-top: 20px; }
+#library-dialog { width: min(560px, calc(100vw - 32px)); max-height: min(600px, calc(100dvh - 32px)); overflow-y: auto; padding: 20px; color: var(--text); background: var(--card); border: 1px solid var(--border); border-radius: 12px; }
+#library-dialog::backdrop { background: rgb(0 0 0 / .45); }
+.reading-library { font-size: 14px; margin-top: 20px; }
+.reading-library .nav-heading { font-size: 14px; }
+.reading-library[hidden] { display: none; }
+.reading-library ul { list-style: none; padding: 0 12px; margin: 0 0 20px; }
+.reading-library a { color: var(--link); overflow-wrap: anywhere; }
+.reading-library a[aria-current="page"] { font-weight: 600; }
+.reading-library .missing { color: var(--muted); }
+.library-status { padding: 0 12px; color: var(--muted); }
+#navigation-status { color: var(--danger); overflow-wrap: anywhere; }
+#navigation-status:empty { display: none; }
+.bar:has(#navigation-status:not(:empty)) { flex-wrap: wrap; }
+#navigation-status:not(:empty) { flex-basis: 100%; }
+`;
+}

package/src/server/page/readingTools.ts

@@ -0,0 +1,12 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { Heading } from "#render/documentHeadings.ts";
+
+export function readingTools(headings: readonly Heading[]): string {
+	const outline =
+		headings.length === 0
+			? ""
+			: `<details class="outline" data-key="outline"><summary>On this page</summary><nav aria-label="Document outline"><ol>${headings
+					.map(({ depth, id, title }) => `<li data-depth="${depth}"><a href="#${escapeHtml(id)}">${escapeHtml(title || "Section")}</a></li>`)
+					.join("")}</ol></nav></details>`;
+	return `<div class="reading-tools"><button id="favorite-toggle" type="button" aria-pressed="false" disabled>Save favorite</button>${outline}</div>`;
+}

package/src/server/page/recordedEvidence.ts

@@ -0,0 +1,12 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { MetadataModel } from "#server/metadata/model.ts";
+import type { ParsedMetadata } from "#server/metadata/parse.ts";
+import { referenceHtml, sourceHtml, valueHtml } from "./metadataLinks.ts";
+
+export function recordedEvidence(parsed: ParsedMetadata, file: string, model: MetadataModel): string {
+	const records = parsed.fields.evidence ?? [];
+	if (records.length === 0) {
+		return "";
+	}
+	return `<h3>Recorded evidence</h3><p>Source claims — not independently verified. A recorded outcome does not establish human acceptance. Work Board does not check recorded revisions against the current workspace.</p><ul>${records.map((item, index) => `<li id="recorded-evidence-${index}" tabindex="-1">${sourceHtml(item.source, file, model)}<dl><dt>Recorded in</dt><dd>${escapeHtml(file)}:${parsed.lines[`evidence.${index}.source`] ?? parsed.lines.evidence ?? 1}</dd><dt>Criterion</dt><dd>${item.criterion ? referenceHtml(item.criterion, item.criterion, model) : "Not recorded"}</dd><dt>Checked revision</dt><dd>${valueHtml(item.checkedRevision)}</dd><dt>Observed time</dt><dd>${valueHtml(item.observedAt)}</dd><dt>Method</dt><dd>${valueHtml(item.method)}</dd><dt>Recorded outcome</dt><dd>${valueHtml(item.outcome)}</dd></dl></li>`).join("")}</ul>`;
+}