@gavin-hu/my-pi-agent 0.19.0 → 0.21.0

package/lib/tui/render-cache.ts

@@ -31,6 +31,8 @@
 export class RenderCache {
 	private width: number | null = null;
 	private source: readonly string[] | undefined;
+	/** The last key's parts, for the value-keyed form; `undefined` until one is set. */
+	private parts: readonly unknown[] | undefined;
 	private cached: string[] = [];
 
 	/**
@@ -47,9 +49,36 @@ export class RenderCache {
 		return this.cached;
 	}
 
+	/**
+	 * The lines from `build()`, for a component that derives them from a key.
+	 *
+	 * The identity form above chains on the inner component's array. A component with no
+	 * inner component has nothing to chain on — a header's view and a footer's snapshot are
+	 * rebuilt every frame — so it describes its inputs instead, and this compares them:
+	 * primitives by value, and anything else by identity (a theme object is the case that
+	 * matters, since its strings are what get cached).
+	 *
+	 * The key is only as complete as the caller makes it: a part left out is a frame that
+	 * shows stale lines. Positions are compared, so an undefined part is a real one.
+	 */
+	keyed(parts: readonly unknown[], build: () => string[]): string[] {
+		const previous = this.parts;
+		if (
+			previous !== undefined &&
+			previous.length === parts.length &&
+			previous.every((part, at) => part === parts[at])
+		) {
+			return this.cached;
+		}
+		this.cached = build();
+		this.parts = [...parts];
+		return this.cached;
+	}
+
 	/** Drop the memo; call from the component's `invalidate()`. */
 	invalidate(): void {
 		this.width = null;
+		this.parts = undefined;
 		this.cached = [];
 	}
 }

package/lib/tui/tool.ts

@@ -22,6 +22,7 @@ import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
 import { formatDuration, sanitizeLine, stripControlChars } from "../format.ts";
 import { clip, clipMiddle } from "./columns.ts";
 import { expandHint, SEPARATORS } from "./glyphs.ts";
+import { RenderCache } from "./render-cache.ts";
 import { paint } from "./tokens.ts";
 
 /** The parts of a tool result a renderer reads. */
@@ -223,10 +224,18 @@ export type TailResultInput<Row> =
  * section, or the themed tail with an "earlier" note. The caller owns the row
  * renderer, so the extension's own row grammar — a peer-session tag, a status
  * glyph — stays with its vocabulary.
