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

package/extensions/plan/web-comments.ts

@@ -112,7 +112,7 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
   }
 
   function openComposer(wrap, block, quote, initial) {
-    closeComposer();
+    closeOpenComposer();
     wrap.classList.add("bf-block--composing");
     var composer = el("div", "bf-composer");
     if (quote) {
@@ -132,7 +132,7 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
     composer.appendChild(area);
     var row = el("div", "bf-composer__row");
     var cancel = el("button"); cancel.type = "button"; cancel.className = "bf-btn"; cancel.textContent = "Cancel";
-    cancel.addEventListener("click", closeComposer);
+    cancel.addEventListener("click", closeOpenComposer);
     var add = el("button"); add.type = "button"; add.className = "bf-btn bf-btn--primary"; add.textContent = "Add comment";
     var submit = function () {
       if (closed) { setStatus("The review is closed; this comment was not added.", "error"); return; }
@@ -144,10 +144,10 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
       if (role === "reviewer") entry.author = reviewerName;
       annotations.push(entry);
       // Close first: the text is now a comment, so the draft keeps one or the other.
-      closeComposer();
+      closeOpenComposer();
       markDirty();
       setStatus("Comment added.");
-      renderPlan();
+      renderAll();
     };
     add.addEventListener("click", submit);
     submitOnEnter(area, submit);
@@ -168,7 +168,7 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
     card.appendChild(area);
     var row = el("div", "bf-comment__row");
     var cancel = el("button"); cancel.type = "button"; cancel.className = "bf-btn"; cancel.textContent = "Cancel";
-    cancel.addEventListener("click", renderPlan);
+    cancel.addEventListener("click", renderAll);
     var apply = el("button"); apply.type = "button"; apply.className = "bf-btn bf-btn--primary"; apply.textContent = "Save";
     apply.addEventListener("click", function () {
       var comment = area.value.replace(/\s+/g, " ").trim();
@@ -176,7 +176,7 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
       annotation.comment = comment;
       markDirty();
       setStatus("Comment updated.");
-      renderPlan();
+      renderAll();
     });
     submitOnEnter(area, function () { apply.click(); });
     row.appendChild(cancel); row.appendChild(apply); card.appendChild(row);
@@ -205,7 +205,7 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
       annotations.splice(Math.min(index, annotations.length), 0, annotation);
       markDirty();
       clearUndo();
-      renderPlan();
+      renderAll();
       setStatus("Comment restored.", "saved");
     });
     controls.appendChild(button);
@@ -217,7 +217,7 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
     if (!annotation) return;
     annotations.splice(index, 1);
     markDirty();
-    renderPlan();
+    renderAll();
     offerUndo(index, annotation);
     setStatus("Comment deleted.");
   }
@@ -237,6 +237,16 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
       var label = el("span", annotation.author ? "bf-comment__label bf-comment__label--author" : "bf-comment__label");
       label.textContent = annotation.author ? "@" + annotation.author : "Review";
       head.appendChild(label);
