chamba 0.7.0 → 0.9.0

package/templates/webterm/config.js

@@ -42,6 +42,12 @@ export const RESUME_STAMP = process.env.WEBTERM_RESUME_STAMP || "/home/devuser/.
 // chamba reads the same file when it starts the interface at the next container start.
 export const STATE_FILE = process.env.WEBTERM_STATE_FILE || "/home/devuser/.chamba-webterm/agent";
 
+// One-line file holding the id of the accent colour the user picked for this workspace, written when they
+// pick one and deleted when they ask for automatic. Empty means nothing was picked, and the browser works the
+// colour out from the published port instead. Sits beside STATE_FILE in the same mounted directory, so the
+// choice outlives the container: a rebuild replaces everything except what is kept out here.
+export const COLOR_FILE = process.env.WEBTERM_COLOR_FILE || "/home/devuser/.chamba-webterm/color";
+
 // The mounted workspace, and the only tree a session may be started in. Every directory the interface
 // deals with is this one or something under it.
 export const WORKSPACE_ROOT = "/workspace";
@@ -75,11 +81,12 @@ export const MAX_PANE_FILES = Number(process.env.WEBTERM_MAX_PANE_FILES) || 5_00
 // every host.
 export const PANE_SCAN_MS = Number(process.env.WEBTERM_PANE_SCAN_MS) || 1_500;
 
-// --- The Specs tool ----------------------------------------------------------------------------------------------------------------------
+// --- The pane's tools --------------------------------------------------------------------------------------------------------------------
 //
-// The first of the pane's tools. Its client and its server module are built from the pane-apps package and
-// baked beside webterm, so this side names where they sit, what they are pointed at, and the two scoped
-// credentials that open them.
+// The tools beside the terminal, whose clients and server modules are built from the pane-apps package and
+// baked beside webterm. This side names where they sit, what each one is pointed at, and the two scoped
+// credentials that open each of them. What a tool is otherwise - its routes, its verbs, its sentences - is a
+// table of its own in `tools/`.
 
 // Where the built tool clients and server modules sit: a sibling of this directory, which is true both of the
 // image's bake and of a checkout, where chamba's build stages the same dist.
