@shivaedev/work-board 0.0.0 → 0.2.0

package/src/files/changes.ts

@@ -0,0 +1,71 @@
+import { Data, Deferred, Effect, FileSystem, Option, Path, type PlatformError, PubSub, Ref, Schedule, Stream } from "effect";
+import { isMarkdown, listMarkdown, type MarkdownFile } from "./list.ts";
+
+export type Change = { readonly _tag: "Changed"; readonly paths: ReadonlyArray<string> } | { readonly _tag: "Watching"; readonly watching: boolean };
+
+export interface Changes {
+	readonly realRoot: string;
+	readonly events: PubSub.PubSub<Change>;
+	readonly watching: Ref.Ref<boolean>;
+	readonly files: Effect.Effect<ReadonlyArray<MarkdownFile>, PlatformError.PlatformError>;
+}
+
+interface Cached {
+	readonly generation: number;
+	readonly files: ReadonlyArray<MarkdownFile>;
+}
+
+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")]);
+
+export const watchChanges = Effect.fn("WorkBoard.watchChanges")(function* (root: string) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const realRoot = yield* fs.realPath(root);
+	const events = yield* Effect.acquireRelease(PubSub.sliding<Change>(BACKLOG), PubSub.shutdown);
+	const watching = yield* Ref.make(false);
+	const generation = yield* Ref.make(0);
+	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) =>
+				was === now ? Effect.void : Effect.andThen(stale, PubSub.publish(events, { _tag: "Watching", watching: now })),
+			),
+			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));
+	yield* attempt.pipe(
+		Effect.sandbox,
+		Effect.tapError((cause) => Effect.andThen(setWatching(false), Effect.logWarning("Watching the folder failed; retrying", cause))),
+		Effect.retry(RETRY),
+		Effect.forkScoped,
+	);
+	yield* Deferred.await(settled);
+	const files = Effect.gen(function* () {
+		const now = yield* Ref.get(generation);
+		const hit = Option.filter(yield* Ref.get(cached), (entry) => entry.generation === now);
+		if ((yield* Ref.get(watching)) && Option.isSome(hit)) {
+			return hit.value.files;
+		}
+		const listed = yield* listMarkdown(root, realRoot).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+		yield* Ref.set(cached, Option.some({ generation: now, files: listed }));
+		return listed;
+	});
+	const changes: Changes = { realRoot, events, watching, files };
+	return changes;
+});

package/src/files/home.ts

@@ -0,0 +1,37 @@
+import { Data, Effect, FileSystem, Option, Path } from "effect";
+import { listMarkdown } from "./list.ts";
+
+export class HomeMissing extends Data.TaggedError("HomeMissing")<{ readonly message: string }> {}
+
+export const homeIn = Effect.fn("WorkBoard.homeIn")(function* (root: string, home: string | undefined) {
+	if (home === undefined) {
+		return undefined;
+	}
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const missing = new HomeMissing({ message: `The home file ${home} is not a markdown file in ${root}` });
+	const realRoot = yield* fs.realPath(root);
+	const real = yield* Effect.option(fs.realPath(path.resolve(root, home)));
+	if (Option.isNone(real)) {
+		return yield* missing;
+	}
+	const target = yield* Effect.option(fs.stat(real.value));
+	if (Option.isNone(target)) {
+		return yield* missing;
+	}
+	const files = yield* listMarkdown(root, realRoot);
+	const relative = path.relative(realRoot, real.value).split(path.sep).join("/");
+	if (files.some((file) => file.path === relative)) {
+		return relative;
+	}
+	const inode = Option.getOrUndefined(target.value.ino);
+	const same = (info: FileSystem.File.Info) => inode !== undefined && info.dev === target.value.dev && Option.getOrUndefined(info.ino) === inode;
+	const matches = yield* Effect.filter(files, (file) =>
+		Effect.map(Effect.option(fs.stat(path.join(realRoot, file.path))), (info) => Option.isSome(info) && same(info.value)),
+	);
+	const direct = yield* Effect.filter(matches, (file) =>
+		Effect.map(Effect.option(fs.realPath(path.join(realRoot, file.path))), (real) => Option.contains(real, path.join(realRoot, file.path))),
+	);
+	const chosen = matches.find((file) => file.path.toLowerCase() === relative.toLowerCase()) ?? direct[0] ?? matches[0];
+	return chosen === undefined ? yield* missing : chosen.path;
+});