+      if (annotation.moved) {
+        // A refinement carried this note off the text it was written on: the placement is
+        // this build's best guess, and saying so is the difference between the reviewer's
+        // anchor and ours.
+        var moved = el("span", "bf-comment__moved");
+        moved.textContent = "moved";
+        moved.title =
+          "Written on an earlier revision. The block it was on changed, so it sits here now: check it still refers to the text below.";
+        head.appendChild(moved);
+      }
       head.appendChild(el("span", "bf-comment__spacer"));
       if (isMine(annotation)) {
         var actions = el("div", "bf-comment__actions");

package/extensions/plan/web-composer.ts

@@ -0,0 +1,80 @@
+/**
+ * The review page's composer lifecycle: closing it, reopening the one a reload interrupted,
+ * and opening it on the block the keyboard is on.
+ *
+ * The sixth capability out of the review client's template literal, and the first that
+ * needs a bundle rather than a list of arguments: closing touches the page, the status
+ * line, the sentence that names a half-written comment, and the draft store — so those
+ * arrive as one `ComposerDeps` the client builds where the state already exists. What
+ * `openComposer` does with the block stays in `web-comments.ts`, which owns the form.
+ */
+
+import type { ClientNode } from "../../lib/web/client-runtime.ts";
+import { blockAtLine, blockElements, type IslandBlock, setActive } from "./web-blocks.ts";
+
+/** What opening a composer takes: the block, its island entry, a quote, and any draft. */
+export type OpenComposer = (wrap: ClientNode, block: IslandBlock, quote: string, initial?: string) => void;
+
+/** What the lifecycle reads of the page. Built where the state lives, once per call. */
+export interface ComposerDeps {
+	planEl: ClientNode | null;
+	statusEl: ClientNode | null;
+	/** The sentence that names a half-written comment, so a stale one can be cleared. */
+	refusal: string;
+	setStatus(text: string, kind?: string): void;
+	saveDraft(): void;
+	open: OpenComposer;
+}
+
+/**
+ * Close the composer, and let the stored draft follow it.
+ *
+ * A close with nothing open must not rewrite — and so drop — a draft a reload restored, so
+ * the draft is saved only when a composer was actually there.
+ */
+export function closeComposer(deps: ComposerDeps): void {
+	const open = deps.planEl ? deps.planEl.querySelector(".bf-composer") : null;
+	if (open) open.remove();
+	const composing = deps.planEl ? deps.planEl.querySelectorAll(".bf-block--composing") : [];
+	for (let i = 0; i < composing.length; i++) composing[i]?.classList.remove("bf-block--composing");
+	// The only status a composer leaves behind is the refusal to leave it; once the draft is
+	// gone that sentence is stale.
+	if (deps.statusEl && deps.statusEl.textContent === deps.refusal) deps.setStatus("");
+	if (open) deps.saveDraft();
+}
+
+/**
+ * Reopen the composer a reload interrupted, once its block has rendered.
+ *
+ * A review that has settled, been approved, or been closed has no draft to restore: the
+ * text belonged to a page that is no longer asking.
+ */
+export function reopenComposer(
+	deps: ComposerDeps,
+	typing: { anchor: number; quote?: string; text?: string } | undefined,
+	settled: { saved: boolean; approved: boolean; closed: boolean },
+	blocks: readonly IslandBlock[],
+): void {
+	if (!typing || settled.saved || settled.approved || settled.closed) return;
+	const target = blockAtLine(deps.planEl, blocks, typing.anchor);
+	if (target) deps.open(target.wrap, target.block, typing.quote || "", typing.text);
+}
+
+/**
+ * Open the composer on the block the keyboard is on, starting one if none is active.
+ *
+ * The index is returned so the client keeps its one `activeIndex`: opening a composer is a
+ * navigation, and the block the reader lands on is the block they are commenting on.
+ */
+export function commentOnActive(deps: ComposerDeps, activeIndex: number, blocks: readonly IslandBlock[]): number {
+	if (blockElements(deps.planEl).length === 0) return activeIndex;
+	const index = activeIndex < 0 ? (setActive(deps.planEl, 0) ?? activeIndex) : activeIndex;
+	const wrap = blockElements(deps.planEl)[Math.max(0, index)];
+	if (!wrap) return index;
+	const target = blockAtLine(deps.planEl, blocks, Number(wrap.getAttribute("data-line")));
+	if (target) deps.open(target.wrap, target.block, "");
+	return index;
+}
+
+/** The composer lifecycle as source, for the client bundle. */
+export const WEB_COMPOSER_JS = [closeComposer, reopenComposer, commentOnActive].map(String).join("\n\n");

package/extensions/plan/web-draft.ts

@@ -0,0 +1,40 @@
+/**
+ * The review page's draft guard: a composer holding text the page has not committed.
+ *
+ * The fifth capability out of the review client's template literal. `draftTextarea` is
+ * pure — hand it the plan element and it answers the open composer's textarea, or nothing.
+ * `guardDraft` is the rule built on it: the ways off the page refuse while a draft exists,
+ * say why in the status line, and leave the cursor where the text is, so the reader is not
+ * told about a draft they then have to hunt for.
+ */
+
+import type { ClientNode } from "../../lib/web/client-runtime.ts";
+
+/** The open composer's textarea, when it holds anything a reader would lose. */
+export function draftTextarea(planEl: ClientNode | null): { value: string; focus(): void } | null {
+	const open = planEl ? planEl.querySelector(".bf-composer") : null;
+	const area = open ? (open.querySelector("textarea") as { value: string; focus(): void } | null) : null;
+	return area && area.value.trim() ? area : null;
+}
+
+/**
+ * Whether an action must stop because a comment is half-written, and say so if it must.
+ *
+ * The refusal is the status line's own sentence rather than an alert: every way off the
+ * page runs this, and a modal on each of them would be four dialogs for one fact.
+ */
+export function guardDraft(
+	planEl: ClientNode | null,
+	statusEl: ClientNode | null,
+	refusal: string,
+	paint: (node: ClientNode, text: string, kind?: string) => void,
+): boolean {
+	const area = draftTextarea(planEl);
+	if (!area) return false;
+	if (statusEl) paint(statusEl, refusal, "error");
+	area.focus();
+	return true;
+}
+
+/** The draft rules as source, for the client bundle. */
+export const WEB_DRAFT_JS = [draftTextarea, guardDraft].map(String).join("\n\n");

package/extensions/plan/web-keys.ts

@@ -0,0 +1,134 @@
+/**
+ * The review page's keyboard, and the one piece of pointer state a key acts on.
+ *
+ * The ninth capability out of the review client's template literal — and the last one, by
+ * decision: what is left in the bundle after this is wiring (which listener to attach, the
+ * frame stream, the boot order), and a rule about which key does what does not belong in a
+ * list of `addEventListener` calls.
+ *
+ * Two rules live here:
+ *
+ * - **Esc peels one layer.** The shortcut sheet owns its own Esc (the shared dialog runtime
+ *   captures it), so this peels the composer first and closes the review second, which is
+ *   the order a reader pressing it twice expects.
+ * - **The selection a reader makes is the quote the next comment carries.** The rail button
+ *   collapses the selection when it is pressed, so the text is remembered on `mouseup` and
+ *   read again at click time; a block with a composer open is not a selection to quote.
+ */
+
+import type { ClientNode } from "../../lib/web/client-runtime.ts";
+
+/** What a key may do: one callback per action the page owns. */
+export interface KeyDeps {
+	/** Whether a composer is open, and how to close it. */
+	composerOpen(): boolean;
+	closeComposer(): void;
+	/** Close the review without saving: the owner's, and a no-op for a reviewer. */
+	cancel(): void;
+	/** The shortcut sheet: whether it is open (it then owns the keyboard) and its toggle. */
+	sheetOpen(): boolean;
+	toggleSheet(): void;
+	/** Walk the blocks by one, in the direction the key names. */
+	moveActive(delta: number): void;
+	/** Comment on the block the keyboard is on. */
+	commentOnActive(): void;
+	/** Approve, through its confirmation; and the two writes `s` can stand for. */
+	askApprove(): void;
+	save(): void;
+	postComments(): void;
+	/** Whether a control exists for the key to stand for. */
+	hasSaveControl(): boolean;
+	hasApproveControl(): boolean;
+	/** Whether the key landed in a field, where every key is text. */
+	typing(target: unknown): boolean;
+}
+
+/** The keys a reader can press, as far as this page is concerned. */
+export interface KeyEvent {
+	key: string;
+	metaKey?: boolean;
+	ctrlKey?: boolean;
+	altKey?: boolean;
+	target?: unknown;
+	preventDefault(): void;
+}
+
+/**
+ * Handle one keydown.
+ *
+ * A modified key is never a shortcut: `ctrl+s` belongs to the browser. A field owns the
+ * keyboard while it has focus, and so does the shortcut sheet while it is open.
+ */
+export function handleKey(event: KeyEvent, deps: KeyDeps): void {
+	if (event.key === "Escape") {
+		// The sheet owns its own Esc; this peels the composer, then the review.
+		if (deps.composerOpen()) {
+			deps.closeComposer();
+			return;
+		}
+		deps.cancel();
+		return;
+	}
+	if (deps.typing(event.target)) return;
+	if (event.metaKey || event.ctrlKey || event.altKey) return;
+	if (event.key === "?") {
+		event.preventDefault();
+		deps.toggleSheet();
+		return;
+	}
+	// While the shortcut sheet is open it owns the keyboard.
+	if (deps.sheetOpen()) return;
+	if (event.key === "j") {
+		event.preventDefault();
+		deps.moveActive(1);
+		return;
+	}
+	if (event.key === "k") {
+		event.preventDefault();
+		deps.moveActive(-1);
+		return;
+	}
+	if (event.key === "c") {
+		event.preventDefault();
+		deps.commentOnActive();
+		return;
+	}
+	if (event.key === "a" && deps.hasApproveControl()) {
+		event.preventDefault();
+		deps.askApprove();
+		return;
+	}
+	if (event.key === "s") {
+		event.preventDefault();
+		if (deps.hasSaveControl()) deps.save();
+		else deps.postComments();
+	}
+}
+
+/** What remembering a selection reads, and where it puts it. */
+export interface QuoteDeps {
+	planEl: ClientNode | null;
+	/** A settled review takes no more comments, so it remembers no selection. */
+	settled(): boolean;
+	/** The text a reader selected inside one block. */
+	selectionIn(wrap: ClientNode): string;
+	/** Remember it, or forget the last one when the release selected nothing. */
+	setPending(quote: { wrap: ClientNode; quote: string } | null): void;
+}
+
+/**
+ * Remember the text a reader selected, so the rail button can still quote it.
+ *
+ * A release outside a block, or inside a block whose composer is open, clears what was
+ * remembered: the next click must not quote text from somewhere the reader has left.
+ */
+export function rememberSelection(target: unknown, deps: QuoteDeps): void {
+	if (!deps.planEl || deps.settled()) return;
+	const node = target as { closest?: (selector: string) => ClientNode | null } | null;
+	const wrap = node && typeof node.closest === "function" ? node.closest(".bf-block") : null;
+	const quote = wrap && !wrap.querySelector(".bf-composer") ? deps.selectionIn(wrap) : "";
+	deps.setPending(wrap && quote ? { wrap, quote } : null);
+}
+
+/** The keymap and the quote rule as source, for the client bundle. */
+export const WEB_KEYS_JS = [handleKey, rememberSelection].map(String).join("\n\n");

package/extensions/plan/web-outline.ts

@@ -0,0 +1,192 @@
+/**
+ * The review page's outline: the section list in the sidebar, and the one rule that says
+ * which section a source line belongs to.
+ *
+ * Written as ordinary TypeScript and exported as source — `WEB_OUTLINE_JS` — because the
+ * review client is a template literal no compiler sees. The two functions are given what
+ * they read rather than closing over the bundle's variables, which is what makes them
+ * testable here: `renderOutline` returns the per-line counters it built instead of
+ * assigning the client's `outlineItems`, and `sectionFor` takes the outline it searches.
+ *
+ * `el` is the client runtime's builder, declared here because this source is spliced into
+ * the same bundle it lives in: the declaration emits nothing, so the body calls the one
+ * builder. The nodes are reached through a structural type because this project compiles
+ * without a DOM lib; the annotations are erased before the source is spliced.
+ */
+
+import type { ClientNode } from "../../lib/web/client-runtime.ts";
+
+/** One entry of the page's `outline` island: a heading, its line, and whether it moved. */
+export interface OutlineEntry {
+	id: string;
+	level: number;
+	line: number;
+	text: string;
+	changed?: boolean;
+}
+
+/** What the browser's `IntersectionObserver` answers for a section watcher. */
+export interface SectionWatcher {
+	observe(target: ClientNode): void;
+	disconnect(): void;
+}
+
+/** What `el` has to answer for an outline. Spliced beside it; declared for the checker. */
+type Build = (tag: string, className?: string, text?: string | null) => ClientNode;
+declare const el: Build;
+
+/**
+ * The section a source line belongs to: the last heading at or before it.
+ *
+ * `null` when the line sits above the first heading, which is how a preamble renders
+ * without a section of its own.
+ */
+export function sectionFor(entries: readonly OutlineEntry[], line: number): OutlineEntry | null {
+	let found: OutlineEntry | null = null;
+	for (const item of entries) if (item.line <= line) found = item;
+	return found;
+}
+
+/**
+ * Draw the section list and return the counter each line owns.
+ *
+ * The caller keeps the returned map because the counters are updated later, when the
+ * comments are counted per section; returning it is what lets this function be a pure
+ * build with no handle on the client's state.
+ */
+export function renderOutline(list: ClientNode | null, entries: readonly OutlineEntry[]): Record<number, ClientNode> {
+	const counters: Record<number, ClientNode> = {};
+	if (!list) return counters;
+	list.replaceChildren();
+	for (const item of entries) {
+		const li = el("li", "lvl-" + item.level);
+		const link = el("a");
+		link.href = "#" + item.id;
+		link.setAttribute("data-id", item.id);
+		const label = el("span", "review-nav__link");
+		label.textContent = item.text;
+		link.appendChild(label);
+		if (item.changed) {
+			const dot = el("span", "review-changed");
+			dot.setAttribute("role", "img");
+			dot.setAttribute("aria-label", "Changed since your last review");
+			dot.title = "Changed since your last review";
+			link.appendChild(dot);
+		}
+		const count = el("span", "review-nav__count");
+		count.hidden = true;
+		link.appendChild(count);
+		li.appendChild(link);
+		list.appendChild(li);
+		counters[item.line] = count;
+	}
+	return counters;
+}
+
+/**
+ * Watch the blocks and mark the section the reader is in, replacing any previous watcher.
+ *
+ * The observer is returned rather than stored, so the client owns the one handle it has to
+ * disconnect and this function owns the rule: the last block still in the document the
+ * observer was built over wins, and a page with no headings needs no watcher at all.
+ */
+export function observeSections(
+	planEl: ClientNode | null,
+	list: ClientNode | null,
+	previous: SectionWatcher | null,
+): SectionWatcher | null {
+	if (previous) previous.disconnect();
+	if (!planEl || !list) return null;
+	const Observer = (
+		globalThis as unknown as {
+			IntersectionObserver?: new (
+				callback: (entries: ArrayLike<{ isIntersecting: boolean; target: { id: string } }>) => void,
+				options: Record<string, unknown>,
+			) => SectionWatcher;
+		}
+	).IntersectionObserver;
+	if (!Observer) return null;
+	const links: Record<string, ClientNode> = {};
+	const anchors = list.querySelectorAll("a");
+	for (let i = 0; i < anchors.length; i++) {
+		const link = anchors[i];
+		if (link) links[link.getAttribute("data-id") ?? ""] = link;
+	}
+	const headings = planEl.querySelectorAll(".bf-block[id]");
+	if (headings.length === 0) return null;
+	const watcher = new Observer(
+		(entries) => {
+			for (let i = 0; i < entries.length; i++) {
+				const entry = entries[i];
+				if (!entry || !entry.isIntersecting) continue;
+				const all = list.querySelectorAll("a");
+				for (let j = 0; j < all.length; j++) all[j]?.removeAttribute("aria-current");
+				const link = links[entry.target.id];
+				if (link) link.setAttribute("aria-current", "true");
+			}
+		},
+		{ rootMargin: "-88px 0px -68% 0px", threshold: 0 },
+	);
+	for (let i = 0; i < headings.length; i++) {
+		const heading = headings[i];
+		if (heading) watcher.observe(heading);
+	}
+	return watcher;
+}
+
+/** One review comment, as the facts need it: the line it is anchored to. */
+export interface AnchoredComment {
+	anchor: number;
+}
+
+/** What a plan's step list says: the numbers the server counted. */
+export interface StepProgress {
+	done: number;
+	total: number;
+}
+
+/**
+ * Paint the review facts: the plan's step progress, the comment total, and one count per
+ * section in the outline.
+ *
+ * The counters are the ones `renderOutline` returned, so the two functions agree by
+ * construction; a section a comment cannot be placed in is skipped rather than counted
+ * against the first heading, which is what "not attached to a current block" means.
+ */
+export function renderFacts(
+	steps: StepProgress,
+	comments: readonly AnchoredComment[],
+	counters: Record<number, ClientNode>,
+	entries: readonly OutlineEntry[],
+): void {
+	const doc = (
+		globalThis as unknown as {
+			document: { getElementById(id: string): ClientNode | null };
+		}
+	).document;
+	// A plan with no Steps section has no progress to show; 0/0 is noise.
+	const fact = doc.getElementById("step-fact");
+	if (fact) fact.hidden = steps.total === 0;
+	const fill = doc.getElementById("step-fill");
+	if (fill) fill.style.width = (steps.total > 0 ? Math.round((steps.done / steps.total) * 100) : 0) + "%";
+	const count = doc.getElementById("step-count");
+	if (count) count.textContent = steps.done + "/" + steps.total;
+	const total = doc.getElementById("comment-total");
+	if (total) total.textContent = String(comments.length);
+	for (const line of Object.keys(counters)) {
+		const node = counters[Number(line)];
+		if (node) node.hidden = true;
+	}
+	for (const comment of comments) {
+		const section = sectionFor(entries, comment.anchor);
+		if (!section) continue;
+		const node = counters[section.line];
+		if (!node) continue;
+		const value = node.hidden ? 0 : Number(node.textContent);
+		node.textContent = String(value + 1);
+		node.hidden = false;
+	}
+}
+
+/** The section list, the facts beside it, and the watcher that marks where the reader is. */
+export const WEB_OUTLINE_JS = [sectionFor, renderOutline, observeSections, renderFacts].map(String).join("\n\n");

package/extensions/plan/web-page.ts

@@ -19,6 +19,7 @@ import {
 	type KeyHint,
 	keysSheet,
 	SIDEBAR_COLLAPSE_MAX,
+	tabTitle,
 	themeToggle,
 	WEB_BASE_CSS,
 	WEB_COMPONENTS_CSS,
@@ -179,6 +180,8 @@ ${WEB_COMPONENTS_CSS}
 .bf-comment__label{font:var(--fw-semibold) var(--fs-xs) var(--font-mono);color:var(--warn);text-transform:uppercase;letter-spacing:.06em}
 /* A reviewer's name is a name, not a label: keep its own capitalisation. */
 .bf-comment__label--author{text-transform:none;letter-spacing:0}
+/* A note a refinement carried off its own block: muted, because the complaint is the guess, not the text. */
+.bf-comment__moved{font:var(--fw-medium) var(--fs-xs) var(--font-mono);color:var(--muted);text-transform:uppercase;letter-spacing:.06em;border:1px solid var(--border);border-radius:var(--radius-sm);padding:0 6px}
 .bf-comment__spacer{flex:1 1 auto}
 .bf-comment__actions{display:flex;gap:4px}
 .bf-comment__actions .bf-btn{padding:1px 8px;font-size:var(--fs-xs)}
@@ -341,7 +344,7 @@ ${reviewHints(data.role, data.canApprove)}
 	return `<!doctype html>
 <html lang="en">
 <head>
-${docHead({ title: "Plan review", css: REVIEW_CSS })}
+${docHead({ title: tabTitle("plan review", data.title), css: REVIEW_CSS })}
 </head>
 <body class="bf-app">
 <a class="skip" href="#plan">Skip to the plan</a>