@shivaedev/work-board 0.2.0 → 0.3.0

package/src/metadata/links.ts

@@ -0,0 +1,19 @@
+import type { MetadataModel } from "./model.ts";
+
+export function identityUrl(id: string): string {
+	return `/_board/item/${encodeURIComponent(id)}/`;
+}
+export function referenceTarget(reference: string, model: MetadataModel): string | undefined {
+	if (model.unavailable.length > 0) {
+		return undefined;
+	}
+	const [id = "", criterion] = reference.split("#");
+	const targets = model.ids.get(id);
+	if (targets?.length !== 1) {
+		return undefined;
+	}
+	if (criterion && targets[0]?.parsed.fields.criteria?.filter((item) => item.id === criterion).length !== 1) {
+		return undefined;
+	}
+	return identityUrl(id) + (criterion ? `#criterion-${encodeURIComponent(criterion)}` : "");
+}

package/src/metadata/locations.ts

@@ -0,0 +1,34 @@
+import { isMap, isNode, isScalar, isSeq, type LineCounter, type Node, type YAMLMap } from "yaml";
+
+function recordMap(node: YAMLMap, field: string, counter: LineCounter, lines: Record<string, number>) {
+	for (const pair of node.items) {
+		if (!isScalar(pair.key) || typeof pair.key.value !== "string") {
+			continue;
+		}
+		const key = field ? `${field}.${pair.key.value}` : pair.key.value;
+		visit(pair.value, key, counter, lines);
+		if (pair.key.range) {
+			lines[key] = counter.linePos(pair.key.range[0]).line + 1;
+		}
+	}
+}
+function visit(value: unknown, field: string, counter: LineCounter, lines: Record<string, number>) {
+	if (!isNode(value)) {
+		return;
+	}
+	if (value.range && field) {
+		lines[field] = counter.linePos(value.range[0]).line + 1;
+	}
+	if (isMap(value)) {
+		recordMap(value, field, counter, lines);
+	} else if (isSeq(value)) {
+		value.items.forEach((item, index) => {
+			visit(item, `${field}.${index}`, counter, lines);
+		});
+	}
+}
+export function metadataLocations(node: Node | null, counter: LineCounter): Readonly<Record<string, number>> {
+	const lines: Record<string, number> = {};
+	visit(node, "", counter, lines);
+	return lines;
+}

package/src/metadata/model.ts

@@ -0,0 +1,27 @@
+import type { Diagnostic, ParsedMetadata } from "./parse.ts";
+import { metadataProblems } from "./problems.ts";
+
+export interface MetadataDocument {
+	readonly file: string;
+	readonly links?: readonly string[];
+	readonly parsed: ParsedMetadata;
+}
+export interface MetadataModel {
+	readonly diagnostics: ReadonlyMap<string, readonly Diagnostic[]>;
+	readonly documents: readonly MetadataDocument[];
+	readonly ids: ReadonlyMap<string, readonly MetadataDocument[]>;
+	readonly rootFile: string | undefined;
+	readonly unavailable: readonly string[];
+}
+
+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/metadata/parse.ts

@@ -0,0 +1,62 @@
+import { LineCounter, parseDocument } from "yaml";
+import { metadataFields } from "./fields.ts";
+import { metadataLocations } from "./locations.ts";
+import type { Metadata } from "./schema.ts";
+
+export interface Diagnostic {
+	readonly field?: string;
+	readonly line: number;
+	readonly message: string;
+}
+export interface ParsedMetadata {
+	readonly body: string;
+	readonly bodyLine: number;
+	readonly diagnostics: readonly Diagnostic[];
+	readonly fields: Metadata;
+	readonly lines: Readonly<Record<string, number>>;
+	readonly raw?: string;
+}
+
+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/metadata/problems.ts

@@ -0,0 +1,62 @@
+import type { MetadataDocument } from "./model.ts";
+import type { Diagnostic } from "./parse.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 { fields, lines } = document.parsed;
+	const references = [
+		...(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 }] : [],
+		) ?? []),
+	];
+	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)];
+	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/metadata/relationshipLabel.ts

@@ -0,0 +1,13 @@
+const labels = new Map([
+	["board member", "Board membership"],
+	["criterion evidence", "Criterion evidence"],
+	["depends_on", "Depends on"],
+	["evidence source", "Evidence source"],
+	["implements", "Implements"],
+	["informs", "Informs"],
+	["relates_to", "Related to"],
+]);
+
+export function relationshipLabel(kind: string): string {
+	return labels.get(kind) ?? kind;
+}

