pi-midcompact 0.4.0 → 0.5.0

package/src/review-webui.ts

@@ -5,17 +5,24 @@ import { readFileSync } from "node:fs";
 
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
-import type { Atom, DraftPlan, DraftTelemetry } from "./types.js";
+import type { Atom, DraftPlan, DraftTelemetry, SelectionSpan } from "./types.js";
 
 const HTML_TEMPLATE = readFileSync(new URL("review-webui.html", import.meta.url), "utf8");
 
+export type ReviewWebUiView = "review" | "selection";
+
 export interface ReviewState {
+  view: ReviewWebUiView;
   atoms: Array<{
     ref: string;
     index: number;
+    groupRef: string;
+    groupLabel: string;
     kind: string;
     preview: string;
-    approxTokens: number;
+    contentChars: number;
+    imageCount: number;
+    imagePayloadBytes: number;
     compressible: boolean;
     protocolClosed: boolean;
     toolNames: string[];
@@ -33,8 +40,10 @@ export interface ReviewState {
       endRef: string;
       topic?: string;
       summary: string;
-      originalApproxTokens: number;
-      compressedApproxTokens: number;
+      originalContentChars: number;
+      originalImageCount: number;
+      originalImagePayloadBytes: number;
+      replacementContentChars: number;
       atomCount: number;
     }>;
   };
@@ -42,27 +51,68 @@ export interface ReviewState {
 }
 
 export interface ReviewWebUiCallbacks {
+  applySelection?(spans: SelectionSpan[], keepRefs: string[]): void;
   editSummary(draftId: string, summary: string): void;
   editTopic(draftId: string, topic: string): void;
   remove(draftId: string): void;
 }
 
-
+export interface ReviewWebUiRuntimeOptions {
+  /** Test seam; production opens the system browser. */
+  openBrowser?: (url: string) => void;
+  /** Release the UI when no page establishes its liveness stream. */
+  livenessConnectTimeoutMs?: number;
+  /** Server-originated keepalive interval for detecting a disappeared page. */
+  livenessPingIntervalMs?: number;
+}
 
 function owningRange(atomIndex: number, ranges: DraftPlan["ranges"]) {
-  return ranges.find((r) => atomIndex >= r.startIndex && atomIndex <= r.endIndex);
+  return ranges.find((range) => atomIndex >= range.startIndex && atomIndex <= range.endIndex);
+}
+
+function groupMeta(atoms: readonly Atom[]): Map<number, { ref: string; label: string }> {
+  let groupNumber = 0;
+  let seenUser = false;
+  const result = new Map<number, { ref: string; label: string }>();
+  atoms.forEach((atom, index) => {
+    if (atom.kind === "user") {
+      groupNumber += 1;
+      seenUser = true;
+    }
+    const ref = seenUser ? `g${String(groupNumber).padStart(4, "0")}` : "g0000";
+    const label = seenUser && atom.kind === "user" ? firstLine(atom.preview, 72) : seenUser ? `group ${ref}` : "context before first user message";
+    result.set(index, { ref, label });
+  });
+  return result;
+}
+
+function firstLine(text: string, limit: number): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length <= limit ? normalized : `${normalized.slice(0, limit - 1)}...`;
 }
 
