@shivaedev/work-board 0.2.1 → 0.4.0

package/src/attention/requests.ts

@@ -0,0 +1,64 @@
+import { identityUrl, referenceTarget } from "#metadata/links.ts";
+import type { MetadataDocument } from "#metadata/model.ts";
+import type { Metadata } from "#metadata/schema.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+
+export type Request = NonNullable<Metadata["attention"]>[number];
+export interface AttentionEntry {
+	readonly document: MetadataDocument;
+	readonly href: string;
+	readonly itemId: string;
+	readonly line: number;
+	readonly request: Request;
+	readonly title: string;
+}
+export interface SourceIssue {
+	readonly file: string;
+	readonly line: number;
+	readonly message: string;
+}
+
+function requestsFor(document: MetadataDocument, snapshot: Snapshot, title: string): readonly AttentionEntry[] {
+	const { fields, lines } = document.parsed;
+	const itemId = fields.id;
+	if (!itemId || snapshot.unavailable.length > 0 || snapshot.model.ids.get(itemId)?.length !== 1) {
+		return [];
+	}
+	const requests = fields.attention ?? [];
+	return requests.flatMap((request, index) => {
+		if (
+			request.state !== "open"
+			|| requests.filter((other) => other.id === request.id).length !== 1
+			|| request.unblocks.some((target) => !referenceTarget(target, snapshot.model))
+		) {
+			return [];
+		}
+		return [
+			{
+				document,
+				href: `${identityUrl(itemId)}#attention-request-${encodeURIComponent(request.id)}`,
+				itemId,
+				line: lines[`attention.${index}`] ?? lines.attention ?? 2,
+				request,
+				title,
+			},
+		];
+	});
+}
+
+export function attentionRequests(snapshot: Snapshot) {
+	const titles = new Map(snapshot.entries.filter((entry) => entry.kind === "document").map((entry) => [entry.file, entry.title]));
+	const issues: SourceIssue[] = snapshot.documents.flatMap((source) =>
+		(snapshot.model.diagnostics.get(source.file) ?? source.parsed.diagnostics).map((problem) => ({ ...problem, file: source.file })),
+	);
+	const entries = snapshot.documents.flatMap((source) => requestsFor(source, snapshot, titles.get(source.file) ?? source.file));
+	const collator = new Intl.Collator("en", { numeric: true, sensitivity: "base" });
+	entries.sort((a, b) => collator.compare(a.title, b.title) || a.itemId.localeCompare(b.itemId) || a.request.id.localeCompare(b.request.id));
+	return { complete: snapshot.unavailable.length === 0, entries, issues };
+}
+
+export function attentionSource(document: MetadataDocument, index: number): string {
+	const requests = document.parsed.fields.attention ?? [];
+	const id = requests[index]?.id;
+	return id && requests.filter((request) => request.id === id).length === 1 ? `attention-request-${id}` : `attention-record-${index}`;
+}

package/src/attention/style.ts

@@ -0,0 +1,9 @@
+export function attentionStyle(): string {
+	return `
+.attention-total{margin:24px 0 8px;font-weight:600}.attention-order,.attention-footnote{font-size:13px;color:var(--muted);margin:0 0 24px;overflow-wrap:anywhere}
+.attention-groups{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:20px;align-items:start}.attention-group{min-width:0}.attention-group>h2{display:flex;justify-content:space-between;gap:12px;font-size:16px;margin:0 0 16px}.attention-group>h2>span{font:12px var(--mono);color:var(--muted)}
+.attention-card{border:1px solid var(--border);border-radius:10px;padding:var(--card-space);background:var(--card);margin:0 0 16px;overflow-wrap:anywhere}.attention-card h3{font-size:1rem;margin:6px 0}.attention-card h3 a{text-decoration:none}.attention-card dl{font-size:13px;margin:16px 0}.attention-card dt{color:var(--muted);margin-top:12px}.attention-card dd{margin:4px 0}.attention-source{font-size:12px}.attention-reason{font-size:14px;margin:0}.attention-footnote{margin-top:24px}.attention-incomplete{padding:16px;border:1px solid var(--danger);border-radius:8px;margin:24px 0;overflow-wrap:anywhere}
+[id^="attention-request-"],[id^="attention-record-"]{scroll-margin-top:20px}
+@media(max-width:1100px){.attention-groups{grid-template-columns:minmax(0,1fr)}}
+`;
+}

