chamba 0.6.0 → 0.7.0

package/templates/webterm/public/app/pane.js

@@ -1,58 +1,47 @@
-// pane.js - the web pane: the pages an agent published, beside the terminal it published them from.
+// pane.js - the Pages tool: the pages an agent published, beside the terminal it published them from.
 //
-// The pane is chrome this interface draws - the chips bar, the counter, the spine - around a page it does
-// not trust (pane-frame.js renders that part). Keeping the two apart is the point: a published page can
-// never fake which session and which page the user is looking at, because everything that says so is drawn
-// outside its frame.
+// One of the tools the pane holds (pane-shell.js holds them), and the whole of what this module draws is its
+// own panel - the chips bar, the counter, and the page. The pane's own furniture, the tab bar and the width,
+// is the shell's, so nothing here can move the pane or say which tool the user is looking at.
 //
-// What the pane shows belongs to the attached session, and it follows the tabs: switching sessions switches
-// the list, the selection, and the page. What the pane *is* belongs to the window - how wide it is, whether it
-// is collapsed, and how big a page is drawn in it - and that survives the switch, and a reload.
+// The chips bar is chrome this interface draws around a page it does not trust (pane-frame.js renders that
+// part). Keeping the two apart is the point: a published page can never fake which session and which page the
+// user is looking at, because everything that says so is drawn outside its frame.
+//
+// What this tool shows belongs to the attached session, and it follows the tabs: switching sessions switches
+// the list, the selection, and the page.
 //
 // A page that arrives opens itself, and says so with one pulse of the pane's edge. It never takes the
 // keyboard: the caret stays in the composer mid-sentence, which is the price of the pane opening at all.
 // "Arrives" is the server's own unread flag, not "new to this window" - the list here starts empty on every
 // reload, and a page nobody has opened in a session nobody has visited is still an arrival when they get to
 // it. A page for a session this window is not looking at touches nothing here; it marks that session's tab
-// (see tabs.js), keeps its chip badge and its place in the spine's counter, and waits.
+// (see tabs.js), keeps its chip badge and its place in the spine's counter, and waits. A page that lands
+// while the pane is open on another tool marks the Pages tab and waits there: an arrival is worth saying, and
+// never worth taking the screen for.
 //
-// The pane exists before any of that. A session that has published nothing still has its spine, and opening it
+// The tool exists before any of that. A session that has published nothing still has its tab, and opening it
 // says what the pane is for and what to ask for - a feature nobody can see is a feature nobody uses, and this
 // one is asked for in words rather than found in a menu.
 
 import { sendFrame } from "./connection.js";
-import {
-    chips,
-    grip,
-    pageBigger,
-    pagebar,
-    pageCount,
-    pageDoc,
-    pageSizeVal,
-    pageSmaller,
-    pane,
-    paneCollapse,
-    paneNext,
-    panePrev,
-    spine,
-    spineBadge,
-} from "./dom.js";
+import { chips, pageBigger, pagebar, pageCount, pageDoc, pageSizeVal, pageSmaller, paneNext, panePrev, toolPages } from "./dom.js";
 import { arrivingPage } from "./pane-arrival.js";
 import { dropPage, fetchPage, renderPage, submitFeedback } from "./pane-frame.js";
+import {
+    flashPane,
+    isPaneCollapsed,
+    isPaneShut,
+    isToolOpen,
+    noteTool,
+    PAGES,
+    registerTool,
+    rememberPageSize,
+    setPaneCollapsed,
+    storedPageSize,
+} from "./pane-shell.js";
 import { attachedSid } from "./state.js";
 
-// Narrower than this and the pane is not a pane any more, so it becomes the spine instead. The mock's
-// threshold, and the width the spine itself takes.
-const COLLAPSE_AT = 150;
-// What the pane opens at, in a fraction of the window, and the most of the window a drag may give it.
-const DEFAULT_FRACTION = 0.44;
-const MAX_FRACTION = 0.7;
-// The least of the window the pane may come back into. Reopening is not the same as resizing: whatever width
-// it was put away at, a pane you have just asked for has to be wide enough to read a page in.
-const MIN_OPEN_FRACTION = 1 / 3;
-// The window's own pane preferences: how wide, whether it is collapsed, and how big a page is drawn in it.
-// Not the session's - a pane is furniture, and furniture does not move because you looked at another tab.
-const GEOMETRY_KEY = "webterm-pane";
 // The sizes a page can be shown at, smallest first, and where an untouched window starts. The spacing is
 // deliberately uneven: a correction near normal reading size wants a fine step, and someone going to 150%
 // wants to get there in two presses.