-export function serializeReviewState(atoms: Atom[], draft: DraftPlan, telemetry: DraftTelemetry): ReviewState {
+export function serializeReviewState(
+  atoms: Atom[],
+  draft: DraftPlan,
+  telemetry: DraftTelemetry,
+  view: ReviewWebUiView = "review",
+): ReviewState {
+  const groups = groupMeta(atoms);
   return {
+    view,
     atoms: atoms.map((atom) => {
       const owner = owningRange(atom.index, draft.ranges);
+      const group = groups.get(atom.index)!;
       return {
         ref: atom.ref,
         index: atom.index,
+        groupRef: group.ref,
+        groupLabel: group.label,
         kind: atom.kind,
         preview: atom.preview,
-        approxTokens: atom.approxTokens,
+        contentChars: atom.metrics.contentChars,
+        imageCount: atom.metrics.imageCount,
+        imagePayloadBytes: atom.metrics.images.reduce((sum, image) => sum + image.payloadBytes, 0),
         compressible: atom.compressible,
         protocolClosed: atom.protocolClosed,
         toolNames: atom.toolNames,
@@ -81,8 +131,10 @@ export function serializeReviewState(atoms: Atom[], draft: DraftPlan, telemetry:
         endRef: range.endRef,
         topic: range.topic,
         summary: range.summary,
-        originalApproxTokens: range.originalApproxTokens,
-        compressedApproxTokens: range.compressedApproxTokens,
+        originalContentChars: range.originalContentChars,
+        originalImageCount: range.originalImageCount,
+        originalImagePayloadBytes: range.originalImagePayloadBytes,
+        replacementContentChars: range.replacementContentChars,
         atomCount: range.endIndex - range.startIndex + 1,
       })),
     },
@@ -90,123 +142,176 @@ export function serializeReviewState(atoms: Atom[], draft: DraftPlan, telemetry:
   };
 }
 
-/**
- * Start a local HTTP server hosting the midcompact review page. Resolves when
- * the user closes the review (POST /api/close) or the server errors out.
- *
- * Edits are applied via callbacks that the caller wires to the same draft
- * mutation + append-entry path used by the TUI, so both surfaces stay consistent.
- */
+/** Serve the shared Review/Selection workbench over loopback HTTP. */
 export async function showReviewWebUi(
   ctx: ExtensionCommandContext,
   atoms: Atom[],
   getLatest: () => { draft: DraftPlan; telemetry: DraftTelemetry },
   callbacks: ReviewWebUiCallbacks,
+  view: ReviewWebUiView = "review",
+  runtime: ReviewWebUiRuntimeOptions = {},
 ): Promise<void> {
   return new Promise<void>((resolve, reject) => {
-    const server = http.createServer((req, res) => {
+    const connectTimeoutMs = runtime.livenessConnectTimeoutMs ?? 30_000;
+    const pingIntervalMs = runtime.livenessPingIntervalMs ?? 10_000;
+    let settled = false;
+    let closing = false;
+    let livenessResponse: http.ServerResponse | undefined;
+    let connectTimer: NodeJS.Timeout | undefined;
+    let pingTimer: NodeJS.Timeout | undefined;
+
+    const clearTimers = () => {
+      if (connectTimer) clearTimeout(connectTimer);
+      if (pingTimer) clearInterval(pingTimer);
+      connectTimer = undefined;
+      pingTimer = undefined;
+    };
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      resolve();
+    };
+    const fail = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      reject(error);
+    };
+    const server = http.createServer(async (req, res) => {
       const url = new URL(req.url ?? "/", "http://127.0.0.1");
       const path = url.pathname;
-
       const sendJson = (code: number, body: unknown) => {
         const payload = JSON.stringify(body);
-        res.writeHead(code, {
-          "content-type": "application/json; charset=utf-8",
-          "content-length": Buffer.byteLength(payload),
-        });
+        res.writeHead(code, { "content-type": "application/json; charset=utf-8", "content-length": Buffer.byteLength(payload) });
         res.end(payload);
       };
       const sendHtml = (html: string) => {
-        res.writeHead(200, {
-          "content-type": "text/html; charset=utf-8",
-          "content-length": Buffer.byteLength(html),
-        });
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8", "content-length": Buffer.byteLength(html) });
         res.end(html);
       };
-
       const readBody = async (): Promise<string> => {
         const chunks: Buffer[] = [];
         for await (const chunk of req) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
         return Buffer.concat(chunks).toString("utf8");
       };
+      const currentState = () => {
+        const latest = getLatest();
+        return serializeReviewState(atoms, latest.draft, latest.telemetry, view);
+      };
 
       try {
+        if (req.method === "GET" && path === "/api/liveness") {
+          if (livenessResponse && !livenessResponse.writableEnded) livenessResponse.end();
+          livenessResponse = res;
+          if (connectTimer) clearTimeout(connectTimer);
+          connectTimer = undefined;
+          res.writeHead(200, {
+            "content-type": "text/event-stream; charset=utf-8",
+            "cache-control": "no-cache",
+            connection: "keep-alive",
+          });
+          res.write(": connected\n\n");
+          if (pingTimer) clearInterval(pingTimer);
+          pingTimer = setInterval(() => {
+            if (!res.writableEnded) res.write(": keepalive\n\n");
+          }, pingIntervalMs);
+          req.on("close", () => {
+            if (livenessResponse === res) {
+              livenessResponse = undefined;
+              closeServer();
+            }
+          });
+          return;
+        }
         if (req.method === "GET" && path === "/") {
-          const { draft, telemetry } = getLatest();
-          const stateJson = JSON.stringify(serializeReviewState(atoms, draft, telemetry)).replace(/</g, "\\u003c");
-          // NOTE: function replacer — a string replacement would interpret `$&` / `$'` in the payload.
+          const stateJson = JSON.stringify(currentState()).replace(/</g, "\\u003c");
           sendHtml(HTML_TEMPLATE.replace("<!--MIDCOMPACT_STATE-->", () => stateJson));
           return;
         }
         if (req.method === "GET" && path === "/api/state") {
-          const { draft, telemetry } = getLatest();
-          sendJson(200, serializeReviewState(atoms, draft, telemetry));
+          sendJson(200, currentState());
           return;
         }
         if (req.method === "POST" && path === "/api/close") {
           sendJson(200, { ok: true });
-          server.close();
-          resolve();
+          closeServer();
+          return;
+        }
+        if (req.method === "POST" && path === "/api/selection") {
+          if (view !== "selection" || !callbacks.applySelection) {
+            sendJson(409, { error: "Selection is not available in this view." });
+            return;
+          }
+          const parsed = JSON.parse(await readBody()) as { spans?: SelectionSpan[]; keepRefs?: string[] };
+          if (!Array.isArray(parsed.spans) || !Array.isArray(parsed.keepRefs)) {
+            sendJson(400, { error: "Selection requires spans and keepRefs arrays." });
+            return;
+          }
+          callbacks.applySelection(parsed.spans, parsed.keepRefs);
+          sendJson(200, currentState());
           return;
         }
         const editMatch = path.match(/^\/api\/range\/([^/]+)\/(edit-summary|edit-topic|remove)$/);
         if (req.method === "POST" && editMatch) {
-          const [, draftId, op] = editMatch;
+          const [, draftId, operation] = editMatch;
+          if (view === "selection" && operation !== "remove") {
+            sendJson(409, { error: "Summary and topic editing belong to Review." });
+            return;
+          }
           const current = getLatest().draft;
-          const range = current.ranges.find((r) => r.id === draftId);
-          if (!range) {
+          if (!current.ranges.some((range) => range.id === draftId)) {
             sendJson(404, { error: `Unknown range ${draftId}` });
             return;
           }
-          if (op === "remove") {
+          if (operation === "remove") {
             callbacks.remove(draftId);
-            const { draft, telemetry } = getLatest();
-            sendJson(200, serializeReviewState(atoms, draft, telemetry));
+            sendJson(200, currentState());
             return;
           }
-          readBody().then((raw) => {
-            try {
-              const parsed = JSON.parse(raw) as { value?: string };
-              const value = typeof parsed.value === "string" ? parsed.value : "";
-              if (op === "edit-summary") {
-                if (!value.trim()) {
-                  sendJson(400, { error: "summary must not be empty" });
-                  return;
-                }
-                callbacks.editSummary(draftId, value.trim());
-              } else {
-                callbacks.editTopic(draftId, value.trim());
-              }
-              const { draft, telemetry } = getLatest();
-              sendJson(200, serializeReviewState(atoms, draft, telemetry));
-            } catch (err) {
-              sendJson(400, { error: err instanceof Error ? err.message : String(err) });
+          const parsed = JSON.parse(await readBody()) as { value?: string };
+          const value = typeof parsed.value === "string" ? parsed.value.trim() : "";
+          if (operation === "edit-summary") {
+            if (!value) {
+              sendJson(400, { error: "summary must not be empty" });
+              return;
             }
-          });
+            callbacks.editSummary(draftId, value);
+          } else callbacks.editTopic(draftId, value);
+          sendJson(200, currentState());
           return;
         }
         sendJson(404, { error: "not found" });
-      } catch (err) {
-        sendJson(500, { error: err instanceof Error ? err.message : String(err) });
+      } catch (error) {
+        sendJson(400, { error: error instanceof Error ? error.message : String(error) });
       }
     });
 
-    server.on("error", reject);
-    // Bind loopback only; random port assigned by the OS.
+    const closeServer = () => {
+      if (closing || settled) return;
+      closing = true;
+      clearTimers();
+      if (livenessResponse && !livenessResponse.writableEnded) livenessResponse.end();
+      livenessResponse = undefined;
+      server.close(finish);
+    };
+
+    server.on("error", fail);
     server.listen(0, "127.0.0.1", () => {
-      const addr = server.address();
-      const port = typeof addr === "object" && addr ? addr.port : 0;
-      const url = `http://127.0.0.1:${port}`;
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : 0;
+      const url = `http://127.0.0.1:${port}/?view=${view}`;
       const token = randomBytes(3).toString("hex");
-      ctx.ui.notify(`Midcompact review-webui ready: ${url} (token ${token})`, "info");
-      tryOpenBrowser(url);
+      ctx.ui.notify(`Midcompact ${view} webui ready: ${url} (token ${token})`, "info");
+      connectTimer = setTimeout(closeServer, connectTimeoutMs);
+      (runtime.openBrowser ?? tryOpenBrowser)(url);
     });
   });
 }
 
 function tryOpenBrowser(url: string): void {
-  const cmd = process.platform === "win32" ? `start "" "${url}"`
+  const command = process.platform === "win32" ? `start "" "${url}"`
     : process.platform === "darwin" ? `open "${url}"`
-    : `xdg-open "${url}"`;
-  exec(cmd, () => { /* best-effort; ignore failures */ });
+      : `xdg-open "${url}"`;
+  exec(command, () => { /* best-effort */ });
 }

package/src/selection-ui.ts

@@ -0,0 +1,220 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+import type { Atom, DraftPlan, DraftTelemetry, SelectionSpan } from "./types.js";
+
+export interface SelectionUiAction {
+  action: "save" | "close";
+  spans?: SelectionSpan[];
+  keepRefs?: string[];
+}
+
+/**
+ * Atom-level Selection surface. It edits a requested selection only; the
+ * caller normalizes it into ordinary DraftRanges through the shared core.
+ */
+export async function showSelectionUi(
+  ctx: ExtensionCommandContext,
+  atoms: Atom[],
+  draft: DraftPlan,
+  telemetry: DraftTelemetry,
+): Promise<SelectionUiAction> {
+  if (ctx.mode !== "tui") return { action: "close" };
+
+  return ctx.ui.custom(
+    (tui: { terminal: { rows: number }; requestRender: () => void }, theme: any, _keybindings: unknown, done: (action: SelectionUiAction) => void) => {
+      const selected = new Set<number>();
+      const keep = new Set<string>();
+      let cursor = 0;
+      let scrollOffset = 0;
+      let dirty = false;
+
+      for (const range of draft.ranges) {
+        for (let index = range.startIndex; index <= range.endIndex; index += 1) selected.add(index);
+      }
+
+      const dim = (text: string) => theme.fg("dim", text);
+      const accent = (text: string) => theme.fg("accent", text);
+      const success = (text: string) => theme.fg("success", text);
+      const warning = (text: string) => theme.fg("warning", text);
+      const border = (text: string) => theme.fg("border", text);
+      const widthOf = (width: number) => Math.max(40, width);
+      const frame = (text: string, width: number) => `${border("|")} ${truncateToWidth(text, Math.max(20, width - 4), "...", true)} ${border("|")}`;
+      const rule = (width: number, left: string, right: string) => border(`${left}${"-".repeat(Math.max(0, width - 2))}${right}`);
+      const short = (text: string, limit: number) => {
+        const normalized = text.replace(/\s+/g, " ").trim();
+        return normalized.length <= limit ? normalized : `${normalized.slice(0, limit - 1)}...`;
+      };
+      const groupBounds = (index: number): { start: number; end: number } => {
+        let start = index;
+        while (start > 0 && atoms[start]?.kind !== "user") start -= 1;
+        if (atoms[start]?.kind !== "user" && start === 0) start = 0;
+        let end = index;
+        while (end + 1 < atoms.length && atoms[end + 1]?.kind !== "user") end += 1;
+        return { start, end };
+      };
+      const spans = (): SelectionSpan[] => {
+        const indices = [...selected].sort((a, b) => a - b);
+        const result: SelectionSpan[] = [];
+        for (const index of indices) {
+          const previous = result[result.length - 1];
+          const previousIndex = previous ? atoms.findIndex((atom) => atom.ref === previous.endRef) : -2;
+          if (previous && previousIndex + 1 === index) previous.endRef = atoms[index]!.ref;
+          else result.push({ startRef: atoms[index]!.ref, endRef: atoms[index]!.ref });
+        }
+        return result;
+      };
+      const toggleSelection = () => {
+        const atom = atoms[cursor];
+        if (!atom) return;
+        if (!atom.compressible && !selected.has(cursor)) {
+          ctx.ui.notify(`Protected atom ${atom.ref} stays KEEP. Select its surrounding group instead.`, "warning");
+          return;
+        }
+        if (selected.has(cursor)) {
+          selected.delete(cursor);
+          keep.delete(atom.ref);
+        } else selected.add(cursor);
+        dirty = true;
+        tui.requestRender();
+      };
+      const toggleKeep = () => {
+        const atom = atoms[cursor];
+        if (!atom) return;
+        if (!atom.compressible) {
+          ctx.ui.notify(`Protected atom ${atom.ref} already stays KEEP.`, "info");
+          return;
+        }
+        if (!selected.has(cursor)) {
+          selected.add(cursor);
+          keep.add(atom.ref);
+          dirty = true;
+          tui.requestRender();
+          return;
+        }
+        if (keep.has(atom.ref)) keep.delete(atom.ref);
+        else keep.add(atom.ref);
+        dirty = true;
+        tui.requestRender();
+      };
+      const addGroup = () => {
+        const bounds = groupBounds(cursor);
+        for (let index = bounds.start; index <= bounds.end; index += 1) selected.add(index);
+        dirty = true;
+        tui.requestRender();
+      };
+      const clearRange = () => {
+        const current = atoms[cursor];
+        if (!current?.compressible || keep.has(current.ref) || !selected.has(cursor)) return;
+        let start = cursor;
+        let end = cursor;
+        while (start > 0 && atoms[start - 1]!.compressible && selected.has(start - 1) && !keep.has(atoms[start - 1]!.ref)) start -= 1;
+        while (end + 1 < atoms.length && atoms[end + 1]!.compressible && selected.has(end + 1) && !keep.has(atoms[end + 1]!.ref)) end += 1;
+        for (let index = start; index <= end; index += 1) {
+          selected.delete(index);
+          keep.delete(atoms[index]!.ref);
+        }
+        dirty = true;
+        tui.requestRender();
+      };
+      const move = (delta: number) => {
+        cursor = Math.max(0, Math.min(atoms.length - 1, cursor + delta));
+        tui.requestRender();
+      };
+
+      const totalChars = atoms.reduce((sum, atom) => sum + atom.metrics.contentChars, 0);
+      const component = {
+        render(width: number): string[] {
+          const w = widthOf(width);
+          const budget = Math.max(18, Math.floor(tui.terminal.rows * 0.82));
+          const selectedAtoms = [...selected]
+            .map((index) => atoms[index])
+            .filter((atom): atom is Atom => Boolean(atom?.compressible && !keep.has(atom.ref)));
+          const chars = selectedAtoms.reduce((sum, atom) => sum + atom.metrics.contentChars, 0);
+          const charShare = percentage(chars, totalChars);
+          const images = selectedAtoms.reduce((sum, atom) => sum + atom.metrics.imageCount, 0);
+          const body: string[] = [];
+          const lineStarts = new Map<number, number>();
+          let groupNumber = 0;
+
+          atoms.forEach((atom, index) => {
+            if (atom.kind === "user") groupNumber += 1;
+            if (index === 0 || atom.kind === "user") {
+              const groupRef = atom.kind === "user" ? `g${String(groupNumber).padStart(4, "0")}` : "g0000";
+              const label = atom.kind === "user" ? short(atom.preview, Math.max(24, w - 24)) : "context before first user message";
+              body.push(frame(accent(`-- ${groupRef} | ${label}`), w));
+            }
+            lineStarts.set(index, body.length);
+            const isCursor = index === cursor;
+            const isSelected = selected.has(index);
+            const isKeep = keep.has(atom.ref) || !atom.compressible;
+            const marker = isKeep ? "K" : isSelected ? "*" : " ";
+            const state = isKeep ? success("KEEP") : isSelected ? warning("PLAN") : dim("....");
+            const tools = atom.toolNames.length ? ` tools:${atom.toolNames.join(",")}` : "";
+            const line = `${isCursor ? ">" : " "} [${marker}] ${atom.ref} ${atom.kind.padEnd(15)} ${String(atom.metrics.contentChars).padStart(6)} chars ${String(atom.metrics.imageCount).padStart(2)} img ${tools}`;
+            body.push(frame(isCursor ? accent(line) : state + " " + line.slice(2), w));
+            const preview = short(atom.preview, Math.max(30, w - 24));
+            for (const wrapped of wrapTextWithAnsi(`    ${preview}`, Math.max(20, w - 8)).slice(0, 2)) body.push(frame(dim(wrapped), w));
+          });
+
+          const header = [
+            rule(w, "+", "+"),
+            frame(accent(theme.bold(`Midcompact Selection | Draft v${draft.revision}`)), w),
+            frame(dim(`Anchor Pi usage: ${usageLine(telemetry)}`), w),
+            frame(dim(`Selected ${selectedAtoms.length}/${atoms.length} atoms | ${chars}/${totalChars} chars (${charShare} of anchor) | up to ${charShare} fewer anchor chars | ${images} images`), w),
+            rule(w, "+", "+"),
+          ];
+          const footer = [
+            rule(w, "+", "+"),
+            frame(dim("j/k move | space select | K KEEP | G add group | D remove range | S save | Esc save & close"), w),
+            frame(dim(`requested spans ${spans().length} | keep ${keep.size} | ${selectedAtoms.length} planned`), w),
+            rule(w, "+", "+"),
+          ];
+          const viewport = Math.max(4, budget - header.length - footer.length);
+          const cursorLine = lineStarts.get(cursor) ?? 0;
+          if (cursorLine < scrollOffset) scrollOffset = cursorLine;
+          else if (cursorLine >= scrollOffset + viewport) scrollOffset = cursorLine - viewport + 1;
+          scrollOffset = Math.max(0, Math.min(scrollOffset, Math.max(0, body.length - viewport)));
+          const visible = body.slice(scrollOffset, scrollOffset + viewport);
+          while (visible.length < viewport) visible.push(frame("", w));
+          return [...header, ...visible, ...footer];
+        },
+        invalidate(): void {},
+        handleInput(data: string): void {
+          if (matchesKey(data, Key.escape) || data === "q") {
+            done(dirty ? { action: "save", spans: spans(), keepRefs: [...keep] } : { action: "close" });
+            return;
+          }
+          if (data === "s" || data === "S" || matchesKey(data, Key.enter)) {
+            done({ action: "save", spans: spans(), keepRefs: [...keep] });
+            return;
+          }
+          if (data === "j" || matchesKey(data, Key.down)) move(1);
+          else if (data === "k" || matchesKey(data, Key.up)) move(-1);
+          else if (data === " " || data === "x") toggleSelection();
+          else if (data === "K") toggleKeep();
+          else if (data === "g" || data === "G") addGroup();
+          else if (data === "d" || data === "D") clearRange();
+          else if (matchesKey(data, Key.pageDown)) { scrollOffset += 10; tui.requestRender(); }
+          else if (matchesKey(data, Key.pageUp)) { scrollOffset = Math.max(0, scrollOffset - 10); tui.requestRender(); }
+        },
+      };
+      return component;
+    },
+    { overlay: true, overlayOptions: { width: "94%", maxHeight: "88%", anchor: "center" } },
+  ) as Promise<SelectionUiAction>;
+}
+
+function percentage(part: number, total: number): string {
+  if (total <= 0) return "0%";
+  const value = Math.round((part / total) * 1_000) / 10;
+  return `${Number.isInteger(value) ? value : value.toFixed(1)}%`;
+}
+
+function usageLine(telemetry: DraftTelemetry): string {
+  const usage = telemetry.anchorUsage;
+  if (!usage) return "unavailable";
+  const tokens = usage.tokens === null ? "unavailable" : String(usage.tokens);
+  const percent = usage.percent === null ? "unavailable" : `${usage.percent}%`;
+  return `${tokens}/${usage.contextWindow} tokens (${percent}, Pi reported)`;
+}

package/src/selection.ts

@@ -0,0 +1,95 @@
+// Pure selection core. A requested span may cross KEEP/protected atoms; this
+// module subtracts those nodes and returns sorted, non-overlapping ordinary
+// spans that contain no protected atom. It does not create summaries, append
+// session entries, or know whether the caller is TUI, Web, or Agent.
+
+import { isProtectedAtom } from "./atoms.js";
+import type { Atom, OrdinarySpan, SelectionSpan } from "./types.js";
+
+export interface SelectionInput {
+  /** Requested spans. May cross KEEP/protected atoms. */
+  spans: SelectionSpan[];
+  /** Atom refs marked KEEP inside the spans. */
+  keepRefs: string[];
+}
+
+export interface SelectionResult {
+  spans: OrdinarySpan[];
+}
+
+export class SelectionError extends Error {}
+
+function refIndex(atoms: readonly Atom[], ref: string): number {
+  const idx = atoms.findIndex((atom) => atom.ref === ref);
+  if (idx < 0) throw new SelectionError(`Unknown atom ref ${ref}.`);
+  return idx;
+}
+
+/**
+ * Expand a requested selection into ordinary spans.
+ *
+ * - Rejects unknown refs, reversed or empty spans.
+ * - Rejects a requested span that consists entirely of protected atoms
+ *   (compressing a protected atom directly is not allowed).
+ * - Subtracts KEEP and protected atoms from each span, splitting it into
+ *   contiguous ordinary fragments.
+ * - Merges adjacent fragments across spans and drops empty ones.
+ * - Output is sorted by start index, non-overlapping, and contains no
+ *   protected atom.
+ */
+export function expandSelection(atoms: readonly Atom[], input: SelectionInput): SelectionResult {
+  if (input.spans.length === 0) return { spans: [] };
+
+  const keepSet = new Set(input.keepRefs);
+
+  // Resolve and normalize requested spans to [start,end] inclusive index ranges.
+  const requested: Array<{ start: number; end: number }> = [];
+  for (const span of input.spans) {
+    const start = refIndex(atoms, span.startRef);
+    const end = refIndex(atoms, span.endRef);
+    if (start > end) throw new SelectionError(`Span ${span.startRef}→${span.endRef} is reversed.`);
+    requested.push({ start, end });
+  }
+  requested.sort((a, b) => a.start - b.start);
+
+  const ordinaryIndices: number[] = [];
+  for (const range of requested) {
+    let anyProtected = false;
+    let anyOrdinary = false;
+    for (let i = range.start; i <= range.end; i += 1) {
+      const atom = atoms[i];
+      if (!atom) continue;
+      if (isProtectedAtom(atom)) {
+        anyProtected = true;
+        continue;
+      }
+      if (keepSet.has(atom.ref)) continue;
+      ordinaryIndices.push(i);
+      anyOrdinary = true;
+    }
+    if (!anyOrdinary && anyProtected) {
+      const ref = atoms[range.start]!.ref;
+      throw new SelectionError(`Cannot compress protected atom ${ref}; split around it or drop it.`);
+    }
+  }
+
+  // Group ordinary indices into contiguous runs.
+  ordinaryIndices.sort((a, b) => a - b);
+  const runs: Array<{ start: number; end: number }> = [];
+  for (const idx of ordinaryIndices) {
+    const last = runs[runs.length - 1];
+    if (last && idx === last.end + 1) {
+      last.end = idx;
+    } else {
+      runs.push({ start: idx, end: idx });
+    }
+  }
+
+  const spans: OrdinarySpan[] = runs.map((run) => ({
+    startRef: atoms[run.start]!.ref,
+    endRef: atoms[run.end]!.ref,
+    startIndex: run.start,
+    endIndex: run.end,
+  }));
+  return { spans };
+}