@shivaedev/work-board 0.11.0 → 0.12.0

package/src/server/handoffs/Service.ts

@@ -0,0 +1,111 @@
+import { join } from "node:path";
+import { Clock, Effect, FileSystem, Path, Semaphore } from "effect";
+import { defineService } from "@shivaedev/effect-service/define-service.ts";
+import { Conflict, Forbidden, NotFound, PreconditionFailed, ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import { rpcBoundary } from "@shivaedev/platform/rpc-server/boundary.ts";
+import type { Handoff, HandoffInput } from "#browser/handoffs/schema.ts";
+import { markdownPath } from "#server/files/markdownPath.ts";
+import { handoffFrom, handoffMarkdown, handoffPrompt, matchesHandoff } from "#server/handoffs/records.ts";
+import { handoffSource } from "#server/handoffs/source.ts";
+import { publish } from "#server/responses/publish.ts";
+import { revisionOf } from "#server/responses/records.ts";
+import { ResponseConfig } from "#server/responses/service.ts";
+
+export const HandoffsService = defineService({
+	id: "WorkBoard/HandoffsService",
+	initialize: Effect.gen(function* () {
+		return { fs: yield* FileSystem.FileSystem, lock: yield* Semaphore.make(1), options: yield* ResponseConfig };
+	}),
+	methods: ({ options, fs, lock }) => {
+		const snapshot = options.index.pipe(
+			rpcBoundary(ServiceUnavailable, {
+				message: "The workspace could not be indexed.",
+				unexpected: (message) => new ServiceUnavailable({ message }),
+			}),
+		);
+		const locate = handoffSource(options.root, options.changes.realRoot, snapshot, fs);
+		const read = Effect.fn("WorkBoard.read")(function* (item: string) {
+			const data = yield* snapshot;
+			const unknown = [...data.unavailable];
+			const records = data.documents.flatMap((document) => {
+				const record = handoffFrom(document, options.changes.realRoot);
+				if (
+					(record && data.model.ids.get(record.id)?.length !== 1)
+					|| (document.parsed.fields.kind === "handoff" && !record)
+					|| (document.file.startsWith("handoffs/") && document.parsed.diagnostics.some((problem) => problem.field === undefined))
+				) {
+					unknown.push(document.file);
+					return [];
+				}
+				return record?.handoff.item === item ? [record] : [];
+			});
+			return { records: records.sort((a, b) => b.handoff.preparedAt - a.handoff.preparedAt || a.id.localeCompare(b.id)), unknown };
+		});
+		const reconcile = Effect.fn("WorkBoard.reconcile")(function* (record: Handoff | undefined, input: HandoffInput) {
+			if (!record || record.file !== `handoffs/${input.id}.md` || !matchesHandoff(record, input) || revisionOf(record.context) !== input.revision) {
+				return yield* Effect.fail(new Conflict({ message: "This handoff identity moved, is duplicated or records different direction." }));
+			}
+			const path = yield* markdownPath(options.root, options.changes.realRoot, record.file);
+			if (!path) {
+				return yield* Effect.fail(new NotFound({ message: "The prepared handoff moved or disappeared." }));
+			}
+			const raw = yield* fs.readFileString(path).pipe(
+				rpcBoundary(ServiceUnavailable, {
+					message: "The handoff could not be reconciled.",
+					unexpected: (message) => new ServiceUnavailable({ message }),
+				}),
+			);
+			yield* publish(options.root, options.changes.realRoot, record.id, raw, "handoffs");
+			return record;
+		});
+
+		function prepare(input: HandoffInput) {
+			return lock.withPermit(
+				Effect.gen(function* () {
+					if (!options.enabled) {
+						return yield* Effect.fail(new Forbidden({ message: "Restart with --responses to enable local response/handoff writes." }));
+					}
+					const data = yield* snapshot;
+					const existing = data.model.ids.get(input.id);
+					if (existing?.length) {
+						const record = existing.length === 1 ? handoffFrom(existing[0], options.changes.realRoot) : undefined;
+						return yield* reconcile(record, input);
+					}
+					const current = yield* locate(input.item);
+					if (current.reviewedRevision !== input.revision || current.source !== input.source) {
+						return yield* Effect.fail(new PreconditionFailed({ message: "The source changed or moved. Keep your draft and review it again." }));
+					}
+					const file = `handoffs/${input.id}.md`;
+					const record: Handoff = {
+						context: current.context,
+						file,
+						handoff: {
+							constraints: input.constraints,
+							goal: input.goal,
+							item: input.item,
+							nextAction: input.nextAction,
+							preparedAt: yield* Clock.currentTimeMillis,
+							recipient: input.recipient,
+							reviewedRevision: input.revision,
+							source: input.source,
+							state: "requested",
+						},
+						id: input.id,
+						prompt: handoffPrompt(join(options.changes.realRoot, file)),
+					};
+					yield* publish(
+						options.root,
+						options.changes.realRoot,
+						record.id,
+						handoffMarkdown(record.id, record.handoff, record.context),
+						"handoffs",
+					).pipe(Effect.ensuring(options.changes.refresh ?? Effect.void));
+					return record;
+				}),
+			);
+		}
+		return { locate, prepare, read };
+	},
+	requires: [ResponseConfig, FileSystem.FileSystem, Path.Path],
+});
+export type HandoffsService = typeof HandoffsService.Identifier;

package/src/server/handoffs/html.ts

@@ -0,0 +1,42 @@
+import { Effect } from "effect";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { Handoff, HandoffPreview } from "#browser/handoffs/schema.ts";
+import { fileUrl } from "#files/url.ts";
+import type { RenderFailed } from "#render/failed.ts";
+import { metadataParse } from "#server/metadata/parse.ts";
+import type { Highlighter } from "#server/render/Highlighter.ts";
+import { renderMarkdown } from "#server/render/markdown.ts";
+
+export function promptHtml(id: string, prompt: string) {
+	return `<div class="handoff-copy"><label>Prompt for your existing agent session<textarea id="handoff-prompt-${escapeHtml(id)}" readonly rows="3">${escapeHtml(prompt)}</textarea></label><button type="button" data-handoff-copy="handoff-prompt-${escapeHtml(id)}">Copy tiny prompt</button><p role="status" data-copy-status>Copy and paste this into your agent session. Preparing a file does not notify an agent.</p></div>`;
+}
+function receiptNote(h: Handoff["handoff"]) {
+	if (!(h.by || h.note)) {
+		return "";
+	}
+	return `<p>${escapeHtml(h.by ?? "Attribution not recorded")}${h.note ? ` · ${escapeHtml(h.note)}` : ""}</p>`;
+}
+export const handoffHistoryHtml = Effect.fn("WorkBoard.handoffHistoryHtml")(function* (
+	records: readonly Handoff[],
+	current?: HandoffPreview,
+): Effect.fn.Return<string[], RenderFailed, Highlighter> {
+	return yield* Effect.forEach(records, (record) =>
+		Effect.gen(function* () {
+			const h = record.handoff;
+			const goal = yield* renderMarkdown(h.goal, { file: h.source, safe: true });
+			const constraints = yield* renderMarkdown(h.constraints, { file: h.source, safe: true });
+			const next = yield* renderMarkdown(h.nextAction, { file: h.source, safe: true });
+			const same = current?.reviewedRevision === h.reviewedRevision && current.source === h.source;
+			return `<article id="${escapeHtml(record.id)}"><h3><a href="${fileUrl(record.file)}">${escapeHtml(record.id)}</a> · ${escapeHtml(h.recipient)}</h3><p><b>Receipt: ${escapeHtml(h.state)}</b>${h.state === "requested" ? " — prepared; receipt not confirmed" : ""}. Execution and acceptance are not recorded by this state.</p><p>${same ? "Current reviewed source" : "Earlier or unavailable reviewed source; recheck before acting"} · <a href="${fileUrl(h.source)}">${escapeHtml(h.source)}</a> · <code>${h.reviewedRevision}</code></p>${receiptNote(h)}<h4>Goal</h4>${goal}<h4>Constraints</h4>${constraints || "<p>None recorded.</p>"}<h4>Next action</h4>${next}${promptHtml(record.id, record.prompt)}<details><summary>Exact reviewed source snapshot</summary><pre>${escapeHtml(record.context)}</pre></details></article>`;
+		}),
+	);
+});
+export const handoffFormHtml = Effect.fn("WorkBoard.handoffFormHtml")(function* (
+	source: HandoffPreview,
+	enabled: boolean,
+): Effect.fn.Return<string, RenderFailed, Highlighter> {
+	const parsed = metadataParse(source.context);
+	const background = yield* renderMarkdown(parsed.body, { file: source.source, safe: true });
+	const goal = /^#\s+(?<title>.+)$/mu.exec(parsed.body)?.groups?.title ?? source.item;
+	return `<section class="response-context">${background}</section><details><summary>Exact source being reviewed</summary><pre>${escapeHtml(source.context)}</pre></details><form id="handoff-form" data-item="${escapeHtml(source.item)}" data-source="${escapeHtml(source.source)}" data-revision="${source.reviewedRevision}" data-question="${source.id}" data-writable="${enabled}"><label>Recipient — local agent label<input name="recipient" required maxlength="200"></label><label>Goal<textarea name="goal" required maxlength="8192" rows="3">${escapeHtml(goal)}</textarea></label><label>Constraints (optional)<textarea name="constraints" maxlength="8192" rows="4"></textarea></label><label>Next action<textarea name="nextAction" required maxlength="8192" rows="3">${escapeHtml(parsed.fields.nextAction ?? "")}</textarea></label><p>The file includes the full reviewed source and its declared acceptance criteria. Preparing it does not change the item or start an agent. Drafts use the existing 30-day/2-MiB workspace store.</p><button id="handoff-preview" type="button" disabled>Preview Markdown</button><pre id="handoff-preview-content" hidden></pre><button id="handoff-submit" type="submit" disabled>Prepare handoff</button><button id="handoff-clear" type="button" disabled>Clear workspace drafts</button><p id="handoff-status" role="status">${enabled ? "JavaScript is required to prepare a handoff." : "Read-only mode. Restart with --responses to enable local writes."}</p><section id="handoff-prepared" hidden></section></form>`;
+});

package/src/server/handoffs/page.ts

@@ -0,0 +1,51 @@
+import { Effect, type FileSystem, type Path, type PlatformError } from "effect";
+import type { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { Changes } from "#server/files/changes.ts";
+import { handoffFormHtml, handoffHistoryHtml } from "#server/handoffs/html.ts";
+import { HandoffsService } from "#server/handoffs/Service.ts";
+import { respond } from "#server/http/respond.ts";
+import { navHtml } from "#server/page/nav.ts";
+import { shell } from "#server/page/shell.ts";
+import type { Highlighter } from "#server/render/Highlighter.ts";
+import type { searchSnapshot } from "#server/search/snapshot.ts";
+
+function unknownHistory(files: readonly string[]) {
+	return files.length > 0
+		? `<p role="status">Some handoff history is unavailable: ${files.map(escapeHtml).join(", ")}. Missing records do not establish that no receipt exists.</p>`
+		: "";
+}
+export function handoffPage(changes: Changes, home: string | undefined, enabled: boolean, index?: Effect.Success<ReturnType<typeof searchSnapshot>>) {
+	return Effect.fn("WorkBoard.handoffPage")(function* (
+		request: HttpServerRequest.HttpServerRequest,
+	): Effect.fn.Return<
+		HttpServerResponse.HttpServerResponse,
+		PlatformError.PlatformError,
+		FileSystem.FileSystem | Path.Path | Highlighter | HandoffsService
+	> {
+		const service = yield* HandoffsService;
+		const item = new URL(request.url, "http://127.0.0.1").searchParams.get("item") ?? "";
+		const files = yield* changes.files;
+		const snapshot = index ? yield* index : undefined;
+		function layout(body: string, status = 200) {
+			return respond(
+				shell("Handoff", navHtml(files, "", home, snapshot), body, changes.realRoot, false, undefined, "handoff", snapshot),
+				"text/html",
+				status,
+			);
+		}
+		return yield* Effect.gen(function* () {
+			const source = yield* Effect.result(service.locate(item));
+			const current = source._tag === "Success" ? source.success : undefined;
+			const reading = yield* service.read(item);
+			const history = yield* handoffHistoryHtml(reading.records, current);
+			const form = current
+				? yield* handoffFormHtml(current, enabled)
+				: `<p role="status">Source unavailable: ${escapeHtml(String(source._tag === "Failure" ? source.failure : ""))}. Existing handoffs remain readable.</p>`;
+			return layout(
+				`<section class="response-panel"><h1>Agent handoff · ${escapeHtml(item)}</h1><p>Prepare a Markdown file, then copy a tiny prompt into your existing agent session. Sessions may poll or wait for human answers. Agents record receipt with ordinary file edits.</p>${form}<section id="handoff-history"><h2>Prepared handoffs</h2>${unknownHistory(reading.unknown)}${history.join("") || "<p>No readable handoff is recorded for this item.</p>"}</section></section>`,
+				current || reading.records.length > 0 ? 200 : 409,
+			);
+		}).pipe(Effect.catch((error) => Effect.succeed(layout(`<h1>Handoff unavailable</h1><p>${escapeHtml(String(error))}</p>`, 409))));
+	});
+}

package/src/server/handoffs/records.ts

@@ -0,0 +1,34 @@
+import { join } from "node:path";
+import { Schema } from "effect";
+import { stringify } from "yaml";
+import type { Handoff, HandoffInput, HandoffRecord } from "#browser/handoffs/schema.ts";
+import { HandoffRecord as RecordSchema } from "#browser/handoffs/schema.ts";
+import type { MetadataDocument } from "#server/metadata/model.ts";
+
+export function handoffFrom(document: MetadataDocument | undefined, root: string): Handoff | undefined {
+	if (!document) {
+		return undefined;
+	}
+	const { id, kind, handoff } = document.parsed.fields;
+	return id && kind === "handoff" && handoff
+		? { context: document.parsed.body, file: document.file, handoff, id, prompt: handoffPrompt(join(root, document.file)) }
+		: undefined;
+}
+export function handoffPrompt(path: string): string {
+	return `Read the handoff at ${JSON.stringify(path)}. Record receipt by editing its handoff.state and add handoff.by/note; then follow its instructions.`;
+}
+export function handoffMarkdown(id: string, handoff: HandoffRecord, context: string): string {
+	return `---\n${stringify({ handoff: Schema.encodeSync(RecordSchema)(handoff), id, kind: "handoff" })}---\n${context}`;
+}
+export function matchesHandoff(record: Handoff, input: HandoffInput) {
+	const saved = record.handoff;
+	return (
+		saved.item === input.item
+		&& saved.source === input.source
+		&& saved.reviewedRevision === input.revision
+		&& saved.recipient === input.recipient
+		&& saved.goal === input.goal
+		&& saved.constraints === input.constraints
+		&& saved.nextAction === input.nextAction
+	);
+}

package/src/server/handoffs/source.ts

@@ -0,0 +1,40 @@
+import { Effect, type FileSystem } from "effect";
+import { BadRequest, NotFound, PreconditionFailed, ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import { rpcBoundary } from "@shivaedev/platform/rpc-server/boundary.ts";
+import type { HandoffPreview } from "#browser/handoffs/schema.ts";
+import type { ResponseRejection } from "#rpc/rejections.ts";
+import { markdownPath } from "#server/files/markdownPath.ts";
+import { metadataParse } from "#server/metadata/parse.ts";
+import { questionId, revisionOf } from "#server/responses/records.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+
+export function handoffSource(root: string, realRoot: string, snapshot: Effect.Effect<Snapshot, ResponseRejection>, fs: FileSystem.FileSystem) {
+	return Effect.fn("WorkBoard.handoffSource")(function* (item: string) {
+		const data = yield* snapshot;
+		const matches = data.model.ids.get(item);
+		if (data.unavailable.length > 0 || matches?.length !== 1 || !matches[0]) {
+			return yield* Effect.fail(new NotFound({ message: "The item is missing, ambiguous or unavailable." }));
+		}
+		const file = matches[0].file;
+		const real = yield* markdownPath(root, realRoot, file);
+		if (!real) {
+			return yield* Effect.fail(new ServiceUnavailable({ message: "The handoff source could not be read." }));
+		}
+		const context = yield* fs.readFileString(real).pipe(
+			rpcBoundary(ServiceUnavailable, {
+				message: "The handoff source could not be read.",
+				unexpected: (message) => new ServiceUnavailable({ message }),
+			}),
+		);
+		const fields = metadataParse(context).fields;
+		if (fields.id !== item || fields.kind === "question" || fields.kind === "response" || fields.kind === "handoff") {
+			return yield* Effect.fail(new PreconditionFailed({ message: "Choose a current project item for this handoff." }));
+		}
+		if (new TextEncoder().encode(context).length > 256 * 1024) {
+			return yield* Effect.fail(new BadRequest({ message: "Handoff context is limited to 256 KiB. Choose a focused item." }));
+		}
+		const reviewedRevision = revisionOf(context);
+		const preview: HandoffPreview = { context, id: questionId(item, "handoff", reviewedRevision, file), item, reviewedRevision, source: file };
+		return preview;
+	});
+}

package/src/server/history/baseline.ts

@@ -0,0 +1,43 @@
+import { Option, Schema } from "effect";
+import { Baseline } from "#history/schema.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { MAX_AGE, MAX_BYTES } from "./limits.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/server/history/compare.ts

@@ -0,0 +1,54 @@
+import type { Baseline } from "#history/schema.ts";
+import { type HistoryDocument, historyDocuments, historyIdentities } from "./documents.ts";
+import { historyFields } from "./fields.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/server/history/documents.ts

@@ -0,0 +1,21 @@
+import type { Baseline } from "#history/schema.ts";
+import { metadataParse, type ParsedMetadata } from "#server/metadata/parse.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/server/history/html.ts

@@ -0,0 +1,23 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { fileUrl } from "#files/url.ts";
+import type { Baseline } from "#history/schema.ts";
+import { compareHistory, type SourceChange } from "./compare.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/server/history/response.ts

@@ -0,0 +1,23 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { HistoryOutput } from "#history/schema.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { observeBaseline, readBaseline } from "./baseline.ts";
+import { historyHtml } from "./html.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/server/http/assets.ts

@@ -0,0 +1,133 @@
+import { createRequire } from "node:module";
+import { Effect, FileSystem, Path, Schema } from "effect";
+import type { HttpRouter, HttpServerRequest } from "effect/unstable/http";
+import { InternalServerError } from "@shivaedev/platform/errors/taxonomy.ts";
+import { diagnosticsScript } from "#client/diagnostics/script.ts";
+import { historyScript } from "#client/history/script.ts";
+import { ageScript } from "#client/page/ageScript.ts";
+import { libraryScript } from "#client/page/libraryScript.ts";
+import { navigationScript } from "#client/page/navigationScript.ts";
+import { readingStateScript } from "#client/page/readingStateScript.ts";
+import { client, preferences } from "#client/page/runtime.ts";
+import { diagrams, swap } from "#client/page/scripts.ts";
+import { searchResultsScript } from "#client/page/searchResultsScript.ts";
+import { searchScript } from "#client/page/searchScript.ts";
+import { sidebarScript } from "#client/page/sidebarScript.ts";
+import { pageStateScript } from "#client/page/stateScript.ts";
+import { visualScript } from "#client/page/visualScript.ts";
+import { visualViewport } from "#client/page/visualViewport.ts";
+import { savedScript } from "#client/views/savedScript.ts";
+import { style } from "#server/page/style.ts";
+import { respond } from "./respond.ts";
+
+export const ASSETS: ReadonlyArray<readonly [HttpRouter.PathInput, string, string]> = [
+	["/_board/style.css", style, "text/css"],
+	["/_board/diagnostics.js", diagnosticsScript(), "text/javascript"],
+	["/_board/visuals.js", visualScript(), "text/javascript"],
+	["/_board/visual-viewport.js", visualViewport(), "text/javascript"],
+	["/_board/saved-views.js", savedScript(), "text/javascript"],
+	["/_board/client.js", client, "text/javascript"],
+	["/_board/ages.js", ageScript(), "text/javascript"],
+	["/_board/history.js", historyScript(), "text/javascript"],
+	["/_board/preferences.js", preferences, "text/javascript"],
+	["/_board/search.js", searchScript(), "text/javascript"],
+	["/_board/search-results.js", searchResultsScript(), "text/javascript"],
+	["/_board/sidebar.js", sidebarScript(), "text/javascript"],
+	["/_board/library.js", libraryScript(), "text/javascript"],
+	["/_board/navigation.js", navigationScript(), "text/javascript"],
+	["/_board/page-state.js", pageStateScript(), "text/javascript"],
+	["/_board/reading-state.js", readingStateScript(), "text/javascript"],
+	["/_board/diagrams.js", diagrams, "text/javascript"],
+	["/_board/swap.js", swap, "text/javascript"],
+];
+
+const MERMAID = "/_board/mermaid/";
+
+export class MermaidMissing extends Schema.TaggedError<MermaidMissing>()("MermaidMissing", { cause: Schema.Unknown }) {
+	override get message() {
+		return "The Mermaid assets could not be found. Reinstall Work Board and restart it.";
+	}
+}
+
+export const mermaidRoot = Effect.fn("WorkBoard.mermaidRoot")(function* () {
+	const path = yield* Path.Path;
+	const entry = yield* Effect.try({ catch: (cause) => new MermaidMissing({ cause }), try: () => createRequire(import.meta.url).resolve("mermaid") });
+	return path.dirname(entry);
+});
+
+export function mermaidFile(root: string) {
+	return Effect.fn("WorkBoard.mermaidFile")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const file = path.resolve(root, new URL(request.url, "http://127.0.0.1").pathname.slice(MERMAID.length));
+		if (!(file.startsWith(`${root}${path.sep}`) && file.endsWith(".mjs") && (yield* fs.exists(file)))) {
+			return respond("Not found", "text/plain", 404);
+		}
+		return respond(yield* fs.readFile(file), "text/javascript");
+	});
+}
+
+export const MERMAID_ROUTE: HttpRouter.PathInput = `${MERMAID}*`;
+
+export const NATIVE_ROUTE: HttpRouter.PathInput = "/_board/native.js";
+function missingBundle(file: string) {
+	return `Work Board browser bundle assets/${file} is missing. Run pnpm --filter @shivaedev/work-board build:browser from the repository root to build it.`;
+}
+
+const bundledPath = Effect.fn("WorkBoard.bundledPath")(function* (file: string) {
+	const path = yield* Path.Path;
+	const module = yield* path
+		.fromFileUrl(new URL(import.meta.url))
+		.pipe(Effect.mapError(() => new InternalServerError({ message: "The browser asset location is invalid. Reinstall Work Board and restart it." })));
+	return path.resolve(path.dirname(module), "../../../assets", file);
+});
+
+const checkAssets = Effect.fn("WorkBoard.checkAssets")(function* (files: readonly string[]) {
+	const fs = yield* FileSystem.FileSystem;
+	for (const file of files) {
+		if (!(yield* fs.exists(yield* bundledPath(file)))) {
+			yield* Effect.logWarning(missingBundle(file));
+		}
+	}
+});
+
+export function checkNativeAsset() {
+	return checkAssets(["native.js"]);
+}
+export function checkBrowserAssets() {
+	return checkAssets(["native.js", "react.js", "react.css"]);
+}
+export const nativeAsset = bundledAsset("native.js", "text/javascript");
+
+const BUNDLED_ASSETS: ReadonlyArray<readonly [HttpRouter.PathInput, ReturnType<typeof bundledAsset>]> = [
+	[NATIVE_ROUTE, nativeAsset],
+	["/_board/react.js", bundledAsset("react.js", "text/javascript")],
+	["/_board/react.css", bundledAsset("react.css", "text/css")],
+];
+
+const reactChunk = Effect.fn("WorkBoard.reactChunk")(function* (request: HttpServerRequest.HttpServerRequest) {
+	const name = new URL(request.url, "http://127.0.0.1").pathname.slice("/_board/react-assets/".length);
+	if (!/^[a-zA-Z\d_-]+\.js$/u.test(name)) {
+		return respond("Not found", "text/plain", 404);
+	}
+	return yield* bundledAsset(`react-assets/${name}`, "text/javascript")();
+});
+
+function bundledAsset(file: string, contentType: string) {
+	return Effect.fn("WorkBoard.bundledAsset")(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		return yield* fs.readFile(yield* bundledPath(file)).pipe(
+			Effect.map((body) => respond(body, contentType)),
+			Effect.catchIf(
+				(error) => error.reason._tag === "NotFound",
+				() => Effect.succeed(respond(missingBundle(file), "text/plain", 500)),
+			),
+		);
+	});
+}
+
+export const ASSET_HANDLERS = [
+	...ASSETS.map(([route, body, type]) => [route, () => Effect.succeed(respond(body, type))] as const),
+	...BUNDLED_ASSETS,
+	["/_board/react-assets/*", reactChunk] as const,
+];