@@ -66,39 +55,13 @@ const AGE_TICK_MS = 30_000;
 // heard about, so switching back to a tab lands on the page it was left on.
 const panes = new Map();
 
-let width = null;
-// null means nobody has said. An untouched pane keeps out of the way while its session has nothing in it, and
-// is open once it has - which is the first page of a session opening on arrival, as it always did. A click on
-// the spine or on the collapse button is an answer, and from then on it is the only one that counts.
-let collapsed = null;
-// Which of TEXT_SIZES the shown page is drawn at.
-let sizeStep = DEFAULT_SIZE_STEP;
-// What the last render decided, for the two things that only need to know whether the pane is showing.
-let shut = true;
-
-// --- What the window remembers -----------------------------------------------------------------------------------------------------------
-
-try {
-    const stored = JSON.parse(localStorage.getItem(GEOMETRY_KEY) ?? "{}");
-    if (typeof stored.width === "number" && stored.width >= COLLAPSE_AT) width = stored.width;
-    if (typeof stored.collapsed === "boolean") collapsed = stored.collapsed;
-    // The multiplier is stored rather than its position, so a window that was left at a size this version no
-    // longer offers falls back to the default instead of landing between two steps.
-    const step = TEXT_SIZES.indexOf(stored.size);
-    if (step !== -1) sizeStep = step;
-} catch {
-    // A disabled or full store only means the pane opens at its default width.
-}
-
-function rememberGeometry() {
-    try {
-        localStorage.setItem(GEOMETRY_KEY, JSON.stringify({ width, collapsed, size: TEXT_SIZES[sizeStep] }));
-    } catch {
-        // The pane still works for this page's lifetime.
-    }
-}
+// Which of TEXT_SIZES the shown page is drawn at. The multiplier is what the pane stores, so a window that
+// was left at a size this version no longer offers falls back to the default instead of landing between two
+// steps.
+const storedStep = TEXT_SIZES.indexOf(storedPageSize());
+let sizeStep = storedStep === -1 ? DEFAULT_SIZE_STEP : storedStep;
 
