@shivaedev/work-board 0.11.0 → 0.13.0

package/src/server/metadata/backlinks.ts

@@ -0,0 +1,52 @@
+import type { MetadataDocument, MetadataModel } from "./model.ts";
+import { referenceFile, sourceFile } from "./sourceLinks.ts";
+
+export interface Backlink {
+	readonly file: string;
+	readonly kind: string;
+	readonly line?: number;
+}
+
+export function referencesFrom(document: MetadataDocument, model: MetadataModel) {
+	const { fields, lines } = document.parsed;
+	return [
+		...(fields.handoff ? [{ kind: "agent handoff", line: lines.handoff, target: referenceFile(fields.handoff.item, model) }] : []),
+		...(fields.question ? [{ kind: "reviewed question", line: lines.question, target: referenceFile(fields.question.item, model) }] : []),
+		...(fields.response ? [{ kind: "recorded response", line: lines.response, target: referenceFile(fields.response.question, model) }] : []),
+		...(fields.response?.supersedes
+			? [{ kind: "superseding response", line: lines.response, target: referenceFile(fields.response.supersedes, model) }]
+			: []),
+		...(fields.attention?.flatMap((request, index) =>
+			request.unblocks.map((target, targetIndex) => ({
+				kind: "attention target",
+				line: lines[`attention.${index}.unblocks.${targetIndex}`],
+				target: referenceFile(target, model),
+			})),
+		) ?? []),
+		...(fields.relationships?.map((link, index) => ({
+			kind: link.kind,
+			line: lines[`relationships.${index}.target`],
+			target: referenceFile(link.target, model),
+		})) ?? []),
+		...(fields.items?.map((item, index) => ({ kind: "board member", line: lines[`items.${index}`], target: referenceFile(item, model) })) ?? []),
+		...(fields.evidence?.flatMap((evidence, index) => [
+			{ kind: "evidence source", line: lines[`evidence.${index}.source`], target: sourceFile(evidence.source, document.file, model) },
+			{
+				kind: "criterion evidence",
+				line: lines[`evidence.${index}.criterion`],
+				target: evidence.criterion ? referenceFile(evidence.criterion, model) : undefined,
+			},
+		]) ?? []),
+		...(document.links?.map((link) => ({ kind: "Markdown link", line: undefined, target: sourceFile(link, document.file, model) })) ?? []),
+	];
+}
+
+export function backlinksOf(file: string, model: MetadataModel): readonly Backlink[] {
+	return model.documents.flatMap((document) =>
+		document.file === file
+			? []
+			: referencesFrom(document, model)
+					.filter((reference) => reference.target === file)
+					.map((reference) => ({ file: document.file, kind: reference.kind, ...(reference.line === undefined ? {} : { line: reference.line }) })),
+	);
+}

package/src/server/metadata/fields.ts

@@ -0,0 +1,29 @@
+import { Option, Schema } from "effect";
+import { Metadata } from "#metadata/schema.ts";
+import type { Diagnostic } from "./parse.ts";
+
+const schemas: ReadonlyMap<string, Schema.ConstraintDecoder<unknown, never>> = new Map(Object.entries(Metadata.to.fields));
+const sourceKeys = new Map([
+	["next_action", "nextAction"],
+	["request_receipt", "requestReceipt"],
+]);
+
+export function metadataFields(data: object, lines: Readonly<Record<string, number>>) {
+	const fields: Record<string, unknown> = {};
+	const diagnostics: Diagnostic[] = [];
+	for (const [field, value] of Object.entries(data)) {
+		const key = sourceKeys.get(field) ?? field;
+		const schema = field === "nextAction" || field === "requestReceipt" ? undefined : schemas.get(key);
+		if (!schema) {
+			diagnostics.push({ field, line: lines[field] ?? 2, message: `Unknown field ${field}; kept in the original frontmatter.` });
+			continue;
+		}
+		const decoded = Schema.decodeUnknownOption(schema, { onExcessProperty: "error" })(value);
+		if (Option.isNone(decoded)) {
+			diagnostics.push({ field, line: lines[field] ?? 2, message: `Invalid ${field}; kept in the original frontmatter and not interpreted.` });
+		} else {
+			fields[key] = decoded.value;
+		}
+	}
+	return { diagnostics, fields: Schema.decodeUnknownSync(Schema.toType(Metadata))(fields) };
+}

