chamba 0.7.0 → 0.8.0

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

@@ -0,0 +1,302 @@
+// tool-host.js - a pane tool's client, in a frame of its own.
+//
+// A 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 that tool's own reading at worst. This module is the host around such a 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 it. The frame gets a tool-scoped key that opens that tool's data routes
+// and a path prefix that opens the files it serves, 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.
+//
+// One host per tool, made by that tool's own module beside this file, which names the tool and nothing more.
+// Everything here is the same for every tool, so a third one is a panel and three lines.
+
+import { sendFrame } from "./connection.js";
+import { noteTool, registerTool, rememberPaneTheme, storedPaneTheme } from "./pane-shell.js";
+import { attachedSid, KEY_HEADER, WEB_KEY } from "./state.js";
+
+// 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;
+
+// What the shell and a frame call each other's messages. Namespaced by the tool, 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 = "credentials";
+const CHANGE = "change";
+const OPEN = "open";
+const DELIVER = "deliver";
+const WAITING = "waiting";
+const DELIVERED = "delivered";
+const SESSION = "session";
+const THEME = "theme";
+
+// id -> the host of that tool, so a frame from the server reaches the one it is about.
+const hosts = new Map();
+
+/** The host of one tool, or undefined. */
+export function toolHost(id) {
+    return hosts.get(id);
+}
+
+/** Tell every tool which session this window is now driving. */
+export function toolsMovedToSession() {
+    for (const host of hosts.values()) host.session();
+}
+
+/**
+ * Put one tool on the page.
+ *
+ * `id` is the tool's own name, which is both the prefix of its routes and the name of its messages - the
+ * server derives the same paths from the same word (see `tools/paths.js`). `panel` is the element the pane
+ * gave this tool, and `opening` is the one sentence shown while its credentials are being fetched.
+ */
+export function createToolHost({ id, label, panel, opening }) {
+    // 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/${id}/index.html`;
+    const KEYS_URL = `/${id}/keys`;
+    const named = (what) => `${id}:${what}`;
+
+    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, and whether the tool has anything to show at
+    // all. Kept here rather than in the frame, because both have to hold while another tool is open and the
+    // frame is not being drawn. A tool that has said nothing yet has something to show: a panel drawn once
+    // and then declared empty is a pane that moves under a reader who did nothing.
+    let waiting = 0;
+    let anything = true;
+
+    /** Fetch the frame's credentials. The shell holds the master key; this is the only route it opens for this tool. */
+    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 ${label} 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", label);
+        next.addEventListener("load", () => onLoad(next));
+        next.src = FRAME_SRC;
+        frame = next;
+        handed = false;
+        panel.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: named(HANDOVER), key: credentials.key, raw: credentials.raw }, "*");
+            // The session this window is on, right behind the handover. The frame usually finishes loading
+            // after the first session has attached, so without this a window that never switches would never
+            // hear which session it is beside - and a tool keeps its view per session.
+            sendSession(loaded);
+            return;
+        }
+        if (rebuilds >= MAX_REBUILDS) {
+            frame = null;
+            failure = `The ${label} 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 = label;
+        const lede = document.createElement("p");
+        lede.textContent = line;
+        wrap.append(title, lede);
+        panel.replaceChildren(wrap);
+    }
+
+    function render() {
+        // What the tool last said about itself, which holds while another tool is open: what is waiting for
+        // the user in it, and whether it has anything to show.
+        noteTool(id, { unread: waiting, empty: !anything });
+        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);
+            fetchCredentials();
+            return;
+        }
+        build();
+    }
+
+    /**
+     * Tell one frame which session this window is driving, and how that session reads. `null` says there is none.
+     *
+     * The theme rides with the session because it belongs to it: the frame has an opaque origin and no storage
+     * of its own, so what it was set to last is the pane's to keep and the pane's to hand back.
+     */
+    function sendSession(target) {
+        const sid = attachedSid ?? null;
+        // Both fields say the same session or neither does: the pane is drawn in the session it opened with
+        // before the first frame names one, and handing the frame that session's palette beside "there is no
+        // session" would have it read in a theme it was never told the reason for.
+        target?.contentWindow?.postMessage({ t: named(SESSION), sid, theme: sid === null ? null : storedPaneTheme() }, "*");
+    }
+
+    /**
+     * Whether a message is this 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 tool's 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 !== named(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, and whether it holds anything. Both are the tool's own; the mark
+    // they put on the tab is the shell's - which is what makes something awaiting an answer visible from any
+    // other tool in the pane. Only the word "no" makes a tool empty, so a message from an older client that
+    // says nothing about it leaves the tab as it was.
+    window.addEventListener("message", (event) => {
+        const message = event.data;
+        if (!message || typeof message !== "object" || message.t !== named(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;
+        anything = message.anything !== false;
+        noteTool(id, { unread: waiting, empty: !anything });
+    });
+
+    // The tool asking for the other palette. It has nowhere to keep the answer, so the pane keeps it with the
+    // rest of that session's shape and hands it straight back down the session path - which is the one way the
+    // frame ever learns its theme, so the store is what the tool is reading rather than a copy of it.
+    window.addEventListener("message", (event) => {
+        const message = event.data;
+        if (!message || typeof message !== "object" || message.t !== named(THEME)) return;
+        if (!fromTool(event, message)) return;
+        rememberPaneTheme(message.theme);
+        sendSession(frame);
+    });
+
+    // 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 which tool it is from, 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 !== named(DELIVER)) return;
+        if (!fromTool(event, message)) return;
+        sendFrame({
+            t: "tool:deliver",
+            tool: id,
+            event: String(message.event ?? ""),
+            detail: String(message.detail ?? ""),
+            path: String(message.path ?? ""),
+            create: message.create === true,
+        });
+    });
+
+    const host = {
+        /** The disk moved under this tool's work. Passed straight in: the frame decides what is worth re-reading. */
+        change(msg) {
+            if (frame === null || !handed) return;
+            frame.contentWindow?.postMessage({ t: named(CHANGE), change: msg.change }, "*");
+        },
+
+        /**
+         * The window moved to another session, or off the one it had.
+         *
+         * A tool keeps one view per session - what is open, where the reader is, and what they are holding -
+         * so a switch has to reach it. It rides the same path as every other message to the frame, and it
+         * names the session this window is on rather than one the frame may choose.
+         */
+        session() {
+            if (frame === null || !handed) return;
+            sendSession(frame);
+        },
+
+        /** What the server made of the last delivery, passed back to the frame that asked for it. */
+        delivered(msg) {
+            if (frame === null || !handed) return;
+            frame.contentWindow?.postMessage({ t: named(DELIVERED), ok: msg.ok === true, error: msg.error ?? "" }, "*");
+        },
+    };
+
+    hosts.set(id, host);
+    registerTool(id, 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();
+    return host;
+}

package/templates/webterm/public/app/workspace-color.js

@@ -0,0 +1,192 @@
+// workspace-color.js - the control in the bar that says what colour this workspace wears, and changes it.
+//
+// The colour is the one thing a window says about itself from across a screen full of windows, and until now
+// it was worked out from the published port with nothing the user could do about it. The control is a palette
+// glyph beside the bell, drawn and coloured exactly as the bell is, so the row stays a row.
+//
+// Everything is one click. Picking a colour applies it at once, with nothing to confirm, because there is
+// nothing to get wrong - the panel offers eleven colours and a way back to automatic, and a colour that turns
+// out to be the wrong one is another click. The mark stays on what is *stored*, not on what is on the screen,
+// so "nothing picked" is still tellable from "picked the colour the port would have given anyway".
+//
+// The panel hangs off the body through anchored.js. It is not a nicety: renderBar() empties the bar on every
+// frame, and picking a colour broadcasts a frame back to this very window, so a panel inside the bar would
+// close itself the moment it was used.
+
+import { createAnchoredPanel } from "./anchored.js";
+import { connected, sendFrame } from "./connection.js";
+import { SVG_NS } from "./dom.js";
+import { hexFor, PALETTE } from "./palette.js";
+import { workspaceColorId } from "./state.js";
+
+const BUTTON_ID = "wscolorbtn";
+
+// markButton runs on every open and every close, so the button says what the panel is doing however the
+// panel got there - a choice made in it, a click outside, Escape, or the socket dropping.
+const panel = createAnchoredPanel(BUTTON_ID, () => markButton());
+
+// Put the open panel back under its button after the bar was rebuilt, and take it away with a button that has
+// gone. Called from renderBar(), beside the new-session panel's own.
+export function repositionColorPop() {
+    panel.reposition();
+}
+
+// The tick on the chosen cell. Drawn rather than styled so it sits on any of the eleven: the stroke is the
+// interface's own near-black, which every colour in the palette carries at 3:1 or better.
+function tick() {
+    const svg = document.createElementNS(SVG_NS, "svg");
+    svg.setAttribute("viewBox", "0 0 10 8");
+    svg.setAttribute("width", "10");
+    svg.setAttribute("height", "8");
+    svg.setAttribute("aria-hidden", "true");
+    const path = document.createElementNS(SVG_NS, "path");
+    path.setAttribute("d", "M1 4.2 3.6 6.8 9 1.2");
+    path.setAttribute("fill", "none");
+    path.setAttribute("stroke", "#0d1117");
+    path.setAttribute("stroke-width", "2");
+    path.setAttribute("stroke-linecap", "round");
+    path.setAttribute("stroke-linejoin", "round");
+    svg.append(path);
+    return svg;
+}
+
+// One cell of the grid. `id` is "" for the automatic cell, which is one of the choices rather than a button
+// under them: it is what the workspace goes back to, so it belongs in the same grid as what it replaces.
+function cell(id, hex, label, stored) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = id === "" ? "wscell auto" : "wscell";
+    button.title = label;
+    // Plain buttons that say whether they are the one in force. Not role="radio": that role promises arrow-key
+    // navigation with a roving tabindex, and describing behaviour the code does not have is worse than saying
+    // less. Every cell stays in the tab order, which is what actually happens.
+    const chosen = id === stored;
+    button.setAttribute("aria-pressed", String(chosen));
+    button.setAttribute("aria-label", label);
+    if (id === "") button.textContent = "A";
+    else button.style.background = hex;
+    if (chosen) {
+        button.classList.add("chosen");
+        // The ring carries the mark on every cell. The tick goes on the colours alone: the automatic cell
+        // already holds its "A", and a tick beside it would sit off centre and be drawn in a near-black that
+        // is all but invisible on that cell's own dark stripes.
+        if (id !== "") button.append(tick());
+    }
+    button.addEventListener("click", () => {
+        panel.close();
+        // Sent, never held: the server decides, and every window is told on the frame that comes back. A pick
+        // kept to send later would be undone by the next sessions frame anyway (FR-17).
+        sendFrame({ t: "color", color: id });
+    });
+    return button;
+}
+
+function popLabel(text) {
+    const label = document.createElement("span");
+    label.className = "poplabel";
+    label.textContent = text;
+    return label;
+}
+
+function openPanel() {
+    // What is *stored*, and an id this version does not know counts as nothing stored - the same reading
+    // theme.js gives it when it paints. Without that, a colour dropped from the palette in a later version
+    // would leave the panel with no mark at all: no cell matches the id, and the automatic cell would not
+    // either, though automatic is exactly what the window is showing.
+    const stored = hexFor(workspaceColorId) ? workspaceColorId : "";
+    const pop = document.createElement("div");
+    pop.id = "wscolorpop";
+    pop.setAttribute("role", "dialog");
+    pop.setAttribute("aria-label", "Workspace colour");
+
+    const grid = document.createElement("div");
+    grid.className = "wsgrid";
+    grid.setAttribute("role", "group");
+    grid.setAttribute("aria-label", "Workspace colour");
+    for (const colour of PALETTE) grid.append(cell(colour.id, colour.hex, colour.id, stored));
+    // Automatic last, so the eleven read as one set and the way out sits at the end of it.
+    grid.append(cell("", "", "Automatic", stored));
+
+    const foot = document.createElement("p");
+    foot.className = "wscolorfoot";
+    foot.textContent = "Automatic goes back to the colour this workspace works out for itself.";
+
+    pop.append(popLabel("Workspace colour"), grid, foot);
+    panel.open(pop);
+}
+
+function togglePanel() {
+    if (panel.isOpen()) panel.close();
+    else openPanel();
+}
+
+// The open state, said on the button as it happens rather than left to the next bar rebuild, which may be a
+// frame away or the whole sixty-second age tick away: a screen reader would otherwise be told "collapsed" over
+// an open panel. The bar is rebuilt from scratch on every frame, so this looks the button up rather than
+// holding one, and does nothing when the bar has not drawn yet.
+function markButton() {
+    const button = document.getElementById(BUTTON_ID);
+    if (!button) return;
+    button.setAttribute("aria-expanded", String(panel.isOpen()));
+    button.classList.toggle("open", panel.isOpen());
+}
+
+// Called when the socket drops, so the panel goes with it. renderBar() rebuilds the button disabled, but a
+// panel that is already open hangs off the body, where the bar's own offline rules cannot reach it.
+export function closeColorPop() {
+    panel.close();
+}
+
+// A palette: a circle with a bite out of it for the thumb hole, and three wells of paint. Drawn in the idiom
+// the bell and the power button use - a 24-unit grid at 14px, no fill, currentColor at stroke-width 2 - so
+// the three read as one row of controls. The wells are filled rather than stroked, because a ring of one
+// unit closes up at this size.
+function paletteGlyph() {
+    const svg = document.createElementNS(SVG_NS, "svg");
+    svg.setAttribute("viewBox", "0 0 24 24");
+    svg.setAttribute("width", "14");
+    svg.setAttribute("height", "14");
+    svg.setAttribute("fill", "none");
+    svg.setAttribute("stroke", "currentColor");
+    svg.setAttribute("stroke-width", "2");
+    svg.setAttribute("stroke-linecap", "round");
+    svg.setAttribute("stroke-linejoin", "round");
+    const body = document.createElementNS(SVG_NS, "path");
+    body.setAttribute("d", "M12 22a10 10 0 1 1 10-10c0 2.2-1.8 4-4 4h-1.6a2.4 2.4 0 0 0-1.7 4.1A2 2 0 0 1 12 22z");
+    svg.append(body);
+    for (const [cx, cy] of [
+        [7.5, 12.5],
+        [9.5, 8],
+        [14.5, 7.5],
+    ]) {
+        const well = document.createElementNS(SVG_NS, "circle");
+        well.setAttribute("cx", String(cx));
+        well.setAttribute("cy", String(cy));
+        well.setAttribute("r", "1");
+        well.setAttribute("fill", "currentColor");
+        well.setAttribute("stroke", "none");
+        svg.append(well);
+    }
+    return svg;
+}
+
+// The control that opens the palette. It carries no colour of its own: the bar already says which colour is
+// in force, on the edge of the active tab, and a filled swatch in a row of glyphs reads as a thing that
+// wandered in rather than as one of the row.
+export function workspaceColorButton() {
+    const button = document.createElement("button");
+    button.id = BUTTON_ID;
+    button.type = "button";
+    // Nothing to open, and nothing to send, while this window is not talking to the server: a pick that could
+    // not be sent would be undone by the next frame, which is worse than not offering it. The socket dropping
+    // is what closes an open panel, in connection.js - by the time this runs the panel is already gone.
+    button.disabled = !connected;
+    button.title = "The colour this workspace wears";
+    button.setAttribute("aria-label", "Change the workspace colour");
+    button.setAttribute("aria-haspopup", "dialog");
+    button.setAttribute("aria-expanded", String(panel.isOpen()));
+    button.classList.toggle("open", panel.isOpen());
+    button.append(paletteGlyph());
+    button.addEventListener("click", togglePanel);
+    return button;
+}

package/templates/webterm/public/index.html

@@ -21,7 +21,7 @@
     <div id="middle">
         <div id="termwrap">
             <main id="term"></main>
-            <!-- Take over / end session / limit reached, scoped to the terminal area. -->
+            <!-- Take over / end session / limit reached, fixed to the viewport so the card is in the middle of the screen. -->
             <div id="overlay"><div id="card" class="card"></div></div>
             <!-- Transient status ("copied 3 lines", upload and dictation errors), floating so it shifts nothing. -->
             <span id="note"></span>
@@ -45,6 +45,14 @@
                             <path d="M13 8l-4 4 4 4" />
                         </svg>
                     </button>
+                    <!-- Two equal panels, split down the middle: the pane at half the window, which is the
+                         width it opens at. -->
+                    <button type="button" id="pane-half" class="pane-nav" title="Half the window" aria-label="Half the window">
+                        <svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                            <rect x="3.5" y="5" width="17" height="14" rx="2" />
+                            <path d="M12 5v14" />
+                        </svg>
+                    </button>
                     <!-- An arrow into the pane's own edge: put it away, that way. Inline because this bar is
                          static chrome, unlike the session bar's icons, which are drawn per frame. -->
                     <button type="button" id="pane-collapse" class="pane-nav" title="Collapse the pane" aria-label="Collapse the pane">
@@ -79,8 +87,14 @@
             <!-- Specs: the spec workspace, in a frame of its own. -->
             <div id="tool-specs" class="tool-panel" hidden></div>
 
-            <button type="button" id="spine" title="Open the web pane" aria-label="Open the web pane">
-                <span class="label"><span id="spine-badge" hidden></span> Web pane</span>
+            <!-- Code Reviews: the reviews of this repository, in a frame of its own. -->
+            <div id="tool-reviews" class="tool-panel" hidden></div>
+
+            <!-- The label names what the pane holds now that it holds more than pages: one tab per app.
+                 The `webpane` helper, the framed line a page's feedback arrives on, and the skill are all
+                 named for the pane itself and are unchanged - they are an agent's interface, not a label. -->
+            <button type="button" id="spine" title="Open the apps pane" aria-label="Open the apps pane">
+                <span class="label"><span id="spine-badge" hidden></span> Apps pane</span>
             </button>
         </aside>
     </div>