-// --- The pane's own state ----------------------------------------------------------------------------------------------------------------
+// --- The tool's own state ----------------------------------------------------------------------------------------------------------------
 
 function paneFor(sid) {
     let entry = panes.get(sid);
@@ -122,14 +85,16 @@ export function applyPages(msg) {
     // The page this frame opens, if it opens one - the rule itself is in pane-arrival.js, where it can be run,
     // and so is what a burst of publishes does under it.
     const arrived = arrivingPage(entry.pages);
+    // It is selected either way, so the tab the user comes back to is on the page that arrived. Only the
+    // saying-so is held back while another tool has the pane.
     if (arrived !== null) {
         select(msg.sid, arrived.id, { user: false });
-        flashArrival();
+        if (isToolOpen(PAGES)) flashPane();
     }
     // A pane someone put away comes back for a page. Only for an answer they gave: the third state, nobody
     // has said, already opens the pane when its session stops being empty, and settling it here would open
     // the pane in every other empty session in this window too.
-    if (arrived !== null && collapsed === true) setCollapsed(false);
+    if (arrived !== null && isToolOpen(PAGES) && isPaneCollapsed()) setPaneCollapsed(false);
     else render();
 }
 
@@ -141,7 +106,7 @@ export function prunePanes(live) {
 }
 
 /**
- * Draw the pane for whatever session this window is now on, asking for its pages when this window has never
+ * Draw the tool for whatever session this window is now on, asking for its pages when this window has never
  * been told them. The server pushes the list when a window lands on a session, so this covers the frame that
  * did not arrive - a socket replaced mid-attach, or a window that took a session over from another one.
  */
@@ -257,25 +222,16 @@ function chipFor(sid, page, selected) {
     return chip;
 }
 
-// How wide, and collapsed or not. Its own function because a drag is the one thing that changes the pane
-// without changing anything in it: sixty of these a second are cheap, and sixty full redraws are not.
-function applyGeometry(collapsedNow = shut) {
-    pane.classList.toggle("collapsed", collapsedNow);
-    // The width goes into a custom property rather than straight onto `width`, so the stylesheet keeps the
-    // last word: the collapsed spine and the narrow-screen layout are rules, and an inline width would beat
-    // both of them.
-    pane.style.setProperty("--pane-width", width === null ? `${DEFAULT_FRACTION * 100}%` : `${width}px`);
-}
-
 // --- How big a page is drawn -------------------------------------------------------------------------------------------------------------
 
-// The size is a property on the pane, and the stylesheet zooms the frame from it. Two reasons, both structural:
-// the frame's document has an opaque origin and the shell cannot reach into it, and renderPage() throws the
-// iframe away and builds a fresh one on every chip click, so anything set on the frame itself would have to be
-// put back on every one of those paths. Setting it out here costs nothing and cannot be missed.
+// The size is a property on this tool's panel, and the stylesheet zooms the frame from it. Two reasons, both
+// structural: the frame's document has an opaque origin and the shell cannot reach into it, and renderPage()
+// throws the iframe away and builds a fresh one on every chip click, so anything set on the frame itself
+// would have to be put back on every one of those paths. Setting it out here costs nothing and cannot be
+// missed.
 function applyTextSize() {
     const size = TEXT_SIZES[sizeStep];
-    pane.style.setProperty("--page-zoom", String(size));
+    toolPages.style.setProperty("--page-zoom", String(size));
     pageSizeVal.textContent = `${Math.round(size * 100)}%`;
     // A control that can do nothing says so, rather than swallowing the press.
     pageSmaller.disabled = sizeStep === 0;
@@ -287,49 +243,25 @@ function stepTextSize(by) {
     if (next === sizeStep) return;
     sizeStep = next;
     applyTextSize();
-    rememberGeometry();
+    rememberPageSize(TEXT_SIZES[sizeStep]);
 }
 
 pageSmaller.addEventListener("click", () => stepTextSize(-1));
 pageBigger.addEventListener("click", () => stepTextSize(1));
 applyTextSize();
 
-// --- Saying that a page arrived ----------------------------------------------------------------------------------------------------------
-
-// One pulse of the pane's edge, in the workspace colour. ARRIVAL_MS must match the keyframes in styles.css.
-const ARRIVAL_MS = 1_000;
-let arrivalTimer = null;
-
-// The class comes off on a timer rather than on animationend, because with a reduced-motion preference there
-// is no animation to end - the stylesheet holds the highlight instead of pulsing it, and this is what makes
-// the two last the same moment.
-function flashArrival() {
-    clearTimeout(arrivalTimer);
-    // A pulse still running when the next page lands restarts rather than stacking: off, force the browser to
-    // notice, on again. Reading a layout property is what makes the restart real.
-    pane.classList.remove("arriving");
-    void pane.offsetWidth;
-    pane.classList.add("arriving");
-    arrivalTimer = setTimeout(() => pane.classList.remove("arriving"), ARRIVAL_MS);
-}
-
 function render() {
     const sid = attachedSid;
     const entry = sid === null ? null : (panes.get(sid) ?? null);
     const pages = entry?.pages ?? [];
     const unread = pages.filter((page) => page.unread).length;
 
-    // Nothing published in this session, and nothing to say about it. The pane stays - as the spine, until
-    // someone opens it - because a pane that only appears once an agent has used it is one nobody knows to
-    // ask for. The grip is the part that goes: there is no width worth choosing for a page that does not exist.
+    // Nothing published in this session, and nothing to say about it. The tab stays - and the pane stays as
+    // the spine, until someone opens it - because a pane that only appears once an agent has used it is one
+    // nobody knows to ask for. Saying so is the shell's business: the tab's mark, and whether an untouched
+    // pane keeps out of the way, are the pane's decisions to take from what its open tool has.
     const bare = pages.length === 0 && !entry?.notice;
-    shut = collapsed === null ? bare : collapsed;
-    pane.hidden = false;
-    grip.hidden = bare && shut;
-
-    applyGeometry(shut);
-    spineBadge.textContent = unread > 0 ? String(unread) : "";
-    spineBadge.hidden = unread === 0;
+    noteTool(PAGES, { unread, empty: bare });
 
     chips.replaceChildren(...pages.map((page) => chipFor(sid, page, page.id === entry?.selected)));
     const at = pages.findIndex((page) => page.id === entry?.selected);
@@ -364,75 +296,18 @@ function render() {
     chips.querySelector(".chip.sel")?.scrollIntoView({ block: "nearest", inline: "nearest" });
 }
 
+// The tool draws itself whenever the pane asks - a tab click, a width that changed, a session switch.
+registerTool(PAGES, render);
+
 setInterval(() => {
-    if (!shut) render();
+    if (!isPaneShut() && isToolOpen(PAGES)) render();
 }, AGE_TICK_MS);
 
-// --- The divider, and the spine ----------------------------------------------------------------------------------------------------------
-
-// Dragging sets a pixel width until it stops making sense, and below the threshold the pane becomes the
-// spine rather than a sliver. Pointer capture keeps the drag alive over the terminal and the frame alike -
-// a page is a document with its own event loop, and without capture the pointer would be lost in it.
-let dragging = false;
-// The width the pane had when the drag started. Dragging it shut is a request to put it away, not a request
-// for a 150px pane, so crossing the threshold hands its old width back rather than keeping the sliver the
-// pointer passed through on the way there.
-let widthBeforeDrag = null;
-
-grip.addEventListener("pointerdown", (event) => {
-    dragging = true;
-    widthBeforeDrag = width;
-    document.body.classList.add("dragging");
-    grip.setPointerCapture(event.pointerId);
-});
-
-grip.addEventListener("pointermove", (event) => {
-    if (!dragging) return;
-    const wanted = Math.max(0, window.innerWidth - event.clientX - grip.offsetWidth / 2);
-    if (wanted < COLLAPSE_AT) {
-        collapsed = true;
-        width = widthBeforeDrag;
-    } else {
-        collapsed = false;
-        width = Math.min(wanted, window.innerWidth * MAX_FRACTION);
-    }
-    // A drag is an answer too, so what it decides is what the next render starts from.
-    shut = collapsed;
-    applyGeometry(shut);
-});
-
-function endDrag() {
-    if (!dragging) return;
-    dragging = false;
-    document.body.classList.remove("dragging");
-    rememberGeometry();
-}
-
-grip.addEventListener("pointerup", endDrag);
-grip.addEventListener("pointercancel", endDrag);
-
-// Away, and back. Two ways in and one way out, because the pane is put away far more often than it is
-// resized: the button in the bar is the obvious one, and dragging the grip past the threshold is the other.
-function setCollapsed(next) {
-    collapsed = next;
-    shut = next;
-    // Back at whatever width it had, unless that width would be a sliver - a pane dragged shut, or one from
-    // a window remembered narrower than this one, has to open into something a page fits in.
-    if (!collapsed) {
-        const floor = Math.min(window.innerWidth * MIN_OPEN_FRACTION, window.innerWidth * MAX_FRACTION);
-        if (width !== null && width < floor) width = floor;
-    }
-    rememberGeometry();
-    render();
-}
-
-paneCollapse.addEventListener("click", () => setCollapsed(true));
-spine.addEventListener("click", () => setCollapsed(false));
-
-// The chips bar scrolls by roughly a bar's worth, which is what the arrows in the mock do.
-panePrev.addEventListener("click", () => chips.scrollBy({ left: -chips.clientWidth * 0.8, behavior: "smooth" }));
-paneNext.addEventListener("click", () => chips.scrollBy({ left: chips.clientWidth * 0.8, behavior: "smooth" }));
 // A bar that fits at one width may not at another, and the arrows only exist when it does not.
 window.addEventListener("resize", render);
+// The bar hides its scrollbar, so these are the only way to reach a chip that scrolled out of it. A little
+// under a full bar each time, so the chip at the edge stays on the screen and says where the bar now is.
+panePrev.addEventListener("click", () => chips.scrollBy({ left: -chips.clientWidth * 0.8, behavior: "smooth" }));
+paneNext.addEventListener("click", () => chips.scrollBy({ left: chips.clientWidth * 0.8, behavior: "smooth" }));
 // The pagebar is chrome: a click on it must not leave the terminal without focus for no reason.
 pagebar.addEventListener("mousedown", (event) => event.preventDefault());

package/templates/webterm/public/app/specs-host.js

@@ -0,0 +1,222 @@
+// specs-host.js - the Specs tool: the spec workspace, in a frame of its own.
+//
+// The tool's client is not part of this interface. It is built elsewhere and rendered here in a frame with an
+// opaque origin, the same way a published page is, so the shell's key never enters it and one rendering bug
+// can leak spec reading at worst. This module is the host around that frame: it owns the panel, the frame,
+// and the one message that gives the frame what it needs to ask the server anything.
+//
+// The handover is the whole point of this file. The frame gets a Specs-scoped key that opens the tool's data
+// routes and a path prefix that opens workspace files, and it gets them once, unprompted, on the load of the
+// document this shell put there. It is never handed out on request: a window object survives a navigation, so
+// a document that navigated itself into this frame would ask with the same identity as the one that was
+// loaded. A second load is therefore read as a navigation, and the frame is thrown away and built again.
+
+import { sendFrame } from "./connection.js";
+import { toolSpecs } from "./dom.js";
+import { noteTool, registerTool, SPECS } from "./pane-shell.js";
+import { KEY_HEADER, WEB_KEY } from "./state.js";
+
+// Where the built client is served from, and where the shell asks for the frame's credentials. The second one
+// is behind the master key in a header, which is the shell's own gate and never the frame's.
+const FRAME_SRC = "/pane-apps/specs/index.html";
+const KEYS_URL = "/specs/keys";
+
+// What the shell and the frame call each other's messages. Namespaced because a frame may be talking to
+// something else of its own, and every message is checked against the frame it must come from.
+const HANDOVER = "specs:credentials";
+const CHANGE = "specs:change";
+const OPEN = "specs:open";
+const DELIVER = "specs:deliver";
+const WAITING = "specs:waiting";
+const DELIVERED = "specs:delivered";
+
+// How many times a frame that navigates itself is rebuilt before the tab says so instead. A client that keeps
+// leaving the document it was given is broken or is being driven, and either way rebuilding it for ever is a
+// spinning window rather than a recovery.
+const MAX_REBUILDS = 3;
+
+let frame = null;
+let handed = false;
+let rebuilds = 0;
+let credentials = null;
+let asking = false;
+let failure = null;
+// How many things are waiting for the user inside the tool. Kept here rather than in the frame, because the
+// mark has to hold while another tool is open and the frame is not being drawn.
+let waiting = 0;
+
+/** Fetch the frame's credentials. The shell holds the master key; this is the only route it opens for Specs. */
+async function fetchCredentials() {
+    if (asking) return;
+    asking = true;
+    try {
+        const response = await fetch(KEYS_URL, { headers: { [KEY_HEADER]: WEB_KEY }, cache: "no-store" });
+        if (!response.ok) throw new Error(String(response.status));
+        const answer = await response.json();
+        if (typeof answer?.key !== "string" || typeof answer?.raw !== "string") throw new Error("no credentials");
+        credentials = answer;
+        failure = null;
+    } catch {
+        failure = "The Specs tool could not be reached. The next time this tab is opened it tries again.";
+    } finally {
+        asking = false;
+    }
+    // Drawn whether the tab is open or not. The panel is off the screen when it is not, so nothing is shown
+    // either way, but this is the step that puts the frame up - and the tool has to be running to say what
+    // is waiting for the user, wherever in the pane that user happens to be.
+    render();
+}
+
+/** Put a fresh frame in the panel, replacing whatever was there. */
+function build() {
+    const next = document.createElement("iframe");
+    next.className = "tool-frame";
+    // The whole boundary in one attribute: scripts and forms, and no same-origin, so the document has an
+    // opaque origin and nothing of this window is reachable from inside it - not the DOM, not storage, and
+    // not the URL that carries the master key. Set before the src, since the sandbox of a frame that already
+    // has a document is not what a later attribute says it is.
+    next.setAttribute("sandbox", "allow-scripts allow-forms");
+    // A frame inherits its embedder's referrer, and this window's URL carries the master key - both as
+    // `document.referrer` inside the frame and as the `Referer` header on everything it loads.
+    next.setAttribute("referrerpolicy", "no-referrer");
+    next.setAttribute("title", "Specs");
+    next.addEventListener("load", () => onLoad(next));
+    next.src = FRAME_SRC;
+    frame = next;
+    handed = false;
+    toolSpecs.replaceChildren(next);
+}
+
+/** The frame finished loading a document. The first one is the client; a second one is a navigation. */
+function onLoad(loaded) {
+    if (loaded !== frame) return;
+    if (!handed) {
+        handed = true;
+        loaded.contentWindow?.postMessage({ t: HANDOVER, key: credentials.key, raw: credentials.raw }, "*");
+        return;
+    }
+    if (rebuilds >= MAX_REBUILDS) {
+        frame = null;
+        failure = "The Specs tool kept leaving the page it was given, so it was stopped.";
+        render();
+        return;
+    }
+    rebuilds += 1;
+    build();
+}
+
+/** One sentence in the middle of the panel: what the tab is doing, or why it is doing nothing. */
+function say(line) {
+    const wrap = document.createElement("div");
+    wrap.className = "pane-intro";
+    const title = document.createElement("h2");
+    title.textContent = "Specs";
+    const lede = document.createElement("p");
+    lede.textContent = line;
+    wrap.append(title, lede);
+    toolSpecs.replaceChildren(wrap);
+}
+
+function render() {
+    // The tab always has something to show, so it never asks the pane to keep out of the way. What is on it
+    // is what the tool last said is waiting for the user, which holds while another tool is open.
+    noteTool(SPECS, { unread: waiting, empty: false });
+    if (failure !== null) {
+        // Said once and then forgotten, so coming back to the tab is what tries again.
+        const line = failure;
+        failure = null;
+        frame = null;
+        say(line);
+        return;
+    }
+    // A frame that is up is left alone: it holds the tool's whole state, and rebuilding it would be a reload
+    // every time the user came back to the tab.
+    if (frame !== null) return;
+    if (credentials === null) {
+        say("Opening the specs in this repository.");
+        fetchCredentials();
+        return;
+    }
+    build();
+}
+
+/** The disk moved under a spec. Passed straight in: the frame decides what is worth re-reading. */
+export function applySpecs(msg) {
+    if (frame === null || !handed) return;
+    frame.contentWindow?.postMessage({ t: CHANGE, change: msg.change }, "*");
+}
+
+/**
+ * Whether a message is the tool asking for something, rather than anything else on this window.
+ *
+ * Two checks, and each one holds without the other. The sender must be the frame's own window, which refuses
+ * a workspace document nested inside the tool - it is a frame of its own and can post here. And the message
+ * must carry the Specs key, which only the document this shell loaded ever received, so a document that
+ * navigated the frame passes the window check and fails this one.
+ */
+function fromTool(event, message) {
+    if (frame === null || !handed || credentials === null) return false;
+    if (event.source !== frame.contentWindow) return false;
+    return typeof message.key === "string" && message.key === credentials.key;
+}
+
+// A link the tool will not follow itself. The frame has to stay the document this shell put in it, since a
+// navigation would keep the window identity every check here rests on, so an outside link is opened as a
+// window of this interface instead - the web alone, and with nothing of this window carried into it.
+window.addEventListener("message", (event) => {
+    const message = event.data;
+    if (!message || typeof message !== "object" || message.t !== OPEN) return;
+    if (!fromTool(event, message)) return;
+    let url;
+    try {
+        url = new URL(String(message.url));
+    } catch {
+        return;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") return;
+    window.open(url.href, "_blank", "noopener,noreferrer");
+});
+
+// The tool saying what it is waiting on. The count is the tool's own, and the mark it puts on the tab is the
+// shell's - which is what makes something awaiting an answer visible from any other tool in the pane.
+window.addEventListener("message", (event) => {
+    const message = event.data;
+    if (!message || typeof message !== "object" || message.t !== WAITING) return;
+    if (!fromTool(event, message)) return;
+    const count = Number(message.count);
+    waiting = Number.isFinite(count) && count > 0 ? Math.min(Math.floor(count), 99) : 0;
+    noteTool(SPECS, { unread: waiting, empty: false });
+});
+
+// A delivery: the tool telling the agent beside it that something arrived. It rides this window's own socket,
+// so the server resolves the session from the socket the way every other pane frame does, and nothing here
+// or in the frame names one. What travels is the kind of event, a line of detail, the file the tool wrote,
+// and whether the user agreed to start a session for it.
+window.addEventListener("message", (event) => {
+    const message = event.data;
+    if (!message || typeof message !== "object" || message.t !== DELIVER) return;
+    if (!fromTool(event, message)) return;
+    sendFrame({
+        t: DELIVER,
+        event: String(message.event ?? ""),
+        detail: String(message.detail ?? ""),
+        path: String(message.path ?? ""),
+        create: message.create === true,
+    });
+});
+
+/** What the server made of the last delivery, passed back to the frame that asked for it. */
+export function applySpecsDelivery(msg) {
+    if (frame === null || !handed) return;
+    frame.contentWindow?.postMessage({ t: DELIVERED, ok: msg.ok === true, error: msg.error ?? "" }, "*");
+}
+
+registerTool(SPECS, render);
+
+// The frame is built at startup rather than the first time the tab is opened, because the mark on the tab is
+// the tool's to put there and the tool cannot say anything until it is running. Waiting for the first open
+// would make "something is waiting for you" visible only to a user who already went and looked, which is the
+// one reader who did not need telling - and a window reopened on another tool would show nothing at all.
+// Nothing is drawn by this: the panel is off the screen until its tab is picked, and the frame holds the
+// tool's state from here on, so opening the tab shows what is already there instead of loading it then.
+render();

package/templates/webterm/public/app/state.js

@@ -40,7 +40,7 @@ export function labelOf(sid, fallback) {
     return sessions.find((entry) => entry.id === sid)?.label ?? fallback;
 }
 
-// The key that came with the URL. The server mints a new one every time it starts and refuses everything
+// The key that came with the URL. The server creates a new one every time it starts and refuses everything
 // without it, so this is also what goes stale: a window left open across a restart still holds the old key,
 // which is the case the curtain explains rather than reconnecting forever.
 export const WEB_KEY = new URLSearchParams(location.search).get("k") ?? "";

package/templates/webterm/public/app/tabs.js

@@ -171,7 +171,7 @@ function renameEditor(entry) {
     editor.className = "rename";
     editor.value = editingValue;
     editor.spellcheck = false;
-    // A soft cap for the field; the server trims to its own limit and strips control characters.
+    // A soft limit for the field; the server trims to its own limit and strips control characters.
     editor.maxLength = 60;
     editor.addEventListener("click", (event) => event.stopPropagation());
     editor.addEventListener("dblclick", (event) => event.stopPropagation());

package/templates/webterm/public/app/terminal.js

@@ -87,10 +87,18 @@ term.onData((data) => {
 // Keep the PTY's window size in step with the rendered terminal. Debounced: a resize storm
 // (layout settling, pane drag) collapses to one fit + one resize, which cuts down the redraw
 // artifacts the TUI shows when width changes mid-render.
+//
+// A terminal with no width on the screen is not a narrow terminal, and the PTY is not told about one.
+// The pane at its full width leaves the row nothing, and the fit would answer with its own floor of two
+// columns: the agent's TUI would take that as a real window, reflow its frame and its scrollback into
+// two columns, and keep the mangled scrollback after the pane came back. Holding the last real size
+// instead is what makes "squeezed out rather than hidden" true for the process as well as the layout -
+// nothing is sent while it is out of the row, and the next pass sends the width it returns at.
 let resizeTimer = null;
 const resizeObserver = new ResizeObserver(() => {
     if (resizeTimer) clearTimeout(resizeTimer);
     resizeTimer = setTimeout(() => {
+        if (termEl.clientWidth === 0 || termEl.clientHeight === 0) return;
         try {
             fit.fit();
             sendResize();