package/src/files/list.ts

@@ -0,0 +1,55 @@
+import { Effect, FileSystem, Option, Path, type PlatformError } from "effect";
+
+export interface MarkdownFile {
+	readonly path: string;
+	readonly modified: number;
+}
+
+const skipped = (segment: string): boolean => segment.startsWith(".") || segment === "node_modules";
+
+export const isMarkdown = (path: string): boolean => path.endsWith(".md") && !path.split("/").some(skipped);
+
+export const within = (realRoot: string, separator: string, real: string): boolean => real === realRoot || real.startsWith(`${realRoot}${separator}`);
+
+const folderOf = (path: string): string => path.slice(0, Math.max(0, path.lastIndexOf("/")));
+
+const byFolder = (left: string, right: string): number => folderOf(left).localeCompare(folderOf(right)) || left.localeCompare(right);
+
+type Listing = Effect.Effect<ReadonlyArray<MarkdownFile>, PlatformError.PlatformError>;
+
+export const listMarkdown = Effect.fn("WorkBoard.listMarkdown")(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 =>
+		Effect.gen(function* () {
+			const real = yield* Effect.option(fs.realPath(path.join(root, relative)));
+			if (Option.isNone(real) || !within(realRoot, path.sep, real.value)) {
+				return [];
+			}
+			const info = yield* Effect.option(fs.stat(real.value));
+			if (Option.isNone(info)) {
+				return [];
+			}
+			if (info.value.type === "Directory") {
+				return yield* Effect.orElseSucceed(folder(relative, real.value), () => []);
+			}
+			const modified = Option.match(info.value.mtime, { onNone: () => 0, onSome: (date) => date.getTime() });
+			return info.value.type === "File" && relative.endsWith(".md") ? [{ path: relative, modified }] : [];
+		});
+	const folder = (relative: string, real: string): Listing =>
+		Effect.gen(function* () {
+			if (visited.has(real)) {
+				return [];
+			}
+			visited.add(real);
+			const names = yield* fs.readDirectory(real);
+			const found = yield* Effect.forEach(
+				names.filter((name) => !skipped(name)),
+				(name) => entry(relative === "" ? name : `${relative}/${name}`),
+			);
+			return found.flat();
+		});
+	const files = yield* folder("", realRoot);
+	return files.toSorted((left, right) => byFolder(left.path, right.path));
+});

package/src/http/assets.ts