package/src/server/metadata/model.ts

@@ -0,0 +1,17 @@
+import type { MetadataDocument as PublicMetadataDocument, MetadataModel as PublicMetadataModel } from "#integration/metadata.ts";
+import { metadataProblems } from "./problems.ts";
+
+export type MetadataDocument = PublicMetadataDocument;
+export type MetadataModel = PublicMetadataModel;
+
+export function metadataModel(documents: readonly MetadataDocument[], unavailable: readonly string[] = [], rootFile?: string): MetadataModel {
+	const ids = new Map<string, MetadataDocument[]>();
+	for (const document of documents) {
+		const id = document.parsed.fields.id;
+		if (id) {
+			ids.set(id, [...(ids.get(id) ?? []), document]);
+		}
+	}
+	const diagnostics = new Map(documents.map((document) => [document.file, metadataProblems(document, ids, unavailable)]));
+	return { diagnostics, documents, ids, rootFile, unavailable };
+}

package/src/server/metadata/parse.ts

@@ -0,0 +1,51 @@
+import { LineCounter, parseDocument } from "yaml";
+import type { Diagnostic as PublicDiagnostic, ParsedMetadata as PublicParsedMetadata } from "#integration/metadata.ts";
+import { metadataFields } from "./fields.ts";
+import { metadataLocations } from "./locations.ts";
+
+export type Diagnostic = PublicDiagnostic;
+export type ParsedMetadata = PublicParsedMetadata;
+
+export function metadataParse(source: string): ParsedMetadata {
+	const plain: ParsedMetadata = { body: source, bodyLine: 1, diagnostics: [], fields: {}, lines: {} };
+	const opening = /^\uFEFF?---[ \t]*\r?\n/u.exec(source);
+	if (!opening) {
+		return plain;
+	}
+	const remainder = source.slice(opening[0].length);
+	const closing = /^---[ \t]*\r?$/mu.exec(remainder);
+	if (!closing) {
+		return { ...plain, diagnostics: [{ line: 1, message: "Unterminated frontmatter; the original Markdown is shown." }] };
+	}
+	let end = opening[0].length + closing.index + closing[0].length;
+	if (source[end] === "\n") {
+		end += 1;
+	}
+	const raw = source.slice(0, end);
+	const body = source.slice(end);
+	const bodyLine = raw.split("\n").length;
+	const counter = new LineCounter();
+	const doc = parseDocument(remainder.slice(0, closing.index), { lineCounter: counter });
+	const lines = metadataLocations(doc.contents, counter);
+	const diagnostics: Diagnostic[] = [...doc.errors, ...doc.warnings].map((error) => ({
+		line: (error.linePos?.[0].line ?? 1) + 1,
+		message: error.message,
+	}));
+	const result = { body, bodyLine, diagnostics, fields: {}, lines, raw };
+	if (doc.errors.length > 0 || doc.warnings.length > 0) {
+		return result;
+	}
+	let data: unknown;
+	try {
+		data = doc.toJS({ maxAliasCount: 50 });
+	} catch {
+		return { ...result, diagnostics: [...diagnostics, { line: 2, message: "Frontmatter aliases could not be expanded safely." }] };
+	}
+	if (data === null) {
+		return result;
+	}
+	if (typeof data !== "object" || Array.isArray(data)) {
+		return { ...plain, diagnostics: [{ line: 2, message: "Frontmatter must be a mapping; the original Markdown is shown." }] };
+	}
+	return { ...result, ...metadataFields(data, lines) };
+}

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}
+`;