chamba 0.6.1 → 0.7.0

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

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

@@ -27,34 +27,58 @@
             <span id="note"></span>
         </div>
 
-        <!-- The web pane, rendered by app/pane.js: the pages this session's agent published, with the chips
-             bar and the counter drawn out here by the interface, and the page itself inside a sandboxed
-             frame. Both it and its drag handle are hidden until the session has a page. -->
+        <!-- The web pane, rendered by app/pane-shell.js: the tool tabs and the two width controls are the
+             pane's own chrome, and one panel per tool sits under them - Pages (app/pane.js) and Specs
+             (app/specs-host.js). Both the pane and its drag handle are hidden until there is something in it. -->
         <div id="grip" hidden></div>
         <aside id="pane" hidden>
-            <div id="pagebar">
-                <button type="button" id="pane-prev" class="pane-nav" title="Older pages" aria-label="Older pages" hidden>&#8249;</button>
-                <div id="chips"></div>
-                <button type="button" id="pane-next" class="pane-nav" title="Newer pages" aria-label="Newer pages" hidden>&#8250;</button>
-                <span id="page-count"></span>
-                <!-- How big the shown page is drawn, for this browser. Interface furniture: no agent knows it
-                     exists, and a page written before it scales like any other. -->
-                <span id="page-size">
-                    <button type="button" id="page-smaller" title="Smaller text" aria-label="Smaller text">&#8722;</button>
-                    <span id="page-size-val"></span>
-                    <button type="button" id="page-bigger" title="Larger text" aria-label="Larger text">+</button>
+            <!-- The pane's own bar: which tool is open, and how wide the pane is. Nothing in it belongs to a
+                 tool, so a tool can never move the pane or say which tool the user is looking at. -->
+            <div id="panebar">
+                <div id="tool-tabs"></div>
+                <span id="pane-ctl">
+                    <!-- The pane's edge to the far wall, and back again. -->
+                    <button type="button" id="pane-full" class="pane-nav" title="Full width" aria-label="Full width">
+                        <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">
+                            <path d="M4 5v14" />
+                            <path d="M20 12H9" />
+                            <path d="M13 8l-4 4 4 4" />
+                        </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">
+                        <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">
+                            <path d="M4 12h11" />
+                            <path d="M11 8l4 4-4 4" />
+                            <path d="M20 5v14" />
+                        </svg>
+                    </button>
                 </span>
-                <!-- 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 web pane" aria-label="Collapse the web pane">
-                    <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">
-                        <path d="M4 12h11" />
-                        <path d="M11 8l4 4-4 4" />
-                        <path d="M20 5v14" />
-                    </svg>
-                </button>
             </div>
-            <div id="page-doc"></div>
+
+            <!-- Pages: the pages this session's agent published, with the chips bar and the counter drawn out
+                 here by the interface, and the page itself inside a sandboxed frame. -->
+            <div id="tool-pages" class="tool-panel">
+                <div id="pagebar">
+                    <button type="button" id="pane-prev" class="pane-nav" title="Older pages" aria-label="Older pages" hidden>&#8249;</button>
+                    <div id="chips"></div>
+                    <button type="button" id="pane-next" class="pane-nav" title="Newer pages" aria-label="Newer pages" hidden>&#8250;</button>
+                    <span id="page-count"></span>
+                    <!-- How big the shown page is drawn, for this browser. Interface furniture: no agent knows
+                         it exists, and a page written before it scales like any other. -->
+                    <span id="page-size">
+                        <button type="button" id="page-smaller" title="Smaller text" aria-label="Smaller text">&#8722;</button>
+                        <span id="page-size-val"></span>
+                        <button type="button" id="page-bigger" title="Larger text" aria-label="Larger text">+</button>
+                    </span>
+                </div>
+                <div id="page-doc"></div>
+            </div>
+
+            <!-- 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>
             </button>
@@ -80,10 +104,10 @@
                 <!-- The one button that sends without being written: it types a fixed sentence into the
                      session, through the same paste path as anything else, and leaves the box alone. Its
                      place in the markup is what puts it above Send: the block fills row by row. -->