+ *
+ * `render` runs on every frame Pi draws, for every block in the transcript, and
+ * this block is the shared one behind the board's card, a session's peer list and
+ * a shaped tail — each of which re-derived its rows and clipped every line per
+ * frame before this memo. The lines depend on the input, the theme and the width,
+ * and none of them changes without `setInput`, `invalidate`, or a new width, so
+ * the memo is keyed on the width and dropped by those two calls.
  */
 export class TailResult<Row> implements Component {
 	private input: TailResultInput<Row>;
 	private theme: Theme;
+	private readonly cache = new RenderCache();
 
 	constructor(input: TailResultInput<Row>, theme: Theme) {
 		this.input = input;
@@ -237,12 +246,19 @@ export class TailResult<Row> implements Component {
 	setInput(input: TailResultInput<Row>, theme: Theme): void {
 		this.input = input;
 		this.theme = theme;
+		this.cache.invalidate();
 	}
 
-	invalidate(): void {}
+	invalidate(): void {
+		this.cache.invalidate();
+	}
 
 	render(width: number): string[] {
 		const w = Math.max(1, width);
+		return this.cache.lines(w, undefined, () => this.build(w));
+	}
+
+	private build(w: number): string[] {
 		const lines: string[] = [""];
 		const input = this.input;
 		if (input.kind === "list") {
@@ -264,6 +280,19 @@ export class TailResult<Row> implements Component {
 	}
 }
 
+/**
+ * Whether the component the transcript handed back is this kit's tail block.
+ *
+ * `TailResult` carries its row type and `instanceof` erases it. The caller is the
+ * one that knows which rows it drew, so the claim lives here as a guard rather
+ * than as a cast in each extension that reuses its block through
+ * `context.lastComponent` — and a component from another tool can only reach that
+ * check by being this class, which is why the erased type is safe to assert.
+ */
+export function isTailResult<Row>(value: unknown): value is TailResult<Row> {
+	return value instanceof TailResult;
+}
+
 /** The render context fields the elapsed timer needs. */
 export interface ToolRenderClock {
 	/** Pi's per-call render state, opaque here: this module only ever casts it. */

package/lib/web/README.md

@@ -21,6 +21,47 @@ counts its own stylesheet (`pages.test.ts`, `web.test.ts`). A page rule is
 namespaced (`review-*`, `browse-*`) and overrides a kit class rather than
 re-declaring it.
 
+## One browser runtime, spliced in
+
+Three surfaces render pages from a bundle held as a template literal, and each had written
+the same three helpers for itself: an element builder, a "did this key land in a field?"
+test, and a status line's paint. No type checker and no AST scan compares text inside a
+string, so the plan's `el(tag, className)` and the board's `el(tag, className, text)` were
+two builders, and the plan compared `INPUT` where the board lowercased the tag.
+
+`client-runtime.ts` holds one body of each, as ordinary TypeScript, and exports
+`CLIENT_RUNTIME_JS` — the four functions as source, in the order a client reads them. A
+page carries it the way it carries `plural` and its class table: the source crosses the
+boundary, and the page runs the function instead of a copy of it.
+
+The bodies are JavaScript on purpose — no annotation survives into the string, and no
+backtick or `${` may appear in one. The DOM is reached through `globalThis`, because this
+project compiles without a DOM lib; the cast names the guarantee the page makes.
+
+What stays page-side: what a status *says*. `paintStatus` owns the text, its tooltip, and
+the `bf-status--<tone>` class; the board composes `live · 3m` and appends its own class.
+A shared runtime that also decided the wording would be a second copy of the page's voice.
+
+## Name a class once, in a table
+
+A page's document is TypeScript and its client is a string inside a template literal, so
+the two halves cannot import from each other: a class name used to be a literal in each,
+and one assembled at runtime (`"board-card__reason" + kind`) could not be found by
+reading either half. That is how a class reaches a stylesheet with no rule behind it —
+an unstyled element, and nothing fails.
+
+So a page declares its vocabulary once, in a `ClassNames` table beside its own modules,
+and both halves read it: the document interpolates `${N.toolbar}`, the bundle carries
+`namesScript(table)`. A name is then a symbol, and a test can compare the set a page
+wears with the set its stylesheet draws, in both directions.
+
+`namesScript` is the boundary, and it throws rather than trusting a caller: a value must
+be `KEBAB` — lowercase, hyphenated — because the table is spliced into a template
+literal, and a backtick would end the string while `${` would interpolate at build time.
+The global it binds must be a JavaScript `IDENTIFIER`. The table's *keys* are the page's
+own English; its *values* are what CSS matches, and nothing else in the page may spell
+one.
+
 ## Color is a role
 
 `WEB_THEME_TOKENS` is derived from `themes/bytefly-dark.json` and
@@ -99,8 +140,17 @@ choice. Neither page reloads for a theme.
 
 ## Markup atoms and escaping
 
-`docHead`, `brandLockup`, `themeToggle`, `chip`, `button`, and `keysSheet` return
-strings. Every dynamic **value** goes through `escapeHtml` from
+`docHead`, `brandLockup`, `markIcon`, `tabTitle`, `themeToggle`, `chip`, `button`, and
+`keysSheet` return strings. `docHead` links the mark as the tab icon — two SVG
+data URIs from the same blocks the lockup draws, the dark one plain and the light
+one behind `prefers-color-scheme` — because an icon is its own document and
+cannot read the page's tokens.
+
+`tabTitle` is where the three served pages' tab titles agree: `<page> · <subject> ·
+<count>`, the page's name lowercase and the same word its `brandLockup` carries, a part
+the page does not have left out rather than drawn empty. The board's count is live, so
+its page repaints the title on every frame and the body crosses into the bundle as
+`TAB_TITLE_JS`, the way `plural` does — one shape for the string, not two. Every dynamic **value** goes through `escapeHtml` from
 [`../escape.ts`](../escape.ts); the fields documented as trusted (`css`, an
 `icon` glyph, an attribute key, a client id) are code-authored constants, never
 model or file text. A page that renders its own document follows the same rule.

package/lib/web/client-runtime.ts

@@ -0,0 +1,149 @@
+/**
+ * The browser runtime both page clients splice into their bundles: the element builder,
+ * the "is the user typing?" test, the status line, and the JSON POST.
+ *
+ * Two surfaces had written each of these for themselves, and because a bundle is a
+ * template literal no type checker and no AST scan ever compared them: the plan's
+ * `el(tag, className)` and the board's `el(tag, className, text)` were two builders, and
+ * the plan's `typing` compared `INPUT` where the board's lowercased the tag. Both are
+ * now one body, written here as real TypeScript, and each client carries the *source*
+ * (`CLIENT_RUNTIME_JS`) the same way it carries `plural` and the class table.
+ *
+ * The functions are plain JavaScript on purpose: their text is spliced into a bundle, so
+ * no annotation may survive into the string and no backtick or `${` may appear in a body.
+ * The DOM is reached through `globalThis`, because this project compiles without a DOM
+ * lib — the cast names the guarantee the page makes: it is a browser, and it has one.
+ */
+
+/**
+ * The pieces of a DOM node the runtime touches, and the ones a page client needs beyond
+ * it. The page supplies the real thing; this is the shape its bundle is typed against.
+ */
+export interface ClientNode {
+	className: string;
+	textContent: string | null;
+	title: string;
+	hidden: boolean;
+	href: string;
+	id: string;
+	style: { width: string };
+	type: string;
+	scrollTop: number;
+	contains(other: ClientNode | null): boolean;
+	focus(): void;
+	classList: { add(name: string): void; remove(name: string): void; toggle(name: string, on?: boolean): void };
+	setAttribute(name: string, value: string): void;
+	getAttribute(name: string): string | null;
+	removeAttribute(name: string): void;
+	appendChild(child: ClientNode): void;
+	remove(): void;
+	replaceChildren(): void;
+	querySelector(selector: string): ClientNode | null;
+	querySelectorAll(selector: string): ArrayLike<ClientNode>;
+	scrollIntoView?(options?: { block?: string }): void;
+	addEventListener(type: string, listener: (event: { target?: unknown }) => void): void;
+}
+
+/** What `document.createElement` has to answer for these helpers. */
+interface RuntimeDocument {
+	createElement(tag: string): ClientNode;
+}
+
+/**
+ * One element with an optional class and text.
+ *
+ * `text` is set as `textContent`, never parsed: a card title and a plan's prose are both
+ * model- or user-written, and the one property that cannot execute is the one to use.
+ */
+export function el(tag: string, className?: string, text?: string | null): ClientNode {
+	// Reached through `globalThis` and cast here, because this project compiles without a
+	// DOM lib; the cast names what the page guarantees — it is a browser, and it has one.
+	const node = (globalThis as unknown as { document: RuntimeDocument }).document.createElement(tag);
+	if (className) node.className = className;
+	if (text !== undefined && text !== null) node.textContent = String(text);
+	return node;
+}
+
+/**
+ * Whether a key event landed in a field, where every key is text rather than a shortcut.
+ *
+ * The tag is lowercased once, so a document parsed as XHTML (`tagName` upper case) and a
+ * page built by `createElement` (`tagName` lower case) both answer the same.
+ */
+export function typing(target: { tagName?: string; isContentEditable?: boolean }): boolean {
+	if (!target || !target.tagName) return target?.isContentEditable === true;
+	const tag = target.tagName.toLowerCase();
+	return tag === "input" || tag === "textarea" || tag === "select" || target.isContentEditable === true;
+}
+
+/**
+ * Paint a status line: its text, the same text as its tooltip, and its tone's class.
+ *
+ * The status slot is the page's own id, so the caller passes the node; what is shared is
+ * the rule that a tone is a `bf-status--*` class and that the text is also the title (a
+ * clamped line has no other way to be read).
+ */
+export function paintStatus(node: ClientNode, text: string, kind?: string): void {
+	node.textContent = text || "";
+	node.title = text || "";
+	node.className = kind ? "bf-status bf-status--" + kind : "bf-status";
+}
+
+/** One answer from the server: whether it accepted, its status, and its parsed body. */
+interface PostResult {
+	ok: boolean;
+	status: number;
+	body: unknown;
+}
+
+/**
+ * POST JSON and read the reply's body, whatever the status.
+ *
+ * A page that only honoured the happy path would report `server returned 409` where the
+ * server had said *why*, so the body is parsed on both branches and the caller decides.
+ */
+export function postJson(url: string, payload: unknown): Promise<PostResult> {
+	return fetch(url, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(payload),
+	}).then((response: { ok: boolean; status: number; json(): Promise<unknown> }) =>
+		response.json().then(
+			(body: unknown): PostResult => ({ ok: response.ok, status: response.status, body }),
+			(): PostResult => ({ ok: response.ok, status: response.status, body: null }),
+		),
+	);
+}
+
+/**
+ * The prefix this page was served under, as the server wrote it on `<html data-base>`.
+ *
+ * A session serves several pages on one origin, so a bundle cannot assume it owns the
+ * root: `""` at the origin's root, `/files` under a mount. The attribute is read every
+ * time rather than cached at load, because a fragment runs in whatever order the bundle
+ * lists it and none of them may depend on another having run first.
+ */
+export function pageBase(): string {
+	// Cast for the same reason as `el`: this project compiles without a DOM lib, and the
+	// page guarantees a document with a root element.
+	const root = (
+		globalThis as unknown as { document: { documentElement: { getAttribute(name: string): string | null } } }
+	).document.documentElement;
+	return root.getAttribute("data-base") ?? "";
+}
+
+/**
+ * {@link pageBase} on its own, for a bundle to splice at its **outermost** scope.
+ *
+ * A page's bundle is a stack of fragments, and a fragment's helper is only visible to the
+ * ones nested inside it — so this one goes where every fragment can reach it, which is not
+ * where the rest of the runtime goes.
+ */
+export const CLIENT_BASE_JS = String(pageBase);
+
+/**
+ * The runtime, as a bundle receives it: the four bodies, in the order a client reads them.
+ *
+ * `test` holds each to its module body and proves the string is safe to splice.
+ */
+export const CLIENT_RUNTIME_JS = [el, typing, paintStatus, postJson].map(String).join("\n\n");

package/lib/web/index.ts

@@ -1,12 +1,14 @@
 /**
  * The Bytefly web brand system: tokens, base rules, components, layout,
- * runtime, and markup atoms. Import from `lib/web/index.ts` rather than a
- * leaf module so the surface reads as one kit.
+ * runtime, markup atoms, and the class-name table a page's bundle carries. Import
+ * from `lib/web/index.ts` rather than a leaf module so the surface reads as one kit.
  */
 
 export * from "./base.ts";
+export * from "./client-runtime.ts";
 export * from "./components.ts";
 export * from "./layout.ts";
 export * from "./markup.ts";
+export * from "./names.ts";
 export * from "./runtime.ts";
 export * from "./tokens.ts";

package/lib/web/markup.ts

@@ -8,6 +8,7 @@
 
 import { escapeHtml } from "../escape.ts";
 import { THEME_JS_PATH } from "./runtime.ts";
+import { WEB_THEME_TOKENS } from "./tokens.ts";
 
 /** Options for {@link docHead}. */
 export interface DocHeadOptions {
@@ -15,6 +16,46 @@ export interface DocHeadOptions {
 	title: string;
 	/** Trusted CSS assembled by the page. */
 	css: string;
+	/**
+	 * The mount prefix this page answers under, e.g. `/files`; `""` for the origin's
+	 * root. A page's scripts and links are emitted under it, because a session serves
+	 * several pages on one origin.
+	 */
+	base?: string;
+}
+
+/**
+ * A page's browser-tab title: `<page> · <subject> · <count>`.
+ *
+ * One convention across the served pages, so a strip of tabs reads as one product. The
+ * page's name comes first, lowercase and the same word its header's `brandLockup`
+ * carries; then what the page is showing; then the count a reader opens the tab for. A
+ * part the page does not have is left out rather than drawn empty, so a board with
+ * nothing open reads `board · my-pi-agent` and a plan reads `plan review · <its title>`.
+ */
+export function tabTitle(product: string, subject?: string, count?: string): string {
+	const kept = [product, subject, count];
+	return kept.filter((part) => part !== undefined && part !== "").join(" · ");
+}
+
+/**
+ * The same body, as the browser receives it.
+ *
+ * The board's count is live, so its tab is repainted on every frame and this rule has to
+ * cross into the bundle. It is written as concatenation with no backtick and no
+ * interpolation, because the bundle is a template the source is spliced into.
+ */
+export const TAB_TITLE_JS = String(tabTitle);
+
+/**
+ * The `data-base` attribute a page's `<html>` carries, which its own bundle reads
+ * (`base()` in `client-runtime.ts`) to build every URL it emits.
+ *
+ * `""` — the origin's root — writes nothing at all, so a page served alone is markup
+ * without a mount to name.
+ */
+export function baseAttribute(base: string): string {
+	return base === "" ? "" : ` data-base="${escapeHtml(base)}"`;
 }
 
 /**
@@ -27,8 +68,70 @@ export function docHead(options: DocHeadOptions): string {
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="color-scheme" content="dark light">
 <title>${escapeHtml(options.title)}</title>
+${markIcon()}
 <style>${options.css}</style>
-<script src="${THEME_JS_PATH}"></script>`;
+<script src="${options.base ?? ""}${THEME_JS_PATH}"></script>`;
+}
+
+/**
+ * The mark's blocks: `█▀█` over `█▀ █`, as `[x, height]` per row in a 4x2 grid.
+ *
+ * One shape, three places — the header lockup, the tab icon, and the TUI header's
+ * half-blocks — so it is written once. The rows differ: the top fills x=2, the bottom
+ * leaves it empty and fills x=3, which is what makes the mark read as two glyphs.
+ */
+const MARK_ROWS: ReadonlyArray<{ group: "top" | "bottom"; rects: ReadonlyArray<readonly [number, number]> }> = [
+	{
+		group: "top",
+		rects: [
+			[0, 1],
+			[1, 0.5],
+			[2, 1],
+		],
+	},
+	{
+		group: "bottom",
+		rects: [
+			[0, 1],
+			[1, 0.5],
+			[3, 1],
+		],
+	},
+];
+
+/** One row of the mark, as `<rect>`s starting at `y`. */
+function markRowRects(row: (typeof MARK_ROWS)[number], y: number): string {
+	return row.rects.map(([x, height]) => `<rect x="${x}" y="${y}" width="1" height="${height}"/>`).join("");
+}
+
+/**
+ * The mark as a standalone SVG, in one appearance's colours.
+ *
+ * A favicon is its own document: it cannot read the page's tokens, so the fills are
+ * resolved here from the same palette the page paints with, and each appearance gets
+ * its own icon.
+ */
+function markSvg(fills: { top: string; bottom: string }): string {
+	const rows = MARK_ROWS.map((row, index) => `<g fill="${fills[row.group]}">${markRowRects(row, index)}</g>`);
+	return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 4 2">${rows.join("")}</svg>`;
+}
+
+/**
+ * The tab icon: the mark, in the appearance the reader's system is in.
+ *
+ * The dark icon is the plain `rel="icon"` — the page paints dark at `:root`, and a
+ * browser that reads no `media` query on an icon keeps it. The light one is the
+ * override, so a light tab does not carry a mark tuned for a dark one.
+ */
+export function markIcon(): string {
+	const dark = encodeURIComponent(
+		markSvg({ top: WEB_THEME_TOKENS.dark["--accent"], bottom: WEB_THEME_TOKENS.dark["--warn"] }),
+	);
+	const light = encodeURIComponent(
+		markSvg({ top: WEB_THEME_TOKENS.light["--accent"], bottom: WEB_THEME_TOKENS.light["--warn"] }),
+	);
+	return `<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,${dark}">
+<link rel="icon" type="image/svg+xml" media="(prefers-color-scheme: light)" href="data:image/svg+xml,${light}">`;
 }
 
 /**
@@ -37,7 +140,8 @@ export function docHead(options: DocHeadOptions): string {
  * as a 4x2 grid so the accent and warning rows stay crisp at any zoom.
  */
 export function brandLockup(product: string): string {
-	return `<span class="bf-brand"><svg class="bf-mark" viewBox="0 0 4 2" aria-hidden="true"><g class="bf-mark__top"><rect x="0" y="0" width="1" height="1"/><rect x="1" y="0" width="1" height="0.5"/><rect x="2" y="0" width="1" height="1"/></g><g class="bf-mark__bottom"><rect x="0" y="1" width="1" height="1"/><rect x="1" y="1" width="1" height="0.5"/><rect x="3" y="1" width="1" height="1"/></g></svg><span class="bf-wordmark">bytefly</span><span class="bf-context">${escapeHtml(product)}</span></span>`;
+	const rows = MARK_ROWS.map((row, index) => `<g class="bf-mark__${row.group}">${markRowRects(row, index)}</g>`);
+	return `<span class="bf-brand"><svg class="bf-mark" viewBox="0 0 4 2" aria-hidden="true">${rows.join("")}</svg><span class="bf-wordmark">bytefly</span><span class="bf-context">${escapeHtml(product)}</span></span>`;
 }
 
 /**

package/lib/web/names.ts

@@ -0,0 +1,42 @@
+/**
+ * A page's class names, as a table a bundle can carry.
+ *
+ * A browser page in this package is a TypeScript document plus a client script held in
+ * a template literal, so the two halves cannot import from each other: a class name is a
+ * string in one and a string in the other, and a name built by concatenation
+ * (`"board-card__reason" + kind`) cannot be found by reading either. A table fixes both:
+ * the document and the bundle read the same values, and a test can compare the set the
+ * page wears with the set its stylesheet draws.
+ *
+ * The bundle carries the table as **source**, so every value must survive being spliced
+ * into a template literal: a backtick would end the string, and `${` would interpolate
+ * at build time. `KEBAB` is that contract, and {@link namesScript} throws rather than
+ * trusting a caller — a bad name is a build error here, not a mystery on the page.
+ */
+
+/** A page's vocabulary: a key per thing it dresses, and the class it wears. */
+export type ClassNames = Readonly<Record<string, string>>;
+
+/** What a class name may be: lowercase, hyphenated, and nothing a script could misread. */
+export const KEBAB = /^[a-z][a-z0-9_-]*$/;
+
+/** What the global the table is bound to may be: a JavaScript identifier, and nothing else. */
+export const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/** The declared global the table is bound to in a page's bundle. */
+export const NAMES_GLOBAL = "N";
+
+/**
+ * The table as one script statement, for a client bundle to start with.
+ *
+ * `JSON.stringify` is the serializer because the values are already strings that pass
+ * {@link KEBAB}; the check before it is what makes that true, and its message names the
+ * offending key and value so the fix is obvious.
+ */
+export function namesScript(table: ClassNames, global: string = NAMES_GLOBAL): string {
+	for (const [key, value] of Object.entries(table)) {
+		if (!KEBAB.test(value)) throw new Error(`the class name for "${key}" is not a kebab-case name: "${value}"`);
+	}
+	if (!IDENTIFIER.test(global)) throw new Error(`"${global}" is not a name a script can declare`);
+	return `var ${global} = ${JSON.stringify(table)};`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.19.0",
-  "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, file-read, check, memory, context, session-bus, board, team, wechat, and bytefly.",
+  "version": "0.21.0",
+  "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, serve, subagent, job, watch, web-access, file-browse, file-open, file-read, check, memory, context, session-bus, board, team, wechat, and bytefly.",
   "keywords": [
     "pi-package",
     "pi",
@@ -92,6 +92,7 @@
   },
   "pi": {
     "extensions": [
+      "./extensions/serve/index.ts",
       "./extensions/worktree/index.ts",
       "./extensions/rewind/index.ts",
       "./extensions/question/index.ts",

package/extensions/board/config.ts

@@ -1,36 +0,0 @@
-/**
- * The board's one setting: the port its page is pinned to.
- *
- * The `board` section of the shared `bytefly.json` (global then project, project
- * wins). `0` — the default — takes one free port for the session and remembers it,
- * which is what a session that never bookmarks its URL wants; a positive value pins
- * the page, so a bookmarked URL survives a restart. A pinned port that is taken
- * fails the start rather than moving the page out from under the bookmark.
- *
- * Pin it in the project document when more than one repository runs a board: a
- * global value is one port for every board on the machine.
- */
-
-import { clampInteger, loadConfigSection } from "../../lib/config.ts";
-
-/** The `board` section. */
-export interface BoardConfig {
-	/** TCP port on `127.0.0.1`; `0` picks one for the session, a positive value pins it. */
-	port: number;
-}
-
-export const DEFAULT_BOARD_CONFIG: BoardConfig = { port: 0 };
-
-/** Validate and clamp a raw config object over the defaults. */
-export function normalizeBoardConfig(
-	raw: Record<string, unknown> | undefined,
-	base: BoardConfig = DEFAULT_BOARD_CONFIG,
-): BoardConfig {
-	if (!raw) return base;
-	return { port: clampInteger(raw.port, base.port, 0, 65_535) };
-}
-
-/** Load the effective config for a working directory. */
-export function loadBoardConfig(cwd: string): BoardConfig {
-	return loadConfigSection(cwd, "board", DEFAULT_BOARD_CONFIG, normalizeBoardConfig);
-}