@@ -0,0 +1,38 @@
+import { createRequire } from "node:module";
+import { Data, Effect, FileSystem, Path } from "effect";
+import type { HttpRouter, HttpServerRequest } from "effect/unstable/http";
+import { client } from "../page/client.ts";
+import { diagrams } from "../page/diagrams.ts";
+import { style } from "../page/style.ts";
+import { swap } from "../page/swap.ts";
+import { respond } from "./respond.ts";
+
+export const ASSETS: ReadonlyArray<readonly [HttpRouter.PathInput, string, string]> = [
+	["/_board/style.css", style, "text/css"],
+	["/_board/client.js", client, "text/javascript"],
+	["/_board/diagrams.js", diagrams, "text/javascript"],
+	["/_board/swap.js", swap, "text/javascript"],
+];
+
+const MERMAID = "/_board/mermaid/";
+
+export class MermaidMissing extends Data.TaggedError("MermaidMissing")<{ readonly cause: unknown }> {}
+
+export const mermaidRoot = Effect.fn("WorkBoard.mermaidRoot")(function* () {
+	const path = yield* Path.Path;
+	const entry = yield* Effect.try({ try: () => createRequire(import.meta.url).resolve("mermaid"), catch: (cause) => new MermaidMissing({ cause }) });
+	return path.dirname(entry);
+});
+
+export const mermaidFile = (mermaidRoot: string) =>
+	Effect.fn("WorkBoard.mermaidFile")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const file = path.resolve(mermaidRoot, new URL(request.url, "http://127.0.0.1").pathname.slice(MERMAID.length));
+		if (!file.startsWith(`${mermaidRoot}${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}*`;

package/src/http/events.ts

@@ -0,0 +1,29 @@
+import { Effect, PubSub, Ref, Stream } from "effect";
+import { Sse } from "effect/unstable/encoding";
+import { HttpServerResponse } from "effect/unstable/http";
+import type { Change, Changes } from "../files/changes.ts";
+import { HEADERS } from "./respond.ts";
+
+const event = (name: string, data = ""): Sse.Event => ({ _tag: "Event", event: name, id: undefined, data });
+
+const watching = (up: boolean): Sse.Event => event(up ? "ready" : "down");
+
+const eventOf = (change: Change): Sse.Event =>
+	change._tag === "Changed" ? event("change", JSON.stringify({ paths: change.paths })) : watching(change.watching);
+
+const subscribed = (changes: Changes) =>
+	Stream.unwrap(
+		Effect.gen(function* () {
+			const subscription = yield* PubSub.subscribe(changes.events);
+			const now = yield* Ref.get(changes.watching);
+			return Stream.concat(Stream.succeed(watching(now)), Stream.map(Stream.fromSubscription(subscription), eventOf));
+		}),
+	);
+
+export const events = (changes: Changes) => () =>
+	Effect.succeed(
+		HttpServerResponse.stream(Stream.encodeText(Stream.map(subscribed(changes), (message) => Sse.encoder.write(message))), {
+			contentType: "text/event-stream",
+			headers: HEADERS,
+		}),
+	);

package/src/http/loopback.ts

@@ -0,0 +1,29 @@
+import { Effect, Option } from "effect";
+import type { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { respond } from "./respond.ts";
+
+const LOOPBACK_NAMES = new Set(["127.0.0.1", "localhost", "[::1]"]);
+
+const hostnameOf = (host: string): string | undefined => {
+	try {
+		return new URL(`http://${host}/`).hostname;
+	} catch {
+		return undefined;
+	}
+};
+
+const loopbackAddress = (address: string): boolean => {
+	const unmapped = address.replace(/^::ffff:/i, "");
+	return unmapped === "::1" || /^127(?:\.\d{1,3}){3}$/.test(unmapped);
+};
+
+const fromLoopback = (request: HttpServerRequest.HttpServerRequest): boolean => {
+	const host = request.headers.host;
+	const addressed = host !== undefined && LOOPBACK_NAMES.has(hostnameOf(host) ?? "");
+	return addressed && Option.match(request.remoteAddress, { onNone: () => true, onSome: loopbackAddress });
+};
+
+export const loopbackOnly =
+	<E, R>(handler: (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>) =>
+	(request: HttpServerRequest.HttpServerRequest) =>
+		fromLoopback(request) ? handler(request) : Effect.succeed(respond("Only loopback hosts are served", "text/plain", 403));

package/src/http/page.ts

@@ -0,0 +1,54 @@
+import { Effect, FileSystem, Option, Path } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import type { Changes } from "../files/changes.ts";
+import { type MarkdownFile, within } from "../files/list.ts";
+import { boardHtml } from "../page/board.ts";
+import { documentHtml } from "../page/document.ts";
+import { escapeHtml } from "../page/escape.ts";
+import { navHtml } from "../page/nav.ts";
+import { shell } from "../page/shell.ts";
+import { boardOf } from "../render/board.ts";
+import { respond } from "./respond.ts";
+
+export interface PageOptions {
+	readonly root: string;
+	readonly home: string | undefined;
+}
+
+const requestedPath = (url: string): string => {
+	const pathname = new URL(url, "http://127.0.0.1").pathname.replace(/^\/+/, "");
+	try {
+		return decodeURIComponent(pathname);
+	} catch {
+		return pathname;
+	}
+};
+
+const message = (text: string): string => `<p class="empty">${escapeHtml(text)}</p>`;
+
+export const page = (options: PageOptions, changes: Changes) => {
+	const body = Effect.fn("WorkBoard.pageBody")(function* (file: MarkdownFile) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const real = yield* Effect.option(fs.realPath(path.join(options.root, file.path)));
+		if (Option.isNone(real) || !within(changes.realRoot, path.sep, real.value)) {
+			return Option.none();
+		}
+		const source = yield* fs.readFileString(real.value);
+		return Option.some(file.path === options.home ? yield* boardHtml(boardOf(source), file.path, file.modified) : yield* documentHtml(source, file));
+	});
+	return Effect.fn("WorkBoard.page")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const files = yield* changes.files;
+		const requested = requestedPath(request.url) || options.home || files[0]?.path || "";
+		const file = files.find((candidate) => candidate.path === requested);
+		const nav = navHtml(files, requested, options.home);
+		const missing = () => respond(shell(requested, nav, message(`No markdown file at ${requested || options.root}.`)), "text/html", 404);
+		if (file === undefined) {
+			return missing();
+		}
+		return yield* body(file).pipe(
+			Effect.map(Option.match({ onNone: missing, onSome: (main) => respond(shell(file.path, nav, main), "text/html") })),
+			Effect.catch(() => Effect.succeed(respond(shell(file.path, nav, message(`${file.path} could not be read.`)), "text/html", 500))),
+		);
+	});
+};

package/src/http/respond.ts

@@ -0,0 +1,18 @@
+import { HttpServerResponse } from "effect/unstable/http";
+
+const POLICY = [
+	"default-src 'self'",
+	"script-src 'self'",
+	"style-src 'self' 'unsafe-inline'",
+	"img-src 'self' data: https:",
+	"object-src 'none'",
+	"base-uri 'none'",
+	"frame-ancestors 'none'",
+].join("; ");
+
+export const HEADERS = { "cache-control": "no-store", "content-security-policy": POLICY, "x-content-type-options": "nosniff" };
+
+export const respond = (body: string | Uint8Array, contentType: string, status = 200): HttpServerResponse.HttpServerResponse =>
+	typeof body === "string"
+		? HttpServerResponse.text(body, { contentType: `${contentType}; charset=utf-8`, headers: HEADERS, status })
+		: HttpServerResponse.uint8Array(body, { contentType, headers: HEADERS, status });

package/src/index.ts

@@ -0,0 +1 @@
+export { type BoardOptions, boardLayer } from "./board.ts";

package/src/page/board.ts

@@ -0,0 +1,37 @@
+import { Effect } from "effect";
+import { type Board, countsOf, type Section } from "../render/board.ts";
+import { renderMarkdown } from "../render/markdown.ts";
+import { escapeHtml } from "./escape.ts";
+import { updated } from "./updated.ts";
+
+const counts = (board: Board): string =>
+	countsOf(board)
+		.map(({ count, title }) => `<span><b>${count}</b> ${escapeHtml(title.toLowerCase())}</span>`)
+		.join(" · ");
+
+type Render = (fragment: string) => ReturnType<typeof renderMarkdown>;
+
+const section = Effect.fn("WorkBoard.section")(function* ({ heading, items, notes }: Section, render: Render) {
+	const rendered = yield* Effect.forEach(items, (item) => Effect.map(render(item), (html) => `<article class="item">${html}</article>`));
+	const note = notes === "" ? "" : `<div class="notes">${yield* render(notes)}</div>`;
+	return `<section>${yield* render(heading)}${note}${rendered.join("")}</section>`;
+});
+
+export const boardHtml = Effect.fn("WorkBoard.boardHtml")(function* (board: Board, fallbackTitle: string, modified: number) {
+	let fragments = 0;
+	const render: Render = (fragment) => {
+		fragments += 1;
+		return renderMarkdown(board.definitions === "" ? fragment : `${fragment}\n\n${board.definitions}`, `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 [
+		`<header class="board-head">${title}${intro}`,
+		`<p class="counts">${counts(board)}</p>`,
+		`<p class="meta">${updated(modified)}</p></header>`,
+		`<div class="board">${sections.join("")}</div>`,
+		footer,
+	].join("");
+});

package/src/page/client.ts

@@ -0,0 +1,90 @@
+export const client = `
+import { renderDiagrams } from "/_board/diagrams.js";
+import { remember, swap } from "/_board/swap.js";
+
+const since = (modified) => {
+  const seconds = Math.max(0, Math.round((Date.now() - modified) / 1000));
+  if (seconds < 60) return seconds + "s";
+  if (seconds < 3600) return Math.round(seconds / 60) + "m";
+  if (seconds < 172800) return Math.round(seconds / 3600) + "h";
+  return Math.round(seconds / 86400) + "d";
+};
+
+const tick = () => {
+  for (const age of document.querySelectorAll("[data-modified]")) {
+    const ago = since(Number(age.dataset.modified));
+    age.textContent = age.classList.contains("short") ? ago : "updated " + ago + " ago";
+  }
+};
+
+remember(document.getElementById("files"));
+remember(document.getElementById("doc"));
+
+const live = document.getElementById("live");
+let connected = false;
+let dropped = true;
+let failure = "";
+
+const show = () => {
+  const state = failure !== "" ? "stale" : connected ? "live" : "down";
+  live.dataset.state = state;
+  live.textContent = failure !== "" ? failure : connected ? "live" : "reconnecting";
+};
+
+const load = async () => {
+  try {
+    const response = await fetch(location.pathname, { cache: "no-store" });
+    const next = new DOMParser().parseFromString(await response.text(), "text/html");
+    const files = next.getElementById("files");
+    const doc = next.getElementById("doc");
+    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;
+    tick();
+    renderDiagrams(document);
+  } catch {
+    failure = "refresh failed";
+  }
+};
+
+let loading = false;
+let dirty = false;
+const refresh = async () => {
+  if (loading) {
+    dirty = true;
+    return;
+  }
+  loading = true;
+  do {
+    dirty = false;
+    await load();
+  } while (dirty);
+  loading = false;
+  show();
+};
+
+const events = new EventSource("/events");
+events.addEventListener("ready", () => {
+  connected = true;
+  show();
+  if (dropped) refresh();
+  dropped = false;
+});
+const down = () => {
+  connected = false;
+  dropped = true;
+  show();
+};
+events.addEventListener("change", refresh);
+events.addEventListener("down", down);
+events.addEventListener("error", down);
+
+tick();
+setInterval(tick, 5000);
+renderDiagrams(document);
+`;

package/src/page/diagrams.ts

@@ -0,0 +1,72 @@
+export const diagrams = `
+const rendered = new Map();
+const dark = matchMedia("(prefers-color-scheme: dark)");
+let mermaid;
+let counter = 0;
+
+const token = (name) => getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+
+const load = async () => {
+  mermaid ??= (await import("/_board/mermaid/mermaid.esm.min.mjs")).default;
+  mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: "strict",
+    theme: "base",
+    themeVariables: {
+      darkMode: dark.matches,
+      background: token("--bg"),
+      primaryColor: token("--surface"),
+      primaryTextColor: token("--text"),
+      primaryBorderColor: token("--border"),
+      lineColor: token("--muted"),
+      textColor: token("--text"),
+      fontFamily: token("--sans"),
+    },
+  });
+  return mermaid;
+};
+
+const schemeNow = () => (dark.matches ? "dark" : "light");
+
+const draw = async (figure) => {
+  const source = figure.querySelector(".diagram-source").textContent;
+  const scheme = schemeNow();
+  const key = scheme + ":" + source;
+  if (!rendered.has(key)) {
+    rendered.set(key, load().then((engine) => engine.render("diagram-" + ++counter, source)).then((result) => result.svg));
+  }
+  try {
+    const svg = await rendered.get(key);
+    if (scheme !== schemeNow()) {
+      rendered.delete(key);
+      return;
+    }
+    figure.querySelector(".diagram-svg")?.remove();
+    figure.insertAdjacentHTML("afterbegin", '<div class="diagram-svg">' + svg + "</div>");
+    figure.dataset.state = "drawn";
+  } catch (error) {
+    rendered.delete(key);
+    if (scheme !== schemeNow()) return;
+    figure.querySelector(".diagram-svg")?.remove();
+    figure.dataset.state = "failed";
+    figure.dataset.error = String(error?.message ?? error);
+  }
+};
+
+const forget = (root) => {
+  const shown = new Set([...root.querySelectorAll("figure.diagram .diagram-source")].map((source) => source.textContent));
+  for (const key of rendered.keys()) {
+    if (!shown.has(key.slice(key.indexOf(":") + 1))) rendered.delete(key);
+  }
+};
+
+export const renderDiagrams = (root, selector = "figure.diagram:not([data-state=drawn])") => {
+  forget(root);
+  return Promise.all([...root.querySelectorAll(selector)].map(draw));
+};
+
+dark.addEventListener("change", () => {
+  mermaid = undefined;
+  renderDiagrams(document, "figure.diagram");
+});
+`;

package/src/page/document.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import type { MarkdownFile } from "../files/list.ts";
+import { renderMarkdown } from "../render/markdown.ts";
+import { escapeHtml } from "./escape.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>`;
+});

package/src/page/escape.ts

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

package/src/page/nav.ts

@@ -0,0 +1,28 @@
+import type { MarkdownFile } from "../files/list.ts";
+import { escapeHtml } from "./escape.ts";
+
+const nameOf = (path: string): string => path.slice(path.lastIndexOf("/") + 1).replace(/\.md$/, "");
+
+const folderOf = (path: string): string => path.slice(0, Math.max(0, path.lastIndexOf("/")));
+
+const hrefOf = (path: string): string => `/${path.split("/").map(encodeURIComponent).join("/")}`;
+
+const link = (file: MarkdownFile, current: string): string => {
+	const here = file.path === current ? ' aria-current="page"' : "";
+	const age = `<span class="age short" data-modified="${file.modified}"></span>`;
+	return `<a href="${hrefOf(file.path)}"${here}>${escapeHtml(nameOf(file.path))}</a>${age}`;
+};
+
+const folder = (name: string, files: ReadonlyArray<MarkdownFile>, current: string): string => {
+	const links = files.map((file) => `<li>${link(file, current)}</li>`).join("");
+	const open = files.some((file) => file.path === current) ? " open" : "";
+	return `<details data-key="folder:${escapeHtml(name)}"${open}><summary>${escapeHtml(name)}/ (${files.length})</summary><ul>${links}</ul></details>`;
+};
+
+export const navHtml = (files: ReadonlyArray<MarkdownFile>, current: string, home: string | undefined): string => {
+	const ordered = [...files.filter((file) => file.path === home), ...files.filter((file) => file.path !== home)];
+	const folders = Map.groupBy(ordered, (file) => (file.path === home ? "" : folderOf(file.path)));
+	return [...folders]
+		.map(([name, grouped]) => (name === "" ? grouped.map((file) => `<span>${link(file, current)}</span>`).join("") : folder(name, grouped, current)))
+		.join("");
+};

package/src/page/shell.ts

@@ -0,0 +1,12 @@
+import { escapeHtml } from "./escape.ts";
+
+export const shell = (title: string, nav: string, main: string): string =>
+	[
+		'<!doctype html><html lang="en"><head><meta charset="utf-8">',
+		'<meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="light dark">',
+		`<title>${escapeHtml(title)}</title>`,
+		'<link rel="stylesheet" href="/_board/style.css"><script type="module" src="/_board/client.js"></script>',
+		'</head><body><div class="page"><header class="bar">',
+		`<nav id="files" class="files">${nav}</nav><span id="live" class="live">connecting</span></header>`,
+		`<main id="doc">${main}</main></div></body></html>`,
+	].join("");