package/src/metadata/schema.ts

@@ -0,0 +1,36 @@
+import { Schema } from "effect";
+
+export const Identity = Schema.String.check(Schema.isPattern(/^[a-zA-Z\d][a-zA-Z\d._-]*$/u));
+export const Reference = Schema.String.check(Schema.isPattern(/^[a-zA-Z\d][a-zA-Z\d._-]*(?:#[a-zA-Z\d][a-zA-Z\d._-]*)?$/u));
+const Text = Schema.String.check(Schema.isPattern(/\S/u));
+const Criterion = Schema.Struct({ id: Identity, text: Text });
+const Relationship = Schema.Struct({ kind: Schema.Literals(["implements", "informs", "depends_on", "relates_to"]), target: Reference });
+const Evidence = Schema.Struct({
+	checkedRevision: Schema.optional(Schema.String.check(Schema.isPattern(/^(?:[a-f\d]{40}|[a-f\d]{64})$/iu))),
+	criterion: Schema.optional(Reference),
+	method: Schema.optional(Text),
+	observedAt: Schema.optional(
+		Text.check(
+			Schema.makeFilter(
+				(value) =>
+					(Number.isFinite(Date.parse(value)) && /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/u.exec(value) !== null)
+					|| "Expected an ISO timestamp with timezone",
+			),
+		),
+	),
+	outcome: Schema.optional(Text),
+	source: Text,
+}).pipe(Schema.encodeKeys({ checkedRevision: "checked_revision", observedAt: "observed_at" }));
+
+export const Metadata = Schema.Struct({
+	criteria: Schema.optional(Schema.Array(Criterion)),
+	evidence: Schema.optional(Schema.Array(Evidence)),
+	id: Schema.optional(Identity),
+	items: Schema.optional(Schema.Array(Identity)),
+	kind: Schema.optional(Schema.Literals(["task", "investigation", "decision", "result", "project", "board"])),
+	nextAction: Schema.optional(Text),
+	owner: Schema.optional(Text),
+	relationships: Schema.optional(Schema.Array(Relationship)),
+	status: Schema.optional(Text),
+}).pipe(Schema.encodeKeys({ nextAction: "next_action" }));
+export type Metadata = typeof Metadata.Type;

package/src/metadata/sourceLinks.ts

@@ -0,0 +1,46 @@
+import { fileUrl } from "#files/url.ts";
+import { referenceTarget } from "./links.ts";
+import type { MetadataModel } from "./model.ts";
+
+const BASE = "http://work-board.local";
+const absolute = /^(?:[a-z][a-z\d+.-]*:|\/\/)/iu;
+
+export function sourceHref(source: string, file: string): string | undefined {
+	try {
+		const url = new URL(source, `${BASE}${fileUrl(file)}`);
+		if (!["http:", "https:"].includes(url.protocol)) {
+			return undefined;
+		}
+		return absolute.exec(source) === null ? url.pathname + url.search + url.hash : url.href;
+	} catch {
+		return undefined;
+	}
+}
+
+export function referenceFile(reference: string, model: MetadataModel): string | undefined {
+	if (!referenceTarget(reference, model)) {
+		return undefined;
+	}
+	return model.ids.get(reference.split("#")[0] ?? "")?.[0]?.file;
+}
+
+export function sourceFile(source: string, file: string, model: MetadataModel): string | undefined {
+	const href = sourceHref(source, file);
+	if (!href?.startsWith("/")) {
+		return undefined;
+	}
+	const url = new URL(href, BASE);
+	try {
+		const path = decodeURIComponent(url.pathname);
+		if (path === "/") {
+			return model.rootFile;
+		}
+		const identity = /^\/_board\/item\/(?<id>[^/]+)\/$/u.exec(path)?.groups?.id;
+		if (identity) {
+			return referenceFile(identity, model);
+		}
+		return /\.md$/iu.exec(path) === null ? undefined : path.slice(1);
+	} catch {
+		return undefined;
+	}
+}

package/src/page/backlinksHtml.ts

@@ -0,0 +1,18 @@
+import { backlinksOf } from "#metadata/backlinks.ts";
+import type { MetadataModel } from "#metadata/model.ts";
+import { relationshipLabel } from "#metadata/relationshipLabel.ts";
+import { escapeHtml } from "./escape.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/page/board.ts

@@ -1,7 +1,9 @@
 import { Effect } from "effect";
-import { type Board, countsOf, type Section } from "../render/board.ts";
-import { renderMarkdown } from "../render/markdown.ts";
+import { type Board, countsOf, type Section } from "#render/board.ts";
+import { documentHeadings } from "#render/documentHeadings.ts";
+import { renderMarkdown } from "#render/markdown.ts";
 import { escapeHtml } from "./escape.ts";
+import { readingTools } from "./readingTools.ts";
 import { updated } from "./updated.ts";
 
 const counts = (board: Board): string =>
@@ -12,22 +14,30 @@ const counts = (board: Board): string =>
 type Render = (fragment: string) => ReturnType<typeof renderMarkdown>;
 
 const section = Effect.fn("WorkBoard.section")(function* ({ heading, items, notes }: Section, render: Render) {
-	const rendered = yield* Effect.forEach(items, (item) => Effect.map(render(item), (html) => `<article class="item">${html}</article>`));
+	const title = yield* render(heading);
 	const note = notes === "" ? "" : `<div class="notes">${yield* render(notes)}</div>`;
-	return `<section>${yield* render(heading)}${note}${rendered.join("")}</section>`;
+	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) {
+export const boardHtml = Effect.fn("WorkBoard.boardHtml")(function* (board: Board, fallbackTitle: string, modified: number, metadata = "") {
 	let fragments = 0;
+	const headings = documentHeadings();
 	const render: Render = (fragment) => {
 		fragments += 1;
-		return renderMarkdown(board.definitions === "" ? fragment : `${fragment}\n\n${board.definitions}`, `part-${fragments}-`);
+		return renderMarkdown(board.definitions === "" ? fragment : `${fragment}\n\n${board.definitions}`, {
+			file: fallbackTitle,
+			headings,
+			idPrefix: `part-${fragments}-`,
+		});
 	};
 	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>`,

package/src/page/client.ts

@@ -1,6 +1,11 @@
 export const client = `
+import "/_board/saved-views.js";
+import "/_board/preferences.js";
+import "/_board/search.js";
 import { renderDiagrams } from "/_board/diagrams.js";
-import { remember, swap } from "/_board/swap.js";
+import { applyPage } from "/_board/page-state.js";
+import { pageVersion } from "/_board/navigation.js";
+import { remember } from "/_board/swap.js";
 
 const since = (modified) => {
   const seconds = Math.max(0, Math.round((Date.now() - modified) / 1000));
@@ -32,22 +37,23 @@ const show = () => {
 };
 
 const load = async () => {
+  const version = pageVersion();
+  const path = location.pathname + location.search;
   try {
-    const response = await fetch(location.pathname, { cache: "no-store" });
+    const response = await fetch(path, { cache: "no-store" });
     const next = new DOMParser().parseFromString(await response.text(), "text/html");
     const files = next.getElementById("files");
     const doc = next.getElementById("doc");
+    if (version !== pageVersion()) return;
     if (files === null || doc === null) {
       failure = "refresh failed (" + response.status + ")";
       return;
     }
     failure = "";
-    swap(document.getElementById("files"), files);
-    swap(document.getElementById("doc"), doc);
-    document.title = next.title;
+    applyPage(next, true);
     tick();
-    renderDiagrams(document);
   } catch {
+    if (version !== pageVersion()) return;
     failure = "refresh failed";
   }
 };
@@ -71,6 +77,7 @@ const refresh = async () => {
 const events = new EventSource("/events");
 events.addEventListener("ready", () => {
   connected = true;
+  document.dispatchEvent(new Event("board-index-change"));
   show();
   if (dropped) refresh();
   dropped = false;
@@ -80,11 +87,62 @@ const down = () => {
   dropped = true;
   show();
 };
-events.addEventListener("change", refresh);
+events.addEventListener("change", () => { refresh(); document.dispatchEvent(new Event("board-index-change")); });
 events.addEventListener("down", down);
 events.addEventListener("error", down);
 
+document.addEventListener("board-page", tick);
 tick();
 setInterval(tick, 5000);
 renderDiagrams(document);
 `;
+export const preferences = `
+const root = document.documentElement;
+const key = "work-board:appearance:" + root.dataset.workspace;
+const theme = document.getElementById("theme");
+const density = document.getElementById("density");
+const sidebar = document.getElementById("sidebar");
+const toggle = document.getElementById("sidebar-toggle");
+const status = document.getElementById("preference-status");
+const system = matchMedia("(prefers-color-scheme: dark)");
+let saved = {};
+try {
+  const value = JSON.parse(localStorage.getItem(key) ?? "{}");
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) saved = value;
+} catch {
+  status.textContent = "Preferences apply to this page only.";
+}
+
+theme.value = ["light", "dark"].includes(saved.theme) ? saved.theme : "system";
+density.value = saved.density === "compact" ? "compact" : "comfortable";
+let closed = typeof saved.closed === "boolean" ? saved.closed : matchMedia("(max-width: 760px)").matches;
+
+const appearance = () => {
+  root.dataset.theme = theme.value;
+  root.dataset.scheme = theme.value === "system" ? (system.matches ? "dark" : "light") : theme.value;
+  root.dataset.density = density.value;
+  root.dataset.sidebar = closed ? "closed" : "open";
+  sidebar.hidden = closed;
+  toggle.setAttribute("aria-expanded", String(!closed));
+  document.dispatchEvent(new Event("board-theme"));
+};
+
+const save = () => {
+  appearance();
+  try {
+    localStorage.setItem(key, JSON.stringify({ theme: theme.value, density: density.value, closed }));
+    status.textContent = "";
+  } catch {
+    status.textContent = "Preferences apply to this page only.";
+  }
+};
+
+theme.addEventListener("change", save);
+density.addEventListener("change", save);
+toggle.addEventListener("click", () => {
+  closed = !closed;
+  save();
+});
+system.addEventListener("change", appearance);
+appearance();
+`;

package/src/page/criteriaEvidence.ts

@@ -0,0 +1,36 @@
+import { referenceTarget } from "#metadata/links.ts";
+import type { MetadataModel } from "#metadata/model.ts";
+import type { ParsedMetadata } from "#metadata/parse.ts";
+import { escapeHtml } from "./escape.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/page/diagrams.ts

@@ -13,7 +13,7 @@ const load = async () => {
     securityLevel: "strict",
     theme: "base",
     themeVariables: {
-      darkMode: dark.matches,
+      darkMode: schemeNow() === "dark",
       background: token("--bg"),
       primaryColor: token("--surface"),
       primaryTextColor: token("--text"),
@@ -26,7 +26,8 @@ const load = async () => {
   return mermaid;
 };
 
-const schemeNow = () => (dark.matches ? "dark" : "light");
+const schemeNow = () => document.documentElement.dataset.scheme ?? (dark.matches ? "dark" : "light");
+let lastScheme = schemeNow();
 
 const draw = async (figure) => {
   const source = figure.querySelector(".diagram-source").textContent;
@@ -65,8 +66,15 @@ export const renderDiagrams = (root, selector = "figure.diagram:not([data-state=
   return Promise.all([...root.querySelectorAll(selector)].map(draw));
 };
 
-dark.addEventListener("change", () => {
+const themeChanged = () => {
+  const scheme = schemeNow();
+  if (lastScheme === scheme) return;
+  lastScheme = scheme;
+  const doc = document.getElementById("doc");
+  if (doc) doc.dataset.scheme = scheme;
   mermaid = undefined;
   renderDiagrams(document, "figure.diagram");
-});
+};
+document.addEventListener("board-theme", themeChanged);
+dark.addEventListener("change", themeChanged);
 `;

package/src/page/document.ts

@@ -1,10 +1,13 @@
 import { Effect } from "effect";
-import type { MarkdownFile } from "../files/list.ts";
-import { renderMarkdown } from "../render/markdown.ts";
+import type { MarkdownFile } from "#files/list.ts";
+import { documentHeadings } from "#render/documentHeadings.ts";
+import { renderMarkdown } from "#render/markdown.ts";
 import { escapeHtml } from "./escape.ts";
+import { readingTools } from "./readingTools.ts";
 import { updated } from "./updated.ts";
 
-export const documentHtml = Effect.fn("WorkBoard.documentHtml")(function* (source: string, file: MarkdownFile) {
-	const html = yield* renderMarkdown(source);
-	return `<p class="meta">${escapeHtml(file.path)} · ${updated(file.modified)}</p><article class="doc">${html}</article>`;
+export const documentHtml = Effect.fn("WorkBoard.documentHtml")(function* (source: string, file: MarkdownFile, metadata = "") {
+	const headings = documentHeadings();
+	const html = yield* renderMarkdown(source, { file: file.path, headings });
+	return `${readingTools(headings.entries)}<p class="meta">${escapeHtml(file.path)} · ${updated(file.modified)}</p>${metadata}<article class="doc">${html}</article>`;
 });

package/src/page/escape.ts

@@ -1,3 +1,3 @@
-const entities: Readonly<Record<string, string>> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+const entities: Readonly<Record<string, string>> = { "'": "&#39;", '"': "&quot;", "&": "&amp;", "<": "&lt;", ">": "&gt;" };
 
-export const escapeHtml = (text: string): string => text.replaceAll(/[&<>"']/g, (character) => entities[character] ?? character);
+export const escapeHtml = (text: string): string => text.replaceAll(/[&<>"']/gu, (character) => entities[character] ?? character);

package/src/page/libraryScript.ts

@@ -0,0 +1,72 @@
+export function libraryScript(): string {
+	return `
+const root = document.documentElement;
+const key = "work-board:library:" + root.dataset.workspace;
+const library = document.getElementById("reading-library");
+let favorites = [];
+let recents = [];
+let notice = "";
+const valid = (items) => Array.isArray(items) ? items.filter((item) => item && typeof item.file === "string" && item.file !== "" && typeof item.title === "string") : [];
+try {
+  const saved = JSON.parse(localStorage.getItem(key) ?? "{}");
+  favorites = valid(saved?.favorites);
+  recents = valid(saved?.recents);
+} catch { notice = "Reading history applies to this page only."; }
+const save = () => {
+  try { localStorage.setItem(key, JSON.stringify({ favorites, recents })); notice = ""; }
+  catch { notice = "Reading history applies to this page only."; }
+};
+const hrefOf = (file) => "/" + file.split("/").map(encodeURIComponent).join("/");
+const list = (title, items) => {
+  const heading = document.createElement("h2");
+  heading.className = "nav-heading";
+  heading.textContent = title;
+  const ul = document.createElement("ul");
+  const available = new Set([...document.querySelectorAll("#files a")].map((a) => new URL(a.href).pathname));
+  for (const item of items) {
+    const li = document.createElement("li");
+    const a = document.createElement("a");
+    a.href = hrefOf(item.file);
+    a.textContent = item.title;
+    if (item.file === document.getElementById("doc").dataset.file) a.setAttribute("aria-current", "page");
+    if (!available.has(a.pathname)) {
+      a.textContent += " (missing)";
+      a.className = "missing";
+    }
+    li.append(a); ul.append(li);
+  }
+  return [heading, ul];
+};
+export const refreshLibrary = (visit = false) => {
+  const doc = document.getElementById("doc");
+  const title = doc.querySelector("h1")?.textContent.trim() || doc.dataset.file;
+  document.title = title ? title + " · Work Board" : "Work Board";
+  const active = document.querySelector('#files a[aria-current="page"]');
+  if (active) active.title = title;
+  const toggle = document.getElementById("favorite-toggle");
+  if (toggle) {
+    const saved = favorites.some((item) => item.file === doc.dataset.file);
+    toggle.disabled = false;
+    toggle.setAttribute("aria-pressed", String(saved));
+    toggle.textContent = saved ? "Remove favorite" : "Save favorite";
+    if (visit) {
+      recents = [{ file: doc.dataset.file, title }, ...recents.filter((item) => item.file !== doc.dataset.file)].slice(0, 10);
+      save();
+    }
+  }
+  const status = document.createElement("p");
+  status.className = "library-status";
+  status.setAttribute("role", "status");
+  status.textContent = notice;
+  library.replaceChildren(...(favorites.length ? list("Favorites", favorites) : []), ...(recents.length ? list("Recent documents", recents) : []), ...(notice ? [status] : []));
+  library.hidden = favorites.length === 0 && recents.length === 0 && notice === "";
+};
+document.addEventListener("click", (event) => {
+  if (!event.target.closest?.("#favorite-toggle")) return;
+  const doc = document.getElementById("doc");
+  const file = doc.dataset.file;
+  favorites = favorites.some((item) => item.file === file) ? favorites.filter((item) => item.file !== file) : [...favorites, { file, title: doc.querySelector("h1")?.textContent.trim() || file }];
+  save(); refreshLibrary();
+});
+`;
+}