package/src/board.ts

@@ -4,11 +4,17 @@ import { watchChanges } from "#files/changes.ts";
 import { type HomeMissing, homeIn } from "#files/home.ts";
 import { ASSETS, MERMAID_ROUTE, type MermaidMissing, mermaidFile, mermaidRoot } from "#http/assets.ts";
 import { events } from "#http/events.ts";
+import { changesPage, history } from "#http/history.ts";
+import { identity } from "#http/identity.ts";
 import { loopbackOnly } from "#http/loopback.ts";
+import { overview } from "#http/overview.ts";
 import { page } from "#http/page.ts";
 import { respond } from "#http/respond.ts";
+import { search } from "#http/search.ts";
+import { work } from "#http/work.ts";
 import type { RenderFailed } from "#render/failed.ts";
 import { Highlighter } from "#render/highlighter.ts";
+import { searchSnapshot } from "#search/snapshot.ts";
 
 export interface BoardOptions {
 	readonly home?: string | undefined;
@@ -25,18 +31,25 @@ const routes = (options: BoardOptions) =>
 			const mermaid = yield* mermaidRoot();
 			const changes = yield* watchChanges(options.root);
 			const context = yield* Effect.context<Services>();
-			const serve = <E>(route: HttpRouter.PathInput, handler: Handler<E>) =>
+			const serve = <E>(route: HttpRouter.PathInput, handler: Handler<E>, method: "GET" | "POST" = "GET") =>
 				router.add(
-					"GET",
+					method,
 					route,
 					loopbackOnly((request) => Effect.provideContext(handler(request), context)),
 				);
 			yield* serve("/events", events(changes));
+			const index = yield* searchSnapshot(options.root, home, changes);
+			yield* serve("/_board/search", search(index));
+			yield* serve("/_board/work", work(index, changes, home));
+			yield* serve("/_board/overview", overview(index, changes, home));
+			yield* serve("/_board/changes", changesPage(changes, home));
+			yield* serve("/_board/history", history(index), "POST");
 			for (const [route, body, contentType] of ASSETS) {
 				yield* serve(route, () => Effect.succeed(respond(body, contentType)));
 			}
 			yield* serve(MERMAID_ROUTE, mermaidFile(mermaid));
-			const pages = page({ home, root: options.root }, changes);
+			const pages = page({ home, root: options.root }, changes, index);
+			yield* serve("/_board/item/*", identity(index, pages, changes, home));
 			yield* serve("/", pages);
 			yield* serve("/*", pages);
 		}),

package/src/cli.ts

@@ -4,7 +4,7 @@ import { Effect, Layer, Option, Path } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import { HOST, serveBoard } from "./serve.ts";
 