@@ -118,6 +125,50 @@ export const MAX_SPECS_LINES_PER_SESSION = Number(process.env.WEBTERM_MAX_SPECS_
 // its prompt, and a paste that arrives before it does is read by the terminal rather than by the agent.
 export const SPECS_NEW_SESSION_DELAY_MS = Number(process.env.WEBTERM_SPECS_NEW_SESSION_DELAY_MS) || 3_000;
 
+// The directory of reviews the second tool serves, beside the specs of the first. A mount parameter for the
+// same reason: a repository keeps its reviews where it likes, and the tool is pointed at that directory.
+export const REVIEWS_ROOT = process.env.WEBTERM_REVIEWS_ROOT || join(WORKSPACE_ROOT, "reviews");
+
+// This tool's own two credentials, made the same way and opening nothing of the other's. One key per tool
+// rather than one for the pane: a rendering bug inside one frame then leaks that tool's reading and no more.
+export const REVIEWS_KEY = process.env.WEBTERM_REVIEWS_KEY || randomBytes(16).toString("hex");
+export const REVIEWS_RAW_TOKEN = process.env.WEBTERM_REVIEWS_RAW_TOKEN || randomBytes(16).toString("hex");
+
+// The largest body a Code Reviews data route accepts. Smaller than the Specs one by a lot: the biggest thing
+// a review posts is an approval, which carries one signature drawn in a browser, and a page of hunks travels
+// the other way. Nothing a reviewer sends is a file.
+export const MAX_REVIEWS_BYTES = 4 * 1024 * 1024;
+
+// What a Code Reviews delivery may be. The three bounds are the Specs ones, for the reasons written above
+// them: a line is refused rather than trimmed, a gap is what a person looks like, and a session accepts only
+// so many deliveries for as long as this container runs.
+export const MAX_REVIEWS_LINE_LENGTH = Number(process.env.WEBTERM_MAX_REVIEWS_LINE_LENGTH) || 600;
+export const REVIEWS_LINE_MIN_INTERVAL_MS = Number(process.env.WEBTERM_REVIEWS_LINE_MIN_INTERVAL_MS) || 1_000;
+export const MAX_REVIEWS_LINES_PER_SESSION = Number(process.env.WEBTERM_MAX_REVIEWS_LINES_PER_SESSION) || 500;
+
+// And the wait for a session this delivery had to start, which is about the agent CLI rather than the tool.
+export const REVIEWS_NEW_SESSION_DELAY_MS = Number(process.env.WEBTERM_REVIEWS_NEW_SESSION_DELAY_MS) || 3_000;
+
+// --- Home --------------------------------------------------------------------------------------------------------------------------------
+
+// Where the Home tool keeps what it worked out about the repository. Its numbers are all derived and belong
+// to nobody, so they are not the work: a file of them in the workspace would show up in the `git status` of
+// every repository Home opens, and a file of them in the container would die with it. This directory is bind-
+// mounted from the host workspace cache, beside STATE_FILE, so the cache outlives a rebuild. The module
+// refuses a directory inside the workspace, so the two can never be the same place.
+export const HOME_CACHE_DIR = process.env.WEBTERM_HOME_CACHE_DIR || "/home/devuser/.chamba-webterm";
+
+// This tool's own two credentials, made the same way and opening nothing of the other tools'. Home serves no
+// workspace file at all, so the raw token opens nothing; it is issued all the same, because the raw door is
+// registered for every tool and a tool with no token would be a tool with no door to refuse at.
+export const HOME_KEY = process.env.WEBTERM_HOME_KEY || randomBytes(16).toString("hex");
+export const HOME_RAW_TOKEN = process.env.WEBTERM_HOME_RAW_TOKEN || randomBytes(16).toString("hex");
+
+// The largest body a Home data route accepts. Every route is a GET with no body, so this is the size of the
+// nothing they carry; the door that gates a body reads it for every tool, and a tool with no number is a tool
+// with no gate.
+export const MAX_HOME_BYTES = 64 * 1024;
+
 // --- The status strip --------------------------------------------------------------------------------------------------------------------
 
 // How often a session's snapshot file is looked at again for the strip above the composer. A poll for the

package/templates/webterm/context/claude.md

@@ -11,4 +11,3 @@ Use it for anything longer or more structured than a terminal reply carries well
 The `web-pane` skill is how to write one well; read it before your first page.
 
 **The status strip.** Above the composer the user can already see this session's model, the context it is holding, and what is left of the quota, so there is no need to report any of it unasked.
-Run `context-usage` when you want the same numbers yourself.

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

@@ -8,7 +8,8 @@ import { SVG_NS } from "./dom.js";
 import { sessions, workspaceName } from "./state.js";
 import { arrivedAt, renderBar } from "./tabs.js";
 import { focusTerminal } from "./terminal.js";
-import { WORKSPACE_COLOR } from "./theme.js";
+import { workspaceColor } from "./theme.js";
+import { toolsHearSound } from "./tool-host.js";
 
 // --- The browser's own tab ---------------------------------------------------------------------------------------------------------------
 //
@@ -20,6 +21,12 @@ import { WORKSPACE_COLOR } from "./theme.js";
 //   nothing                       - nothing is happening in here
 //   white bar across the bottom   - an agent is working, with a lit segment moving along it
 //   green dot in the top corner   - an agent finished and is waiting for you, pulsing until you go and look
+//   grey all through, and still   - this window cannot reach its container, so it says nothing else at all
+//
+// The grey one is the odd member of the four, because it is about this window rather than about the container.
+// Every other mark stands on the last sessions frame the server sent, and while the socket is down that frame
+// only gets older - so a green dot calls you back to a session this window can no longer see. Draining the
+// icon says the one thing that is still true, and the title and the chime below are held to the same rule.
 //
 // One mark at a time, and the two are told apart by where they sit before any colour is read: working owns the
 // bottom edge, waiting owns the top-right corner. That was the lesson of the first version, where both were a
@@ -27,8 +34,8 @@ import { WORKSPACE_COLOR } from "./theme.js";
 // are the same dot. Green outranks white, since something that wants you matters more than something still going.
 //
 // Working is white rather than a colour on purpose. Every hue in this interface belongs to a workspace or to a
-// session, and the frame around this very icon is one of six of them - so a blue mark sat inside a blue frame in
-// one workspace out of six and stopped reading as a mark at all. White belongs to nobody, and it leaves green as
+// session, and the frame around this very icon is one of the eleven the user can choose from - so a blue mark
+// sat inside a blue frame stopped reading as a mark at all. White belongs to nobody, and it leaves green as
 // the only hue in the icon that means anything, which is what makes the pair read as a traffic light.
 //
 // Both marks move, and neither leans on a particular frame to be understood. A hidden tab is exactly the tab this
@@ -50,10 +57,27 @@ const PULSE_TICKS = 3;
 const SWEEP_TICKS = 16;
 const DONE_COLOR = "#2fe58a";
 const BUSY_COLOR = "#e6edf3";
+// The offline pair: the interface's own muted text grey for the spark, and its border grey for the frame. Flat,
+// with no gradient - at 16px a gradient between two greys says nothing. Anything fainter than this reads as a
+// broken tab rather than an offline one, which is a different thing to tell someone.
+const OFFLINE_SPARK = "#8b949e";
+const OFFLINE_FRAME = "#30363d";
+// How long the socket has to stay down before the icon says so. Most disconnects are a sleeping laptop or a wifi
+// blip and are over inside this, so the icon holds still rather than flickering grey and back. The curtain waits
+// the same three seconds, and the two waits cannot be shared: the curtain's is measured from the end of a /status
+// request that has three seconds of its own, and it is skipped entirely for a window that has stopped trying.
+// It is not only the icon's: the chime below reads the same flag, so lengthening this leaves a window sounding
+// for a container it cannot reach for that much longer.
+const OFFLINE_GRACE_MS = 3_000;
 
 let iconCanvas = null;
 let iconTimer = null;
 let iconFrame = 0;
+// Whether this window has given up on reaching its container, and the grace that is counting towards it. A
+// slower thing than the `offline` class on the body, which goes on at the first close: that one stops the page
+// taking clicks it cannot answer, and this one waits to see whether there is anything worth saying.
+let offline = false;
+let offlineTimer = null;
 
 // What the dot should say right now, or null for no dot. Read fresh on every paint rather than passed in, so a
 // paint from anywhere - an incoming bar, or the pulse - draws what is true now.
@@ -85,7 +109,10 @@ function paintFavicon() {
     iconCanvas.height = ICON_SIZE;
     const ctx = iconCanvas.getContext("2d");
     if (!ctx) return;
-    const badgeColor = dotColor();
+    // No mark at all while the window cannot reach its container, whatever the last frame said was happening:
+    // both marks stand on state nothing is coming to correct, so the grey is the whole message and the two ways
+    // of arriving at it - going offline while an agent works, and going offline while one waits - are one icon.
+    const badgeColor = offline ? null : dotColor();
     // Only one mark is ever drawn, so both phases can be handed over and the drawing picks the one it needs.
     try {
         drawIcon(ctx, badgeColor, badgeColor === DONE_COLOR && pulseDim(), sweepAt());
@@ -106,7 +133,9 @@ function drawIcon(ctx, badgeColor, dim, sweep) {
     ctx.beginPath();
     ctx.roundRect(0, 0, 32, 32, 7);
     ctx.fill();
-    ctx.strokeStyle = WORKSPACE_COLOR;
+    // Offline drains the frame with everything else: the workspace hue is the liveliest thing in the icon, and
+    // one grey shape says more than a grey spark inside a bright ring.
+    ctx.strokeStyle = offline ? OFFLINE_FRAME : workspaceColor();
     ctx.lineWidth = 2;
     ctx.beginPath();
     ctx.roundRect(1, 1, 30, 30, 6);
@@ -115,9 +144,14 @@ function drawIcon(ctx, badgeColor, dim, sweep) {
     // The spark: four points with a waist, stroked as well as filled so it nearly fills the icon and still
     // reads at 16px. Same geometry and gradient as favicon.svg, which is what a browser without canvas still
     // gets - the two are one drawing in two languages, so a change to either is a change to both.
-    const spark = ctx.createLinearGradient(0, 0, 0, 32);
-    spark.addColorStop(0, "#f0c078");
-    spark.addColorStop(1, "#d08a3c");
+    let spark;
+    if (offline) {
+        spark = OFFLINE_SPARK;
+    } else {
+        spark = ctx.createLinearGradient(0, 0, 0, 32);
+        spark.addColorStop(0, "#f0c078");
+        spark.addColorStop(1, "#d08a3c");
+    }
     ctx.fillStyle = spark;
     ctx.strokeStyle = spark;
     ctx.lineWidth = 2;
@@ -194,7 +228,9 @@ function tickIcon() {
 export function refreshBrowserTab() {
     // Just the workspace, no product name: a tab strip gives you a few characters, and the icon already says
     // this is chamba. What the title is for is which workspace, and how many sessions want you.
-    const waiting = sessions.filter((entry) => entry.attention);
+    // The count goes with the icon's marks while the socket is down, and for the same reason. The title says the
+    // workspace and stops there: being offline is the icon's to say, and a tab strip cannot say it twice.
+    const waiting = offline ? [] : sessions.filter((entry) => entry.attention);
     const name = workspaceName || "chamba";
     document.title = waiting.length > 0 ? `(${waiting.length}) ${name}` : name;
 
@@ -202,7 +238,9 @@ export function refreshBrowserTab() {
     // what the sessions are doing: an alert arriving next to one already up is the same state, and restarting the
     // cycle on every frame the server sends would make the mark stutter.
     paintFavicon();
-    if (!dotColor()) {
+    // The grey icon is one still frame: nothing in it moves, so nothing has to be redrawn, and a window sitting
+    // offline for a day costs exactly one paint.
+    if (offline || !dotColor()) {
         if (iconTimer) clearTimeout(iconTimer);
         iconTimer = null;
         iconFrame = 0;
@@ -211,6 +249,42 @@ export function refreshBrowserTab() {
     if (!iconTimer) iconTimer = setTimeout(tickIcon, ICON_TICK_MS);
 }
 
+// The socket went. The only thing the connection has to say, and everything that follows from it - the grace, the
+// flag, the title, the paint and the chime - is this module's, because all five are the same subject as the three
+// states above.
+//
+// Counted from the first close and not restarted by the ones after it, which is the whole difference between
+// three seconds and however long the reconnect loop takes to give up: every failed attempt closes a socket of its
+// own, and each of those closes arrives here. The curtain's own wait is guarded the same way, for the same
+// reason, and a tab that greys later than the curtain it sits above is a tab still showing a live green dot over
+// a page that has already said the container cannot be reached.
+export function socketWentDown() {
+    if (offline || offlineTimer) return;
+    offlineTimer = setTimeout(() => {
+        offlineTimer = null;
+        offline = true;
+        refreshBrowserTab();
+    }, OFFLINE_GRACE_MS);
+}
+
+// And came back.
+export function socketCameBack() {
+    if (offlineTimer) {
+        clearTimeout(offlineTimer);
+        offlineTimer = null;
+    }
+    if (!offline) return;
+    // Spend whatever came due while the tab was grey, before the flag drops. An alert still standing and already
+    // due at this moment can only have come due during the disconnect, because nothing else was left running to
+    // catch it: the chime arms one timer for the soonest alert alone, and the icon's clock, which is what catches
+    // the rest, is stopped while the icon is grey. Without this, the first tick after a reconnect would find one
+    // of those alerts unspent and sound it - a chime for a finish that happened while this window was away.
+    maybeChime();
+    // Then straight back to whatever the sessions say, without waiting for the first frame of the new socket.
+    offline = false;
+    refreshBrowserTab();
+}
+
 // --- A sound, for the session you are not at ---------------------------------------------------------------------------------------------
 //
 // The fourth thing the "an agent finished" alert does, and the only one that reaches a window behind an editor.
@@ -262,6 +336,9 @@ const CHIME_VOLUME = 0.35;
 // reload and covers every window of the same container without touching any other workspace. On by default: a
 // notification nobody discovers is not a notification, and the bell is right there to turn off.
 let soundOn = readSoundPref();
+// Every pane tool that makes a sound of its own reads this window's one preference, so it is said once here at
+// start and again on every toggle.
+toolsHearSound(soundOn);
 
 function readSoundPref() {
     try {
@@ -389,7 +466,10 @@ function maybeChime() {
     // Spent whether or not it is heard, so a muted window does not save up its chimes for whenever the bell is
     // unmuted - nothing new would have happened by then.
     for (const entry of due) chimed.add(entry.id);
-    if (!soundOn) return;
+    // A window that cannot reach its container is the second case of exactly that: calling you back to a session
+    // it can no longer see is worse than saying nothing, and a sound held for the reconnect would be reporting a
+    // state that has had a whole disconnect to move on.
+    if (offline || !soundOn) return;
     const now = Date.now();
     if (now - lastChimeAt < CHIME_GAP_MS) return;
     if (!claimChime()) return;
@@ -424,9 +504,9 @@ export function bellButton() {
     button.type = "button";
     button.classList.toggle("muted", !soundOn);
     button.title = soundOn
-        ? "Sound on - a chime when an agent finishes in a session you have not touched in a while. Click to mute."
-        : "Sound muted - click for a chime when an agent finishes in a session you have not touched in a while.";
-    button.setAttribute("aria-label", soundOn ? "Mute the finish sound" : "Unmute the finish sound");
+        ? "Sound on - a chime when an agent finishes in a session you have not touched in a while, and the bee on the Home tab. Click to mute."
+        : "Sound muted - click for a chime when an agent finishes in a session you have not touched in a while, and for the bee on the Home tab.";
+    button.setAttribute("aria-label", soundOn ? "Mute the interface" : "Unmute the interface");
     button.setAttribute("aria-pressed", String(soundOn));
     const svg = document.createElementNS(SVG_NS, "svg");
     svg.setAttribute("viewBox", "0 0 24 24");
@@ -464,6 +544,7 @@ function toggleSound() {
         // Not remembered past this page, but the toggle still works for as long as it is open.
     }
     renderBar();
+    toolsHearSound(soundOn);
     // The click landed on a button, which took the keyboard off the terminal.
     focusTerminal();
     // Turning it on plays it once, so the first time it happens behind your editor it is a sound you have already

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

@@ -0,0 +1,81 @@
+// anchored.js - a panel that hangs under the button that opened it, and closes the way every panel here does.
+//
+// The bar is rebuilt from scratch on every sessions frame and on the age tick, so a panel nested inside it
+// would close whenever any background session moved - and at the moment of use, since picking a workspace
+// colour broadcasts a frame straight back to the window that picked. Every panel in the bar therefore hangs
+// off the body, and is put back under its button whenever the bar is redrawn.
+//
+// Two panels work this way now, so the behaviour lives here rather than in either of them: where the panel
+// goes, the clamp to the window, dismissal on a click anywhere else, and Escape. What a panel is made of, and
+// what it does when something in it is clicked, stay its own business.
+
+import { focusTerminal } from "./terminal.js";
+
+/**
+ * A panel anchored under the element with `anchorId`. The id rather than the element itself, because the bar
+ * is rebuilt from scratch and the button under an open panel is a new element by the time it is looked at.
+ *
+ * Both callers run this at their own module load, which main.js otherwise forbids. It is allowed here because
+ * this reads nothing: it is a hoisted declaration that builds a closure and registers one listener, and the
+ * only module it touches is reached inside that listener, long after the page has finished loading.
+ */
+export function createAnchoredPanel(anchorId, onChange = () => {}) {
+    let panel = null;
+
+    function close() {
+        if (!panel) return;
+        panel.remove();
+        panel = null;
+        document.removeEventListener("pointerdown", onOutside, true);
+        // Every way out ends here - a click outside, Escape, the socket dropping, a choice made in the panel -
+        // so this is the one place that can tell the button the panel has gone.
+        onChange();
+    }
+
+    function onOutside(event) {
+        // The button itself is left alone: its own click handler toggles, and closing here first would reopen it.
+        if (panel?.contains(event.target) || event.target.closest?.(`#${anchorId}`)) return;
+        close();
+    }
+
+    // Put an open panel back under its button after the bar was rebuilt. A frame arrives whenever anything in
+    // the container moves, and a panel that closed itself every time one did would be unusable; a button that
+    // is gone takes it with it. Clamped to the window, since the bar can be scrolled far to the right.
+    function reposition() {
+        if (!panel) return;
+        const anchor = document.getElementById(anchorId);
+        if (!anchor) {
+            close();
+            return;
+        }
+        const box = anchor.getBoundingClientRect();
+        const width = panel.offsetWidth;
+        const left = Math.min(box.right - width, window.innerWidth - width - 8);
+        panel.style.top = `${Math.round(box.bottom + 6)}px`;
+        panel.style.left = `${Math.round(Math.max(8, left))}px`;
+    }
+
+    function open(element) {
+        close();
+        // Off the body, and never into the bar: renderBar() empties the bar on every frame.
+        document.body.append(element);
+        panel = element;
+        reposition();
+        // Capture, so a click on a tab closes this before that tab switches session.
+        document.addEventListener("pointerdown", onOutside, true);
+        onChange();
+    }
+
+    document.addEventListener("keydown", (event) => {
+        if (event.key !== "Escape" || !panel) return;
+        close();
+        focusTerminal();
+    });
+
+    return {
+        open,
+        close,
+        reposition,
+        isOpen: () => panel !== null,
+    };
+}

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

@@ -43,15 +43,49 @@ export function refreshComposer() {
     else input.placeholder = "Pick a session above to type in it.";
 }
 
+// The box the text is measured in: a second textarea, hidden and of no height, styled as the composer is.
+// The composer sits under the pane in one column, so a height it takes for one layout pass is a height the
+// tool frames lose for that pass, and a frame in its own process paints at that size before the pass is
+// corrected. Measuring here leaves the composer's height alone until the text needs another line.
+let mirror = null;
+function mirrorOf() {
+    if (mirror !== null) return mirror;
+    mirror = document.createElement("textarea");
+    mirror.id = "input-mirror";
+    mirror.tabIndex = -1;
+    mirror.setAttribute("aria-hidden", "true");
+    mirror.readOnly = true;
+    input.parentElement.appendChild(mirror);
+    return mirror;
+}
+
 export function autoGrow() {
-    input.style.height = "auto";
+    const box = getComputedStyle(input);
+    const ruler = mirrorOf();
+    // What decides where the text wraps and how tall a line is, copied from the composer as it stands now.
+    for (const name of [
+        "font",
+        "letterSpacing",
+        "lineHeight",
+        "padding",
+        "border",
+        "boxSizing",
+        "whiteSpace",
+        "wordBreak",
+        "overflowWrap",
+        "tabSize",
+    ]) {
+        ruler.style[name] = box[name];
+    }
+    ruler.style.width = `${input.clientWidth + Number.parseFloat(box.borderLeftWidth) + Number.parseFloat(box.borderRightWidth)}px`;
+    ruler.value = input.value;
     // The floor keeps the box off the button block behind it and the ceiling limits it to seven lines. Both are
     // read from the box itself rather than written here as well: the same two numbers in two files is how the
     // box comes to spring back to a height the stylesheet no longer says.
-    const box = getComputedStyle(input);
     const floor = Number.parseFloat(box.minHeight) || 0;
     const ceiling = Number.parseFloat(box.maxHeight) || Number.POSITIVE_INFINITY;
-    input.style.height = `${Math.min(Math.max(input.scrollHeight, floor), ceiling)}px`;
+    const wanted = `${Math.min(Math.max(ruler.scrollHeight, floor), ceiling)}px`;
+    if (input.style.height !== wanted) input.style.height = wanted;
 }
 input.addEventListener("input", () => {
     autoGrow();

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

@@ -4,11 +4,15 @@
 // the curtain is the one state that says "this window cannot do anything at all". They live together because
 // they are the same subject read from two ends: what the socket is doing, and what the user is told about it.
 
+import { socketCameBack, socketWentDown } from "./alerts.js";
 import { refreshComposer } from "./composer.js";
 import { curtain, curtainCard } from "./dom.js";
 import { onFrame } from "./frames.js";
+import { closeNewPop } from "./new-session.js";
 import { attachedSid, KEY_QUERY, sessions } from "./state.js";
+import { renderBar } from "./tabs.js";
 import { term } from "./terminal.js";
+import { closeColorPop } from "./workspace-color.js";
 
 // Whether the socket is up right now, and whether it has ever been up on this page. The second one is what
 // tells an opened page from a reconnected one, which the server treats differently.
@@ -194,6 +198,12 @@ export function noteSocketAlive() {
 // being abandoned must not schedule a second reconnect or overwrite the new one's state.
 function dropSocket() {
     if (!ws) return;
+    // The one close nobody else hears about. A socket retired while the page still believes it is up is the wake
+    // case: after a sleep the socket reads OPEN for minutes with nothing on the other end, the ping gets no
+    // answer, and this replaces it - with the handlers nulled, so no onclose ever fires for it. The browser tab
+    // is told here instead, because a tab left wearing a green dot for a container it cannot reach is exactly
+    // what this state is. Its own grace covers the ordinary case, where the replacement opens a moment later.
+    if (connected) socketWentDown();
     ws.onopen = null;
     ws.onmessage = null;
     ws.onclose = null;
@@ -222,6 +232,9 @@ export function connect() {
         clearCurtainTimer();
         hideCurtain();
         document.body.classList.remove("offline");
+        // The browser tab reads the socket too, and it keeps a grace of its own. Told that the socket moved and
+        // nothing more: what the tab does about it belongs to the tab.
+        socketCameBack();
         // Ask for the session this window was last looking at. The server decides whether it can have
         // it back, and picks something sensible when it cannot.
         // The last session this window drove: the server hands it back when no other window is on it.
@@ -246,6 +259,16 @@ export function connect() {
         // Immediately, ahead of any curtain: every control on the page is answered over this socket, so
         // while it is down they must stop taking clicks.
         document.body.classList.add("offline");
+        // And the browser tab, which is the only thing a hidden window can say any of this with. Said on every
+        // close, whichever curtain the diagnosis ends at: one rule covers a container that is down, a spent key,
+        // a container being stopped and a container that has gone.
+        socketWentDown();
+        // An anchored panel hangs off the body, so the bar's own offline rules do not reach it - and no frame
+        // is coming to redraw the bar, which leaves the age tick up to a minute away. Both are shut here.
+        closeNewPop();
+        closeColorPop();
+        // The bar with them, so its buttons are rebuilt as unavailable rather than waiting for that tick.
+        renderBar();
         refreshComposer();
         // The container was on its way down and the relay has now gone with it. That is the confirmation the
         // stopping curtain is waiting for, and there is nothing to diagnose: this close was the point.

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

@@ -24,11 +24,14 @@ export const pane = document.getElementById("pane");
 export const panebar = document.getElementById("panebar");
 export const toolTabs = document.getElementById("tool-tabs");
 export const paneFull = document.getElementById("pane-full");
+export const paneHalf = document.getElementById("pane-half");
 export const paneCollapse = document.getElementById("pane-collapse");
 export const spine = document.getElementById("spine");
 export const spineBadge = document.getElementById("spine-badge");
+export const toolHome = document.getElementById("tool-home");
 export const toolPages = document.getElementById("tool-pages");
 export const toolSpecs = document.getElementById("tool-specs");
+export const toolReviews = document.getElementById("tool-reviews");
 
 // The Pages tool. Every one of these is chrome the interface draws around a published page - the page itself
 // lives in a frame built by app/pane-frame.js and is never queried back.

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

@@ -13,11 +13,13 @@ import { stopDictation } from "./dictation.js";
 import { captureDraft, dropDraft, dropHistory, persistDrafts, pruneDrafts, pruneHistory, restoreDraft } from "./drafts.js";
 import { noteMsg } from "./note.js";
 import { applyPages, prunePanes, refreshPane } from "./pane.js";
-import { applySpecs, applySpecsDelivery } from "./specs-host.js";
-import { adoptSessionsFrame, attachedSid, defaultAgent, sessions, setAttachedSid } from "./state.js";
+import { applySessionShape, prunePaneShapes } from "./pane-shell.js";
+import { adoptSessionsFrame, attachedSid, defaultAgent, sessions, setAttachedSid, workspaceColorId } from "./state.js";
 import { applySnapshot, pruneStatuses, refreshStrip } from "./status-strip.js";
 import { noteArrivals, notePageArrivals, renderBar } from "./tabs.js";
 import { focusTerminal, scheduleRefresh, sendResize, term } from "./terminal.js";
+import { applyWorkspaceColor } from "./theme.js";
+import { toolHost, toolsMovedToSession } from "./tool-host.js";
 
 // What the terminal is holding: either a live session's screen (`shownSid`), or a message where a session used
 // to be (`shownMessage`). At most one of them is set. They are tracked because a session can end while this
@@ -28,6 +30,35 @@ const EXITED_SCREEN = "exited";
 let shownSid = null;
 let shownMessage = null;
 
+// Everything beside the terminal that belongs to the session rather than to the window: the pane, whichever
+// tool is open in it, and the strip above the composer. The pane's own shape goes first, because what a tool
+// lays out depends on how wide the pane now is and on which tool that is.
+//
+// The frame that follows the attached session hears about it here too, which matters most where this window
+// loses its session without an exit message of its own - the last session closes, or another window takes it
+// - because a tool still showing that session's work would offer to send where nobody is.
+function movedToSession() {
+    applySessionShape(attachedSid);
+    refreshPane();
+    refreshStrip();
+    toolsMovedToSession();
+}
+
+/**
+ * The tool one frame is about, and which of its two kinds it is, or null.
+ *
+ * A tool's frames are named after the tool - `specs` for a change under it, `specs:delivered` for the answer
+ * to a delivery - so a tool nobody registered has no frames and a name that is not a tool's is not one.
+ */
+function toolFrame(name) {
+    if (typeof name !== "string") return null;
+    const answered = ":delivered";
+    const id = name.endsWith(answered) ? name.slice(0, -answered.length) : name;
+    const host = toolHost(id);
+    if (!host) return null;
+    return { host, kind: id === name ? "change" : "delivered" };
+}
+
 export function onFrame(msg) {
     // Any frame at all proves the socket works, which is what a wake check is waiting to hear.
     noteSocketAlive();
@@ -60,17 +91,17 @@ export function onFrame(msg) {
         sendResize();
         if (switching) restoreDraft(msg.sid);
         refreshComposer();
-        // The pane and the strip belong to the session, so they move with the screen.
-        refreshPane();
-        refreshStrip();
+        movedToSession();
     } else if (msg.t === "pages") {
         applyPages(msg);
-    } else if (msg.t === "specs") {
-        // Every window gets these: a spec belongs to the repository rather than to a session.
-        applySpecs(msg);
-    } else if (msg.t === "specs:delivered") {
-        // What the server made of this window's own delivery, on its way back to the frame that asked.
-        applySpecsDelivery(msg);
+    } else if (toolFrame(msg.t)) {
+        // A frame about one of the pane's tools, named after that tool. The disk moved under its work, which
+        // every window gets - what a tool serves belongs to the repository rather than to a session, and two
+        // windows reading the same work both need to know - or the server answered a delivery this window
+        // asked for, which goes back to the frame that asked.
+        const { host, kind } = toolFrame(msg.t);
+        if (kind === "change") host.change(msg);
+        else host.delivered(msg);
     } else if (msg.t === "snapshot") {
         applySnapshot(msg);
     } else if (msg.t === "out") {
@@ -89,8 +120,7 @@ export function onFrame(msg) {
         setAttachedSid(null);
         takenCard(msg.sid);
         refreshComposer();
-        refreshPane();
-        refreshStrip();
+        movedToSession();
     } else if (msg.t === "exit") {
         if (msg.sid === attachedSid) {
             setAttachedSid(null);
@@ -103,8 +133,7 @@ export function onFrame(msg) {
         dropDraft(msg.sid);
         dropHistory(msg.sid);
         refreshComposer();
-        refreshPane();
-        refreshStrip();
+        movedToSession();
     } else if (msg.t === "stopping") {
         // Sent to every window, not just the one that asked: the container is about to take them all.
         stoppingCurtain();
@@ -123,6 +152,9 @@ export function onFrame(msg) {
 
 function applySessions(msg) {
     adoptSessionsFrame(msg);
+    // Before anything draws: the bar reads the session colours this works out, and the favicon below reads
+    // the workspace's own. An id this version does not know, and "" for nothing picked, both mean automatic.
+    applyWorkspaceColor(workspaceColorId);
     // Before the bar draws: its flash reads these timestamps, so an alert plays once instead of on every frame.
     noteArrivals();
     // The same, for a page published in a session this window is not looking at.
@@ -137,13 +169,15 @@ function applySessions(msg) {
     pruneHistory();
     refreshComposer();
     // Same for the pane: a session that left the bar takes this window's copy of its page list with it. The
-    // files themselves are untouched - a resumed conversation gets them back (FR-15).
+    // files themselves are untouched - a resumed conversation gets them back.
     const live = new Set(sessions.map((entry) => entry.id));
     prunePanes(live);
-    refreshPane();
+    // And for the pane itself: the shape a session was left in ends with that session, the way its draft does.
+    prunePaneShapes(live);
     // And for the strip: the numbers belong to a session, and that session is gone.
     pruneStatuses(live);
-    refreshStrip();
+    // Everything that outlived a session is gone, so what is left is drawn for the session this window holds.
+    movedToSession();
     // A session can vanish from under this window: closed here, closed from another window, or the agent exited.
     // Where the server had a free session to move this window to, that session's replay has already painted over
     // it. Where it did not - every remaining session is being driven elsewhere - this is the only thing that says

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

@@ -0,0 +1,16 @@
+// home-host.js - the Home tool on the page.
+//
+// The host around a tool's frame is `tool-host.js`, where every tool's is. What is here is which tool this
+// is: its name, which is what its routes and its messages are named after, the panel the pane gave it, and
+// the sentence its tab shows while it is opening.
+
+import { toolHome } from "./dom.js";
+import { HOME } from "./pane-shell.js";
+import { createToolHost } from "./tool-host.js";
+
+createToolHost({
+    id: HOME,
+    label: "Home",
+    panel: toolHome,
+    opening: "Reading the pulse of this repository.",
+});