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

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,123 @@
+/**
+ * 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 runtime, as a bundle receives it: 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 {
@@ -17,6 +18,29 @@ export interface DocHeadOptions {
 	css: 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 shared document head: charset, viewport, colour scheme, title, the page
  * CSS, and the pre-paint theme bootstrap. The body and its scripts stay with
@@ -27,17 +51,80 @@ 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>`;
 }
 
+/**
+ * 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}">`;
+}
+
 /**
  * The Bytefly nameplate: the two-tone half-block mark, the `bytefly` wordmark,
  * and the product name. The mark mirrors the TUI header (`█▀█` / `█▀ █`), drawn
  * 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,6 +1,6 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.19.0",
+  "version": "0.20.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.",
   "keywords": [
     "pi-package",