-                <button type="button" id="ask-page" class="icon-btn" title="Put the last answer in the web pane"
-                        aria-label="Put the last answer in the web pane">
+                <button type="button" id="ask-page" class="icon-btn" title="Put the last answer on a page"
+                        aria-label="Put the last answer on a page">
                     <svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round">
-                        <title>Put the last answer in the web pane</title>
+                        <title>Put the last answer on a page</title>
                         <rect x="3" y="4" width="18" height="16" rx="2" />
                         <path d="M14 4v16" />
                         <path d="M17 9h1" />

package/templates/webterm/public/styles.css

@@ -527,6 +527,13 @@ body {
     display: flex;
     flex: 1;
     min-height: 0;
+    /* Stated once because two rules need it: the grip is this wide, and a full-width pane is the row less
+       the grip - which is what keeps the grip on the screen with the terminal squeezed out behind it. */
+    --grip-width: 12px;
+    /* The terminal's own inset, on both sides. A margin does not shrink with the box it is on, so a
+       full-width pane has to leave it as well or the row is wider than the window and the pane's own
+       controls, which sit at its far end, go off the screen. */
+    --term-gutter: 24px;
 }
 
 #termwrap {
@@ -537,7 +544,7 @@ body {
     /* Spacing via margin, not padding: FitAddon measures the wrapper height but does not subtract
        its padding, so wrapper padding makes it propose one row too many and the last line clips.
        Margin gives the same visual inset (page and terminal share a background) without breaking fit. */
-    margin: 8px 12px;
+    margin: 8px calc(var(--term-gutter) / 2);
 }
 
 #term {
