chamba 0.6.1 → 0.8.0

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

@@ -1,58 +1,46 @@
-// 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,
+    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 +54,16 @@ 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. It belongs to the session, so it is asked of the pane each
+// time rather than held here: a switch changes the answer. The multiplier is what the pane stores, so a
+// session left at a size this version no longer offers falls back to the default instead of landing between
+// two steps.
+function sizeStep() {
+    const at = TEXT_SIZES.indexOf(storedPageSize());
+    return at === -1 ? DEFAULT_SIZE_STEP : at;
 }
 
-// --- The pane's own state ----------------------------------------------------------------------------------------------------------------
+// --- The tool's own state ----------------------------------------------------------------------------------------------------------------
 
 function paneFor(sid) {
     let entry = panes.get(sid);
@@ -122,14 +87,15 @@ 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);
+    // A pane someone put away comes back for a page, in the session the page was published in - which is
+    // the session this frame is about, since the list only reaches the tool for the one it is driving.
+    if (arrived !== null && isToolOpen(PAGES) && isPaneCollapsed()) setPaneCollapsed(false);
     else render();
 }
 
@@ -141,7 +107,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.
  */
@@ -207,7 +173,7 @@ function introState() {
     const wrap = document.createElement("div");
     wrap.className = "pane-intro";
     const title = document.createElement("h2");
-    title.textContent = "The web pane";
+    title.textContent = "Pages";
     const lede = document.createElement("p");
     lede.textContent = "Ask the agent for a page whenever the answer is longer or more structured than the terminal carries well:";
     const asks = document.createElement("ul");
@@ -257,79 +223,49 @@ 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));
+    const step = sizeStep();
+    const size = TEXT_SIZES[step];
+    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;
-    pageBigger.disabled = sizeStep === TEXT_SIZES.length - 1;
+    pageSmaller.disabled = step === 0;
+    pageBigger.disabled = step === TEXT_SIZES.length - 1;
 }
 
 function stepTextSize(by) {
-    const next = Math.min(Math.max(sizeStep + by, 0), TEXT_SIZES.length - 1);
-    if (next === sizeStep) return;
-    sizeStep = next;
+    const step = sizeStep();
+    const next = Math.min(Math.max(step + by, 0), TEXT_SIZES.length - 1);
+    if (next === step) return;
+    rememberPageSize(TEXT_SIZES[next]);
     applyTextSize();
-    rememberGeometry();
 }
 
 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() {
+    // The zoom is the session's, so it is applied wherever this tool draws rather than once at load: the
+    // first draw is already in a session's shape, and every switch draws again.
+    applyTextSize();
     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 open,
+    // because a pane that only appears once an agent has used it is one nobody knows to ask for. What the
+    // empty pane says is the tool's own intro; the tab's mark is the shell's, from what the tool says here.
     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;
+    // A page that arrived is a thing to look at, not a thing to answer, so the tab says so without a number.
+    noteTool(PAGES, { unread, empty: bare, counted: false });
 
     chips.replaceChildren(...pages.map((page) => chipFor(sid, page, page.id === entry?.selected)));
     const at = pages.findIndex((page) => page.id === entry?.selected);
@@ -359,80 +295,28 @@ function render() {
         pageDoc.append(emptyState(notice));
         return;
     }
+    // Fetching a page is what marks it read - the server owns that, and it answers with a fresh list. So a
+    // tool nobody is looking at must not fetch: the tab's own mark, set a few lines up, would be cleared by
+    // the frame that fetch provokes, before anyone had seen it. The document is drawn when the user opens
+    // the tool, by this same function.
+    if (!isToolOpen(PAGES)) return;
     show(sid, entry.selected);
     // A chip that scrolled out of the bar while the user was reading something else.
     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 (!isPaneCollapsed() && 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/reviews-host.js

@@ -0,0 +1,15 @@
+// reviews-host.js - the Code Reviews tool on the page.
+//
+// As the Specs host beside it: the tool's own name, its panel and its opening sentence, and the frame around
+// them is `tool-host.js`.
+
+import { toolReviews } from "./dom.js";
+import { REVIEWS } from "./pane-shell.js";
+import { createToolHost } from "./tool-host.js";
+
+createToolHost({
+    id: REVIEWS,
+    label: "Code Reviews",
+    panel: toolReviews,
+    opening: "Opening the reviews in this repository.",
+});

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

@@ -0,0 +1,16 @@
+// specs-host.js - the Specs 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 { toolSpecs } from "./dom.js";
+import { SPECS } from "./pane-shell.js";
+import { createToolHost } from "./tool-host.js";
+
+createToolHost({
+    id: SPECS,
+    label: "Specs",
+    panel: toolSpecs,
+    opening: "Opening the specs in this repository.",
+});

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

@@ -13,6 +13,10 @@ export let maxSessions = 8;
 export let defaultAgent = "the agent";
 export let agents = [];
 export let workspaceName = "";
+// The accent colour id the user picked for this workspace, or "" for none. What is stored, never what is on
+// the screen: the panel marks this, so "nothing picked" stays tellable from "picked the colour the port
+// would have given anyway".
+export let workspaceColorId = "";
 // Where "+ New session" starts an agent, relative to the workspace root ("" is the root itself). The server
 // owns it - it follows the directory chamba was last run in - and the picker opens on it.
 export let defaultCwd = "";
@@ -26,6 +30,7 @@ export function adoptSessionsFrame(msg) {
     defaultAgent = msg.agent || defaultAgent;
     if (Array.isArray(msg.agents)) agents = msg.agents;
     workspaceName = msg.workspace || "";
+    workspaceColorId = typeof msg.color === "string" ? msg.color : "";
     defaultCwd = msg.defaultCwd ?? "";
 }
 

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

@@ -18,6 +18,7 @@ import { repositionNewPop, toggleNewPop } from "./new-session.js";
 import { agents, attachedSid, defaultAgent, defaultCwd, maxSessions, sessions, workspaceName } from "./state.js";
 import { focusTerminal, term } from "./terminal.js";
 import { colorFor } from "./theme.js";
+import { repositionColorPop, workspaceColorButton } from "./workspace-color.js";
 
 // The session tab being renamed right now (its id), and the text in its editor. Kept in module state so a
 // bar re-render (an incoming server frame, or the 60s age tick) rebuilds the editor without losing what
@@ -513,11 +514,14 @@ export function renderBar() {
         ws.textContent = workspaceName;
         right.append(ws);
     }
-    right.append(bellButton(), stopButton());
+    // The colour first: it is about this window's identity rather than about what the window does, so it sits
+    // next to the name it belongs with, on the far side of the bell from the button that ends everything.
+    right.append(workspaceColorButton(), bellButton(), stopButton());
     tabbar.append(right);
 
-    // The panel hangs off the body, so it survives this rebuild - but the button under it just moved.
+    // Both panels hang off the body, so they survive this rebuild - but the buttons under them just moved.
     repositionNewPop();
+    repositionColorPop();
 
     // Keep focus in the rename editor across re-renders. The first render after a double-click selects the
     // whole label so it can be typed over; a later render (an incoming frame) only restores the caret.

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();

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

@@ -1,25 +1,23 @@
-// theme.js - one palette, used for two different jobs.
+// theme.js - what colour this workspace is wearing right now, and what colour its sessions get.
 //
-// The workspace takes one slot of it and keeps it: the composer border, the active tab's edge, the buttons
-// and the frame around the tab icon are all that one colour, so a window is recognisable across a screen full
-// of them before a single word is read. The slot comes from the published port, which chamba assigns per workspace,
-// so two containers open side by side are almost never the same colour and nothing has to be configured.
+// The workspace wears one colour: the composer border, the active tab's edge, the buttons and the frame around
+// the tab icon are all that one colour, so a window is recognisable across a screen full of them before a
+// single word is read. The user picks it from the bar, and until someone does it comes from the published
+// port, which chamba assigns per workspace, so two containers open side by side are almost never alike.
 //
 // The sessions inside that window then rotate through the slots the workspace did not take. That is what
 // makes a tab's own dot mean "this session" rather than "this workspace", and it is why a dot can never come
 // out the same colour as the window it lives in.
+//
+// The colour moves while the page is open, so nothing here is a constant for anyone else to import: it is read
+// through workspaceColor() and set through applyWorkspaceColor(). A module that took a copy at load would keep
+// drawing the colour the workspace had when it started. The palette and the rules over it are in palette.js,
+// which touches no globals and is where the tests check them.
+//
+// The stored colour lives in the container and arrives over the socket, which connects after the first paint.
+// So this module also keeps the browser's own copy of the last colour it was told, and paints that first.
 
-// Cyberpunk neons on a near-black bar, spaced around the wheel and deliberately free of yellow and orange -
-// those read as a warning here, and the bar has enough to say without one. Keep the length one longer than
-// PALETTE_SIZE in sessions.js (a test pins it): the workspace eats one slot, sessions rotate the rest.
-const PALETTE = [
-    "#2fe58a", // spring green
-    "#1fe0cf", // turquoise
-    "#f24bff", // magenta
-    "#b45cff", // neon violet
-    "#29b6ff", // azure
-    "#ff2e88", // rose
-];
+import { automaticId, hexFor, sessionColors } from "./palette.js";
 
 // A stable number for this window when there is no port to read (a proxy, or the default 80/443). Not a
 // hash worth defending - it only has to be the same on every reload of the same address.
@@ -29,18 +27,68 @@ function hostSeed() {
     return seed;
 }
 
-// The workspace's slot in the palette. Ports are handed out lowest-free-first per workspace, so neighbours
-// land on different colours.
-const WORKSPACE_SLOT = (Number(location.port) || hostSeed()) % PALETTE.length;
-export const WORKSPACE_COLOR = PALETTE[WORKSPACE_SLOT];
-// Every slot except the workspace's own, in palette order. A session index maps into this, so "never the
-// workspace colour" is a property of the list rather than a rule someone has to remember.
-const SESSION_COLORS = PALETTE.filter((_, slot) => slot !== WORKSPACE_SLOT);
+// What this workspace wears when nothing is stored for it.
+const AUTOMATIC_ID = automaticId(Number(location.port) || hostSeed());
+
+// The last colour this browser was told, kept so the next load paints it before the socket answers. One
+// localStorage entry, named the way the interface names its own (webterm-sound, webterm-pane).
+//
+// A cache and never the truth. The file in the workspace's state directory decides, and the first sessions
+// frame replaces whatever is held here. It exists for one thing: without it every load would open on the
+// colour the port gives and then jump to the stored one, which is the flicker this work was asked to settle.
+// localStorage is held per origin and the origin names the port, so a workspace whose published port moves
+// starts again with nothing cached - it paints the new automatic colour once, then settles on the stored one.
+const COLOR_KEY = "webterm-color";
+
+function cachedColorId() {
+    try {
+        return localStorage.getItem(COLOR_KEY) || "";
+    } catch {
+        return "";
+    }
+}
+
+// Written whenever a frame carries a colour, and removed when one carries "". A browser that refuses storage
+// still works: it just opens on the automatic colour every time and corrects itself when the socket answers.
+//
+// Only on a change. A sessions frame goes out on every working-or-idle transition the registry notices, which
+// is many a minute under a busy agent, and this is a synchronous write of a value that almost never moves.
+function rememberColorId(id) {
+    try {
+        if (id === cachedColorId()) return;
+        if (id === "") localStorage.removeItem(COLOR_KEY);
+        else localStorage.setItem(COLOR_KEY, id);
+    } catch {
+        // Nothing to do about it, and nothing worth saying to the user.
+    }
+}
 
-// Handed to the stylesheet once, before anything is drawn: everything that carries the window's identity
-// reads it from there, so there is one line in the page that decides what colour this workspace is.
-document.documentElement.style.setProperty("--ws", WORKSPACE_COLOR);
+let workspaceHex = "";
+let sessionHexes = [];
+
+// Handed to the stylesheet: everything that carries the window's identity reads --ws from there, so one line
+// in the page decides what colour this workspace is. Called once below, before anything is drawn, and again
+// whenever the stored colour changes.
+export function applyWorkspaceColor(id) {
+    // Cached here rather than in the frame router, because the two callers are the frame that carries a
+    // colour and the load below that reads the cache back - so caching what is applied is caching what the
+    // server last said, and the load's own call rewrites the value it just read.
+    rememberColorId(id);
+    // The empty string asks for automatic, and an id this version does not know means the same thing.
+    const chosen = hexFor(id) ? id : AUTOMATIC_ID;
+    workspaceHex = hexFor(chosen);
+    sessionHexes = sessionColors(chosen, AUTOMATIC_ID);
+    document.documentElement.style.setProperty("--ws", workspaceHex);
+}
+
+/** The colour the workspace is wearing, read fresh by everything that draws it. */
+export function workspaceColor() {
+    return workspaceHex;
+}
 
 export function colorFor(entry) {
-    return SESSION_COLORS[(entry.colorIndex ?? 0) % SESSION_COLORS.length];
+    return sessionHexes[(entry.colorIndex ?? 0) % sessionHexes.length];
 }
+
+// Before anything is drawn, and before the socket has answered: what this browser was told last time.
+applyWorkspaceColor(cachedColorId());