package/src/server/http/attachment.ts

@@ -0,0 +1,46 @@
+import { Effect, FileSystem, Path } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { attachmentType } from "#path/attachment.ts";
+import { within } from "#server/files/list.ts";
+import { respond } from "./respond.ts";
+
+const MAX_BYTES = 16 * 1024 * 1024;
+
+export function attachment(root: string, realRoot: string) {
+	return Effect.fn("WorkBoard.attachment")(function* (request: HttpServerRequest.HttpServerRequest) {
+		function missing() {
+			return respond("Local image unavailable: unsupported type, missing file or workspace boundary.", "text/plain", 404);
+		}
+		let relative: string;
+		try {
+			relative = decodeURIComponent(new URL(request.url, "http://127.0.0.1").pathname.slice("/_board/attachment/".length));
+		} catch {
+			return missing();
+		}
+		const type = attachmentType(relative);
+		if (
+			!type
+			|| relative.includes("\\")
+			|| relative.split("/").some((part) => !part || part === ".." || part.startsWith(".") || part === "node_modules")
+		) {
+			return missing();
+		}
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		return yield* Effect.gen(function* () {
+			const real = yield* fs.realPath(path.join(root, relative));
+			if (!within(realRoot, path.sep, real)) {
+				return missing();
+			}
+			const info = yield* fs.stat(real);
+			if (info.type !== "File") {
+				return missing();
+			}
+			if (info.size > BigInt(MAX_BYTES)) {
+				return respond("Local image exceeds the 16 MiB limit.", "text/plain", 413);
+			}
+			const body = yield* fs.readFile(real);
+			return body.byteLength > MAX_BYTES ? respond("Local image exceeds the 16 MiB limit.", "text/plain", 413) : respond(body, type);
+		}).pipe(Effect.orElseSucceed(missing));
+	});
+}