chamba 0.7.0 → 0.9.0

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

@@ -31,10 +31,10 @@ import { dropPage, fetchPage, renderPage, submitFeedback } from "./pane-frame.js
 import {
     flashPane,
     isPaneCollapsed,
-    isPaneShut,
     isToolOpen,
     noteTool,
     PAGES,
+    pulseTool,
     registerTool,
     rememberPageSize,
     setPaneCollapsed,
@@ -55,11 +55,14 @@ 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();
 
-// 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;
+// 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 tool's own state ----------------------------------------------------------------------------------------------------------------
 
@@ -89,11 +92,13 @@ export function applyPages(msg) {
     // saying-so is held back while another tool has the pane.
     if (arrived !== null) {
         select(msg.sid, arrived.id, { user: false });
+        // The pane switches tools for nobody. With Pages open the pane's own edge says the page is here;
+        // with another tool open the Pages tab says it, and the tool the user is working in is left alone.
         if (isToolOpen(PAGES)) flashPane();
+        else pulseTool(PAGES);
     }
-    // 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.
+    // 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();
 }
@@ -172,7 +177,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");
@@ -230,38 +235,43 @@ function chipFor(sid, page, selected) {
 // 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];
+    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();
-    rememberPageSize(TEXT_SIZES[sizeStep]);
 }
 
 pageSmaller.addEventListener("click", () => stepTextSize(-1));
 pageBigger.addEventListener("click", () => stepTextSize(1));
-applyTextSize();
 
 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 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.
+    // 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;
-    noteTool(PAGES, { unread, empty: bare });
+    // How many pages nobody has opened, the way Specs counts its open asks. Three waiting is a different day
+    // from one, and the pages already read are not a number anyone acts on, so the tab counts the unopened
+    // ones alone and never the whole list.
+    noteTool(PAGES, { unread, empty: bare, counted: true });
 
     chips.replaceChildren(...pages.map((page) => chipFor(sid, page, page.id === entry?.selected)));
     const at = pages.findIndex((page) => page.id === entry?.selected);
@@ -291,6 +301,11 @@ 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" });
@@ -300,7 +315,7 @@ function render() {
 registerTool(PAGES, render);
 
 setInterval(() => {
-    if (!isPaneShut() && isToolOpen(PAGES)) render();
+    if (!isPaneCollapsed() && isToolOpen(PAGES)) render();
 }, AGE_TICK_MS);
 
 // A bar that fits at one width may not at another, and the arrows only exist when it does not.

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

@@ -0,0 +1,19 @@
+// 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`.
+//
+// "Reviews" and not "Code Reviews", because this word is what the user reads on the tab and in the panel
+// while the tool opens, and four tabs have to fit at the width the pane reopens at. The tool's own name is
+// Code Reviews everywhere else, the server table included, so every refusal still names it in full.
+
+import { toolReviews } from "./dom.js";
+import { REVIEWS } from "./pane-shell.js";
+import { createToolHost } from "./tool-host.js";
+
+createToolHost({
+    id: REVIEWS,
+    label: "Reviews",
+    panel: toolReviews,
+    opening: "Opening the reviews in this repository.",
+});

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

@@ -1,222 +1,16 @@
-// specs-host.js - the Specs tool: the spec workspace, in a frame of its own.
+// specs-host.js - the Specs tool on the page.
 //
-// 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.
+// 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 { 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 });
+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.",
 });
-
-// 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

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