-const VERSION = "0.2.1";
+const VERSION = "0.4.0";
 
 const serve = Effect.fn("WorkBoard.serve")(function* (input: { readonly dir: string; readonly port: number; readonly home: Option.Option<string> }) {
 	const path = yield* Path.Path;

package/src/files/changes.ts

@@ -1,5 +1,6 @@
-import { Data, Deferred, Effect, FileSystem, Option, Path, type PlatformError, PubSub, Ref, Schedule, Stream } from "effect";
-import { isMarkdown, listMarkdown, type MarkdownFile } from "./list.ts";
+import { Deferred, Effect, FileSystem, Option, Path, type PlatformError, PubSub, Ref, Schedule } from "effect";
+import { listMarkdown, type MarkdownFile } from "./list.ts";
+import { watchDirectories } from "./watchDirectories.ts";
 
 export type Change = { readonly _tag: "Changed"; readonly paths: readonly string[] } | { readonly _tag: "Watching"; readonly watching: boolean };
 
@@ -7,6 +8,7 @@ export interface Changes {
 	readonly events: PubSub.PubSub<Change>;
 	readonly files: Effect.Effect<readonly MarkdownFile[], PlatformError.PlatformError>;
 	readonly realRoot: string;
+	readonly revision: Effect.Effect<number>;
 	readonly watching: Ref.Ref<boolean>;
 }
 
@@ -15,10 +17,6 @@ interface Cached {
 	readonly generation: number;
 }
 
-class WatchEnded extends Data.TaggedError("WatchEnded") {}
-
-const SETTLE = "100 millis";
-const BATCH = 256;
 const BACKLOG = 16;
 const RETRY = Schedule.min([Schedule.exponential("100 millis"), Schedule.spaced("5 seconds")]);
 
@@ -32,7 +30,6 @@ export const watchChanges = Effect.fn("WorkBoard.watchChanges")(function* (root:
 	const cached = yield* Ref.make(Option.none<Cached>());
 	const settled = yield* Deferred.make<void>();
 	const stale = Ref.update(generation, (count) => count + 1);
-	const relative = (changed: string) => (path.isAbsolute(changed) ? path.relative(root, changed) : changed).split(path.sep).join("/");
 	const setWatching = (now: boolean) =>
 		Effect.andThen(
 			Effect.flatMap(Ref.getAndSet(watching, now), (was) =>
@@ -40,15 +37,7 @@ export const watchChanges = Effect.fn("WorkBoard.watchChanges")(function* (root:
 			),
 			Deferred.succeed(settled, undefined),
 		);
-	const watchOnce = fs.watch(root, { recursive: true }).pipe(
-		Stream.tap(() => stale),
-		Stream.map((event) => relative(event.path)),
-		Stream.filter(isMarkdown),
-		Stream.groupedWithin(BATCH, SETTLE),
-		Stream.runForEach((paths) => PubSub.publish(events, { _tag: "Changed", paths: [...new Set(paths)] })),
-		Effect.andThen(Effect.fail(new WatchEnded())),
-	);
-	const attempt = Effect.scoped(Effect.andThen(Effect.forkScoped(Effect.delay(setWatching(true), SETTLE)), watchOnce));
+	const attempt = watchDirectories(root, realRoot, stale, setWatching, (paths) => PubSub.publish(events, { _tag: "Changed", paths }));
 	yield* attempt.pipe(
 		Effect.sandbox,
 		Effect.tapError((cause) => Effect.andThen(setWatching(false), Effect.logWarning("Watching the folder failed; retrying", cause))),
@@ -66,6 +55,6 @@ export const watchChanges = Effect.fn("WorkBoard.watchChanges")(function* (root:
 		yield* Ref.set(cached, Option.some({ files: listed, generation: now }));
 		return listed;
 	});
-	const changes: Changes = { events, files, realRoot, watching };
+	const changes: Changes = { events, files, realRoot, revision: Ref.get(generation), watching };
 	return changes;
 });

package/src/files/home.ts

@@ -20,6 +20,10 @@ export const homeIn = Effect.fn("WorkBoard.homeIn")(function* (root: string, hom
 		return yield* missing;
 	}
 	const files = yield* listMarkdown(root, realRoot);
+	const logical = path.relative(root, path.resolve(root, home)).split(path.sep).join("/");
+	if (files.some((file) => file.path === logical)) {
+		return logical;
+	}
 	const relative = path.relative(realRoot, real.value).split(path.sep).join("/");
 	if (files.some((file) => file.path === relative)) {
 		return relative;

package/src/files/list.ts

@@ -17,14 +17,14 @@ const byFolder = (left: string, right: string): number => folderOf(left).localeC
 
 type Listing = Effect.Effect<readonly MarkdownFile[], PlatformError.PlatformError>;
 
-export const listMarkdown = Effect.fn("WorkBoard.listMarkdown")(function* (root: string, realRoot: string) {
+export const scanMarkdown = Effect.fn("WorkBoard.scanMarkdown")(function* (root: string, realRoot: string) {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
-	const visited = new Set<string>();
-	const entry = (relative: string): Listing =>
+	const roots: Array<{ readonly real: string; readonly relative: string }> = [{ real: realRoot, relative: "" }];
+	const entry = (relative: string, boundary: string, ancestors: ReadonlySet<string>, parent: string): Listing =>
 		Effect.gen(function* () {
 			const real = yield* Effect.option(fs.realPath(path.join(root, relative)));
-			if (Option.isNone(real) || !within(realRoot, path.sep, real.value)) {
+			if (Option.isNone(real)) {
 				return [];
 			}
 			const info = yield* Effect.option(fs.stat(real.value));
@@ -32,24 +32,35 @@ export const listMarkdown = Effect.fn("WorkBoard.listMarkdown")(function* (root:
 				return [];
 			}
 			if (info.value.type === "Directory") {
-				return yield* Effect.orElseSucceed(folder(relative, real.value), () => []);
+				return yield* directory(relative, real.value, boundary, ancestors, real.value !== path.join(parent, path.basename(relative)));
 			}
 			const modified = Option.match(info.value.mtime, { onNone: () => 0, onSome: (date) => date.getTime() });
-			return info.value.type === "File" && relative.endsWith(".md") ? [{ modified, path: relative }] : [];
+			return info.value.type === "File" && relative.endsWith(".md") && within(boundary, path.sep, real.value) ? [{ modified, path: relative }] : [];
 		});
-	const folder = (relative: string, real: string): Listing =>
+	function directory(relative: string, real: string, boundary: string, ancestors: ReadonlySet<string>, alias: boolean): Listing {
+		if (ancestors.has(real) || within(real, path.sep, realRoot)) {
+			return Effect.succeed([]);
+		}
+		const linked = !within(boundary, path.sep, real);
+		if (alias) {
+			roots.push({ real, relative });
+		}
+		return Effect.orElseSucceed(folder(relative, real, linked ? real : boundary, ancestors), () => []);
+	}
+	const folder = (relative: string, real: string, boundary: string, ancestors: ReadonlySet<string>): Listing =>
 		Effect.gen(function* () {
-			if (visited.has(real)) {
-				return [];
-			}
-			visited.add(real);
+			const branch = new Set([...ancestors, real]);
 			const names = yield* fs.readDirectory(real);
 			const found = yield* Effect.forEach(
 				names.filter((name) => !skipped(name)),
-				(name) => entry(relative === "" ? name : `${relative}/${name}`),
+				(name) => entry(relative === "" ? name : `${relative}/${name}`, boundary, branch, real),
 			);
 			return found.flat();
 		});
-	const files = yield* folder("", realRoot);
-	return files.toSorted((left, right) => byFolder(left.path, right.path));
+	const files = yield* folder("", realRoot, realRoot, new Set());
+	return { files: files.toSorted((left, right) => byFolder(left.path, right.path)), roots };
+});
+
+export const listMarkdown = Effect.fn("WorkBoard.listMarkdown")(function* (root: string, realRoot: string) {
+	return (yield* scanMarkdown(root, realRoot)).files;
 });

package/src/files/markdownPath.ts

@@ -0,0 +1,31 @@
+import { Effect, FileSystem, Option, Path } from "effect";
+import { isMarkdown, within } from "./list.ts";
+
+export const markdownPath = Effect.fn("WorkBoard.markdownPath")(function* (root: string, realRoot: string, relative: string) {
+	if (!isMarkdown(relative) || relative.split("/").some((segment) => segment === "" || segment === "..")) {
+		return undefined;
+	}
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const segments = relative.split("/");
+	const ancestors = new Set([realRoot]);
+	let boundary = realRoot;
+	for (let index = 0; index < segments.length; index += 1) {
+		const real = yield* Effect.option(fs.realPath(path.join(root, ...segments.slice(0, index + 1))));
+		if (Option.isNone(real)) {
+			return undefined;
+		}
+		if (index === segments.length - 1) {
+			return within(boundary, path.sep, real.value) ? real.value : undefined;
+		}
+		const info = yield* Effect.option(fs.stat(real.value));
+		if (Option.isNone(info) || info.value.type !== "Directory" || ancestors.has(real.value) || within(real.value, path.sep, realRoot)) {
+			return undefined;
+		}
+		ancestors.add(real.value);
+		if (!within(boundary, path.sep, real.value)) {
+			boundary = real.value;
+		}
+	}
+	return undefined;
+});

package/src/files/url.ts

@@ -0,0 +1,3 @@
+export function fileUrl(file: string): string {
+	return `/${file.split("/").map(encodeURIComponent).join("/")}`;
+}

package/src/files/watchDirectories.ts

@@ -0,0 +1,60 @@
+import { Data, Deferred, Effect, FileSystem, Option, Path, Stream } from "effect";
+import { isMarkdown, scanMarkdown } from "./list.ts";
+
+class WatchEnded extends Data.TaggedError("WatchEnded") {}
+
+const SETTLE = "100 millis";
+const BATCH = 256;
+
+export const watchDirectories = Effect.fn("WorkBoard.watchDirectories")(function* (
+	root: string,
+	realRoot: string,
+	stale: Effect.Effect<void>,
+	setWatching: (watching: boolean) => Effect.Effect<unknown>,
+	publish: (paths: readonly string[]) => Effect.Effect<unknown>,
+) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const cycle = Effect.scoped(
+		Effect.gen(function* () {
+			const { roots } = yield* scanMarkdown(root, realRoot);
+			const topology = yield* Deferred.make<void>();
+			// Node's recursive watcher can miss replacement of directory symlinks.
+			const parents = yield* Effect.forEach(
+				roots.filter((folder) => folder.relative !== ""),
+				(folder) =>
+					Effect.map(fs.realPath(path.dirname(path.join(root, folder.relative))), (real) => ({ real, relative: path.dirname(folder.relative) })),
+			);
+			const watched = [...roots.map((folder) => ({ ...folder, recursive: true })), ...parents.map((folder) => ({ ...folder, recursive: false }))];
+			const streams = watched.map((folder) =>
+				fs.watch(folder.real, { recursive: folder.recursive }).pipe(
+					Stream.map((event) => {
+						const local = path.isAbsolute(event.path) ? path.relative(folder.real, event.path) : event.path;
+						return path.join(folder.relative, local).split(path.sep).join("/");
+					}),
+				),
+			);
+			const watch = Stream.mergeAll(streams, { concurrency: "unbounded" }).pipe(
+				Stream.tap(() => stale),
+				Stream.tap((relative) =>
+					Effect.gen(function* () {
+						const info = yield* Effect.option(fs.stat(path.join(root, relative)));
+						const removedLink = roots.some((folder) => folder.relative === relative || folder.relative.startsWith(`${relative}/`));
+						if (Option.match(info, { onNone: () => removedLink, onSome: (value) => value.type === "Directory" })) {
+							yield* Effect.forkScoped(Effect.delay(Deferred.succeed(topology, undefined), SETTLE));
+						}
+					}),
+				),
+				Stream.filter(isMarkdown),
+				Stream.interruptWhen(Deferred.await(topology)),
+				Stream.groupedWithin(BATCH, SETTLE),
+				Stream.runForEach((paths) => publish([...new Set(paths)])),
+				Effect.andThen(Effect.flatMap(Deferred.isDone(topology), (changed) => (changed ? Effect.void : Effect.fail(new WatchEnded())))),
+			);
+			yield* Effect.forkScoped(Effect.delay(setWatching(true), SETTLE));
+			yield* watch;
+			yield* setWatching(false);
+		}),
+	);
+	yield* Effect.forever(cycle);
+});

package/src/history/baseline.ts

@@ -0,0 +1,43 @@
+import { Option, Schema } from "effect";
+import type { Snapshot } from "#search/snapshot.ts";
+import { MAX_AGE, MAX_BYTES } from "./limits.ts";
+import { Baseline } from "./schema.ts";
+
+const JsonBaseline = Schema.fromJsonString(Baseline);
+function byteLength(text: string): number {
+	return new TextEncoder().encode(text).length;
+}
+
+export function readBaseline(raw: string | null, now: number) {
+	if (raw === null) {
+		return { baseline: undefined, discard: false, reason: "No previous snapshot. Start remembering changes to compare future source observations." };
+	}
+	if (byteLength(raw) > MAX_BYTES) {
+		return { baseline: undefined, discard: true, reason: "Remembered snapshot exceeds 2 MiB; history is unavailable." };
+	}
+	const decoded = Schema.decodeUnknownOption(JsonBaseline, { onExcessProperty: "error" })(raw);
+	if (Option.isNone(decoded)) {
+		return { baseline: undefined, discard: true, reason: "Remembered snapshot is invalid or unsupported; history is unavailable." };
+	}
+	const elapsed = now - Date.parse(decoded.value.recordedAt);
+	if (elapsed < 0) {
+		return { baseline: undefined, discard: true, reason: "Remembered observation is in the future; history is unavailable." };
+	}
+	if (elapsed >= MAX_AGE) {
+		return { baseline: undefined, discard: true, reason: "Remembered snapshot expired after 30 days; start again to establish a new baseline." };
+	}
+	return { baseline: decoded.value, discard: false, reason: "" };
+}
+
+export function observeBaseline(snapshot: Snapshot, now: number): string | undefined {
+	if (snapshot.unavailable.length > 0) {
+		return undefined;
+	}
+	const baseline: Baseline = {
+		documents: snapshot.documents.map((document) => ({ file: document.file, source: (document.parsed.raw ?? "") + document.parsed.body })),
+		recordedAt: new Date(now).toISOString(),
+		version: 1,
+	};
+	const raw = Schema.encodeSync(JsonBaseline)(baseline);
+	return byteLength(raw) <= MAX_BYTES ? raw : undefined;
+}

package/src/history/compare.ts

@@ -0,0 +1,54 @@
+import { type HistoryDocument, historyDocuments, historyIdentities } from "./documents.ts";
+import { historyFields } from "./fields.ts";
+import type { Baseline } from "./schema.ts";
+
+export interface SourceChange {
+	readonly after?: HistoryDocument;
+	readonly before?: HistoryDocument;
+	readonly kind: "added" | "removed" | "changed";
+	readonly reasons: readonly string[];
+}
+
+export function compareHistory(baseline: Baseline, current: Baseline) {
+	const before = historyDocuments(baseline);
+	const after = historyDocuments(current);
+	const oldIds = historyIdentities(before);
+	const newIds = historyIdentities(after);
+	const paired = new Set<HistoryDocument>();
+	const remaining = new Set(after);
+	const changes: SourceChange[] = [];
+	function pair(old: HistoryDocument, next: HistoryDocument) {
+		paired.add(old);
+		remaining.delete(next);
+		if (old.source !== next.source || old.file !== next.file) {
+			changes.push({ after: next, before: old, kind: "changed", reasons: historyFields(old, next) });
+		}
+	}
+	for (const [id, old] of oldIds) {
+		const next = newIds.get(id);
+		if (old && next) {
+			pair(old, next);
+		}
+	}
+	const byFile = new Map([...remaining].map((document) => [document.file, document]));
+	for (const old of before) {
+		if (paired.has(old)) {
+			continue;
+		}
+		const next = byFile.get(old.file);
+		if (next) {
+			pair(old, next);
+		} else {
+			changes.push({ before: old, kind: "removed", reasons: ["Source absent from the complete current observation"] });
+		}
+	}
+	for (const next of remaining) {
+		changes.push({ after: next, kind: "added", reasons: ["Source added since the remembered observation"] });
+	}
+	const issues = [
+		...[...oldIds].filter(([, document]) => !document).map(([id]) => `Duplicate ID ${id} in remembered sources; no identity winner selected.`),
+		...[...newIds].filter(([, document]) => !document).map(([id]) => `Duplicate ID ${id} in current sources; no identity winner selected.`),
+	];
+	changes.sort((a, b) => (a.after?.file ?? a.before?.file ?? "").localeCompare(b.after?.file ?? b.before?.file ?? "", "en"));
+	return { changes, issues, newIds };
+}

package/src/history/documents.ts

@@ -0,0 +1,21 @@
+import { metadataParse, type ParsedMetadata } from "#metadata/parse.ts";
+import type { Baseline } from "./schema.ts";
+
+export interface HistoryDocument {
+	readonly file: string;
+	readonly parsed: ParsedMetadata;
+	readonly source: string;
+}
+export function historyDocuments(baseline: Baseline): readonly HistoryDocument[] {
+	return baseline.documents.map((document) => ({ ...document, parsed: metadataParse(document.source) }));
+}
+export function historyIdentities(documents: readonly HistoryDocument[]): ReadonlyMap<string, HistoryDocument | undefined> {
+	const ids = new Map<string, HistoryDocument | undefined>();
+	for (const document of documents) {
+		const id = document.parsed.fields.id;
+		if (id) {
+			ids.set(id, ids.has(id) ? undefined : document);
+		}
+	}
+	return ids;
+}

package/src/history/fields.ts

@@ -0,0 +1,32 @@
+import type { Metadata } from "#metadata/schema.ts";
+import type { HistoryDocument } from "./documents.ts";
+
+const labels: ReadonlyArray<readonly [keyof Metadata, string]> = [
+	["attention", "Recorded attention requests changed"],
+	["criteria", "Criteria changed"],
+	["evidence", "Recorded evidence changed (not verified acceptance)"],
+	["id", "Item ID changed"],
+	["items", "Declared board membership changed"],
+	["kind", "Item kind changed"],
+	["nextAction", "Next action changed"],
+	["owner", "Recorded owner changed (not authorship)"],
+	["relationships", "Explicit relationships changed"],
+	["status", "Recorded status changed (not acceptance)"],
+];
+
+export function historyFields(before: HistoryDocument, after: HistoryDocument): readonly string[] {
+	const changes = labels.flatMap(([field, label]) =>
+		JSON.stringify(before.parsed.fields[field]) === JSON.stringify(after.parsed.fields[field]) ? [] : [label],
+	);
+	if (before.parsed.body !== after.parsed.body) {
+		const decision = before.parsed.fields.kind === "decision" || after.parsed.fields.kind === "decision";
+		changes.push(decision ? "Decision Markdown changed" : "Markdown body changed");
+	}
+	if (changes.length === 0 && before.source !== after.source) {
+		changes.push("Other frontmatter content or source formatting changed; no further interpretation");
+	}
+	if (before.file !== after.file) {
+		changes.unshift("Source path changed for the same unique item ID");
+	}
+	return changes;
+}

package/src/history/html.ts

@@ -0,0 +1,23 @@
+import { fileUrl } from "#files/url.ts";
+import { escapeHtml } from "#page/escape.ts";
+import { compareHistory, type SourceChange } from "./compare.ts";
+import type { Baseline } from "./schema.ts";
+
+function source(label: string, text: string, key: string): string {
+	return `<details data-key="${escapeHtml(key)}:${label}" data-history-source="${label.toLowerCase()}"><summary>${label} source (plain text)</summary><pre class="history-source">${escapeHtml(text)}</pre></details>`;
+}
+function changeHtml(change: SourceChange): string {
+	const file = change.after?.file ?? change.before?.file ?? "";
+	const key = change.before ? `before:${change.before.file}` : `added:${file}`;
+	return `<article class="history-change" data-key="${escapeHtml(key)}"><h2>${change.kind}: ${escapeHtml(file)}</h2>${change.before && change.after && change.before.file !== file ? `<p>Previously ${escapeHtml(change.before.file)}</p>` : ""}<ul>${change.reasons.map((reason) => `<li>${escapeHtml(reason)}</li>`).join("")}</ul>${change.after ? `<a href="${escapeHtml(fileUrl(change.after.file))}">Read current source</a>` : "<p>Removed source; no current document link.</p>"}${change.before ? source("Remembered", change.before.source, key) : ""}${change.after ? source("Current", change.after.source, key) : ""}</article>`;
+}
+export function historyHtml(before: Baseline, current: Baseline): string {
+	const result = compareHistory(before, current);
+	const counts = ["added", "removed", "changed"]
+		.map((kind) => `${result.changes.filter((change) => change.kind === kind).length} ${kind}`)
+		.join(" · ");
+	return `<p>Compared with your observation at <time>${escapeHtml(before.recordedAt)}</time>.</p><p role="status">${counts}</p>${result.changes.length === 0 ? "<p>No source changes since that observation.</p>" : ""}${result.issues.length > 0 ? `<aside aria-label="Identity limitations"><ul>${result.issues.map((issue) => `<li>${escapeHtml(issue)}</li>`).join("")}</ul><p>Ambiguous identities are compared by source path only.</p></aside>` : ""}${result.changes.map(changeHtml).join("")}`;
+}
+export function changesHtml(): string {
+	return `<section class="history"><h1>Changes since seen</h1><p>Compare current Markdown with one observation you explicitly remember in this browser. This is an observed source comparison, not an event journal, Git history, authorship, or verified acceptance.</p><p>Remembered source can include old or deleted content. One snapshot per workspace, up to 2 MiB, expires after 30 days and is removed on your next workspace visit. Mark seen replaces it; Clear forgets it. No source writes or cloud storage.</p><div class="history-controls"><button id="history-mark" type="button" disabled>Start remembering changes</button><button id="history-clear" type="button" disabled>Clear remembered history</button><span id="history-storage" role="status"></span></div><noscript><p>Remembering and comparing changes requires JavaScript and browser storage. Markdown, Overview and Work remain readable.</p></noscript><div id="changes-content" aria-live="polite"><p>No comparison has been loaded.</p></div></section><style>.history-controls{display:flex;flex-wrap:wrap;gap:.6rem;align-items:center}.history-change{border-top:1px solid var(--border);padding:1rem 0}.history-source{white-space:pre-wrap;overflow-wrap:anywhere;max-height:32rem;overflow:auto}.history h2{overflow-wrap:anywhere}</style>`;
+}

package/src/history/limits.ts

@@ -0,0 +1,2 @@
+export const MAX_BYTES = 2 * 1024 * 1024;
+export const MAX_AGE = 30 * 24 * 60 * 60 * 1000;

package/src/history/response.ts

@@ -0,0 +1,23 @@
+import { escapeHtml } from "#page/escape.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+import { observeBaseline, readBaseline } from "./baseline.ts";
+import { historyHtml } from "./html.ts";
+import type { HistoryOutput } from "./schema.ts";
+
+export function historyResponse(raw: string | null, now: number, snapshot?: Snapshot): HistoryOutput {
+	const prior = readBaseline(raw, now);
+	const output: HistoryOutput = { discardBaseline: prior.discard, html: `<p>${escapeHtml(prior.reason)}</p>`, reason: prior.reason, snapshot: null };
+	if (snapshot === undefined) {
+		return output;
+	}
+	const currentRaw = observeBaseline(snapshot, now);
+	if (currentRaw === undefined) {
+		const reason =
+			snapshot.unavailable.length > 0
+				? "Current workspace observation is incomplete; no comparison or removals are inferred. Your valid remembered snapshot is preserved."
+				: "Complete current snapshot exceeds 2 MiB; no comparison or partial history is retained.";
+		return { ...output, html: `<p role="status">${escapeHtml(reason)}</p>`, reason };
+	}
+	const current = readBaseline(currentRaw, now).baseline;
+	return { ...output, html: prior.baseline && current ? historyHtml(prior.baseline, current) : output.html, snapshot: currentRaw };
+}

package/src/history/schema.ts

@@ -0,0 +1,36 @@
+import { Schema } from "effect";
+import { isMarkdown } from "#files/list.ts";
+
+const File = Schema.String.check(
+	Schema.makeFilter(
+		(value) =>
+			(isMarkdown(value) && !value.includes("\\") && !value.includes("\0") && value.split("/").every((part) => part.length > 0 && part !== ".."))
+			|| "Expected a relative readable Markdown path",
+	),
+);
+const ObservedTime = Schema.String.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 observation time with timezone",
+	),
+);
+export const Baseline = Schema.Struct({
+	documents: Schema.Array(Schema.Struct({ file: File, source: Schema.String })).check(
+		Schema.makeFilter(
+			(values) => new Set(values.map((value) => value.file)).size === values.length || "Duplicate source paths are not a complete observation",
+		),
+	),
+	recordedAt: ObservedTime,
+	version: Schema.Literal(1),
+}).pipe(Schema.encodeKeys({ recordedAt: "recorded_at" }));
+export type Baseline = typeof Baseline.Type;
+
+export const HistoryInput = Schema.Struct({ action: Schema.Literals(["check", "compare", "observe"]), baseline: Schema.NullOr(Schema.String) });
+export const HistoryOutput = Schema.Struct({
+	discardBaseline: Schema.Boolean,
+	html: Schema.String,
+	reason: Schema.String,
+	snapshot: Schema.NullOr(Schema.String),
+});
+export type HistoryOutput = typeof HistoryOutput.Type;