chamba 0.7.0 → 0.8.0

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