@@ -595,7 +602,7 @@ body {
 #grip {
     position: relative;
     flex: none;
-    width: 12px;
+    width: var(--grip-width);
     background: var(--panel);
     border-left: 1px solid var(--border);
     border-right: 1px solid var(--border);
@@ -626,8 +633,9 @@ body.dragging {
     user-select: none;
 }
 
-/* The width is app/pane.js's, in a custom property so the two rules that must win - the collapsed spine and
-   the narrow-screen layout - still do. The value here is what shows before the first drag. */
+/* The width is app/pane-shell.js's, in a custom property so the three rules that must win - the collapsed
+   spine, the full row and the narrow-screen layout - still do. The value here is what shows before the first
+   drag. */
 #pane {
     display: flex;
     flex: none;
@@ -637,6 +645,16 @@ body.dragging {
     background: var(--bg);
 }
 
+/* The far end of the range: the pane takes the row and the terminal is squeezed out of it rather than hidden,
+   so the terminal keeps its place in the layout and comes back at whatever the next width is. The grip is
+   what the row leaves over, which is what keeps the way back on the screen, and the terminal's gutter is left
+   as well - it is a margin, so it stays whatever the box it is on shrinks to, and taking the row without it
+   would push the pane's own controls past the right edge of the window. Both are the same background, so what
+   the terminal leaves behind reads as part of the pane. */
+#pane.full {
+    width: calc(100% - var(--grip-width) - var(--term-gutter));
+}
+
 /* A page arrived and opened itself: one pulse of the workspace colour along the pane's own edge, and nothing
    moves. Inset, so it is drawn over the pane rather than pushing the layout about, and over the frame's edge
    rather than under it. ARRIVAL_MS in app/pane.js must match the duration - it is what takes the class off
@@ -664,20 +682,8 @@ body.dragging {
     }
 }
 
-/* The pagination bar: this session's pages as chips, the arrows for a bar too narrow to hold them, and where
-   in the history the open page sits. Drawn by the interface, outside the page's frame, so it always says the
-   truth about which page is open. */
-#pagebar {
-    display: flex;
-    flex: none;
-    align-items: center;
-    gap: 6px;
-    padding: 7px 10px;
-    background: var(--panel);
-    border-bottom: 1px solid var(--border);
-    overflow: hidden;
-}
-
+/* The small square buttons of the pane's two bars: the width controls up in the pane's own chrome, and the
+   chip arrows down in the Pages bar. */
 .pane-nav {
     flex: none;
     padding: 1px 6px;
@@ -695,6 +701,112 @@ body.dragging {
     color: var(--text);
 }
 
+/* The pane's own bar: which tool is open, and how wide the pane is. Nothing in it belongs to a tool, which is
+   what stops a tool from moving the pane or from saying which tool the user is looking at. */
+#panebar {
+    display: flex;
+    flex: none;
+    align-items: flex-end;
+    gap: 2px;
+    padding: 7px 10px 0;
+    background: var(--bg);
+    border-bottom: 1px solid var(--border);
+}
+
+#tool-tabs {
+    display: flex;
+    gap: 2px;
+    min-width: 0;
+    overflow: hidden;
+}
+
+/* A tab is a folder mouth: the open one carries the panel's own background up into the bar, so the two read
+   as one surface and the others read as behind it. */
+.tool-tab {
+    display: flex;
+    flex: none;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 14px;
+    border: 1px solid transparent;
+    border-bottom: none;
+    border-radius: 7px 7px 0 0;
+    background: none;
+    color: var(--muted);
+    font: inherit;
+    font-size: 12.5px;
+    cursor: pointer;
+}
+
+.tool-tab:hover {
+    color: var(--text);
+}
+
+.tool-tab.on {
+    background: var(--panel);
+    border-color: var(--border);
+    color: var(--text);
+}
+
+/* What is waiting in a tool nobody is looking at. The same green as everything else that means "something
+   happened here". */
+.tool-mark {
+    padding: 0 5px;
+    border-radius: 8px;
+    background: var(--accent);
+    color: #04140b;
+    font-size: 9.5px;
+    font-weight: 700;
+}
+
+#pane-ctl {
+    display: flex;
+    flex: none;
+    margin-left: auto;
+    gap: 4px;
+    padding-bottom: 5px;
+}
+
+#pane-ctl .pane-nav {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 2px 5px;
+}
+
+/* The pane is already at the far end, and the button is the way back from it. */
+#pane-ctl .pane-nav.on {
+    background: #10151c;
+    color: var(--accent);
+}
+
+/* One tool's panel. Only the open one is on the screen, and each fills whatever the pane's bar leaves. */
+.tool-panel {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    min-width: 0;
+    min-height: 0;
+}
+
+.tool-panel[hidden] {
+    display: none;
+}
+
+/* The pagination bar: this session's pages as chips, the arrows for a bar too narrow to hold them, and where
+   in the history the open page sits. Drawn by the interface, outside the page's frame, so it always says the
+   truth about which page is open. */
+#pagebar {
+    display: flex;
+    flex: none;
+    align-items: center;
+    gap: 6px;
+    padding: 7px 10px;
+    background: var(--panel);
+    border-bottom: 1px solid var(--border);
+    overflow: hidden;
+}
+
 #chips {
     display: flex;
     gap: 6px;
@@ -810,15 +922,6 @@ body.dragging {
     letter-spacing: 0.02em;
 }
 
-/* Out of the way, at the end of the bar: the pane is put away far more often than the chips are paged. */
-#pane-collapse {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    margin-left: 4px;
-    padding: 2px 5px;
-}
-
 #page-doc {
     flex: 1;
     min-width: 0;
@@ -841,10 +944,21 @@ body.dragging {
     zoom: var(--page-zoom, 1);
 }
 
+/* A tool's own client, in a frame of its own. It fills the panel and this side styles nothing inside it: the
+   tool ships its own document, its own stylesheet and its own theme, and the shell cannot reach in anyway. */
+.tool-frame {
+    display: block;
+    width: 100%;
+    height: 100%;
+    border: none;
+    background: var(--bg);
+}
+
 /* A page is a document with an event loop of its own, and a pointer that crosses into it during a drag is a
    pointer the grip has to keep. Capture does that in every engine that has it; taking the frame out of the
    hit test for the length of the drag is what makes it true everywhere. */
-body.dragging .page-frame {
+body.dragging .page-frame,
+body.dragging .tool-frame {
     pointer-events: none;
 }
 
@@ -893,8 +1007,8 @@ body.dragging .page-frame {
     width: 30px;
 }
 
-#pane.collapsed #pagebar,
-#pane.collapsed #page-doc {
+#pane.collapsed #panebar,
+#pane.collapsed .tool-panel {
     display: none;
 }