chamba 0.3.0 → 0.4.0

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

@@ -0,0 +1,244 @@
+// drafts.js - the two stores this window keeps per session: what has not been sent, and what already was.
+//
+// Both belong to the browser window rather than to the container, both are keyed by session id, and both go
+// when their session does - so they are one module and share the pruning that ends them.
+
+import { autoGrow, imageCounter, pendingImages, setImageCounter } from "./composer.js";
+import { input } from "./dom.js";
+import { noteMsg } from "./note.js";
+import { attachedSid, labelOf, sessions } from "./state.js";
+
+// --- Per-session drafts ------------------------------------------------------------------------------------------------------------------
+//
+// A half-written message belongs to the conversation it was written for, so the box is swapped when you
+// switch tabs and emptied when the session ends. Three things move together: the text, the image tokens in
+// it, and the counter those tokens come from - a token only means something next to the map that expands it,
+// so one shared map would let [Image #1] in one session resolve to another session's file.
+//
+// The draft is this window's. It survives a switch, a reload and a reconnect after sleep (sessionStorage,
+// where the last attached session is already remembered), but it does not follow the session into another
+// browser window: an unsent message stays where it was typed.
+
+const DRAFTS_KEY = "webterm-drafts";
+// How long after the last keystroke the drafts reach storage. Every switch, send and close writes at once,
+// so this only covers reloading mid-sentence.
+const DRAFT_PERSIST_MS = 500;
+
+// sid -> { text, images: [[token, path], ...], counter }. Images are pairs rather than a Map so a draft is
+// plain JSON.
+const drafts = new Map();
+let draftTimer = null;
+
+export function persistDrafts() {
+    if (draftTimer) {
+        clearTimeout(draftTimer);
+        draftTimer = null;
+    }
+    try {
+        sessionStorage.setItem(DRAFTS_KEY, JSON.stringify([...drafts]));
+    } catch {
+        // A disabled or full store must not break typing; the drafts still work for this page's lifetime.
+    }
+}
+
+export function schedulePersist() {
+    if (draftTimer) return;
+    draftTimer = setTimeout(() => {
+        draftTimer = null;
+        persistDrafts();
+    }, DRAFT_PERSIST_MS);
+}
+
+// Storage is a convenience: anything unreadable or malformed just means the composer starts empty.
+try {
+    const stored = JSON.parse(sessionStorage.getItem(DRAFTS_KEY) ?? "[]");
+    if (Array.isArray(stored)) {
+        for (const pair of stored) {
+            const [sid, draft] = Array.isArray(pair) ? pair : [];
+            if (typeof sid === "string" && draft && typeof draft.text === "string") drafts.set(sid, draft);
+        }
+    }
+} catch {
+    // Nothing to restore.
+}
+
+// A reload keeps what was typed rather than eating it, including the last few keystrokes.
+window.addEventListener("pagehide", persistDrafts);
+
+// The composer as it stands now, stored under the session it was typed for. An empty box stores nothing, so
+// clicking through sessions does not pile up empty drafts. Callers decide whether the write is urgent.
+export function captureDraft(sid) {
+    if (!sid) return;
+    if (input.value) drafts.set(sid, { text: input.value, images: [...pendingImages], counter: imageCounter });
+    else drafts.delete(sid);
+}
+
+export function restoreDraft(sid) {
+    const draft = drafts.get(sid);
+    input.value = draft?.text ?? "";
+    pendingImages.clear();
+    for (const [token, path] of draft?.images ?? []) pendingImages.set(token, path);
+    setImageCounter(draft?.counter ?? 0);
+    // Each session has its own history, so a walk never carries across a switch.
+    endHistoryWalk();
+    autoGrow();
+}
+
+// The session is gone, so its unsent message goes with it.
+export function dropDraft(sid) {
+    if (sid && drafts.delete(sid)) persistDrafts();
+}
+
+// Drop everything this window is holding for a session that is no longer in the bar, and say whether anything went.
+// Shared by the two stores kept per session - the unsent message and the history below - because both end the same
+// way at the same moment. This is what covers a session closed from another window, which arrives as a bar without
+// it rather than as an exit.
+function pruneBySession(store) {
+    if (store.size === 0) return false;
+    const live = new Set(sessions.map((session) => session.id));
+    let removed = false;
+    for (const sid of [...store.keys()]) {
+        if (live.has(sid)) continue;
+        store.delete(sid);
+        removed = true;
+    }
+    return removed;
+}
+
+export function pruneDrafts() {
+    if (pruneBySession(drafts)) persistDrafts();
+}
+
+// The window moved on before an upload finished. The token still belongs to the session the image was
+// attached to, so it goes onto that session's draft, numbered by that draft's own counter.
+export function addImageToDraft(sid, path) {
+    const draft = drafts.get(sid) ?? { text: "", images: [], counter: 0 };
+    const counter = draft.counter + 1;
+    const token = `[Image #${counter}]`;
+    const lead = draft.text && !draft.text.endsWith(" ") && !draft.text.endsWith("\n") ? " " : "";
+    drafts.set(sid, { text: `${draft.text}${lead}${token} `, images: [...draft.images, [token, path]], counter });
+    persistDrafts();
+    noteMsg(`image added to ${labelOf(sid, "the session it was attached to")}`);
+}
+
+// --- What you already sent ---------------------------------------------------------------------------------------------------------------
+//
+// Up in an empty box brings back the last message, the way a shell does. The composer exists so a long message can be
+// written properly, and the messages worth having back are exactly the long ones: a prompt that needed one more
+// sentence, a path that was almost right, a question worth asking again of a different session.
+//
+// Two rules keep it out of the way of ordinary typing. It only starts from an empty box, so Up can never snatch away
+// something half-written. And once it has started, Up and Down only step on from the first and last line of what is
+// showing, so the arrows still walk around a recalled message the way they walk around any other text - a shell with
+// a multi-line buffer behaves the same, and anything else is a trap. Typing ends the walk: what is in the box is
+// yours again, and the arrows go back to being arrows.
+//
+// What is stored is what was actually sent, image tokens already expanded. A recalled message has to mean the same
+// thing the second time, and [Image #1] means nothing once the box that numbered it has been emptied.
+//
+// The history is this window's, like the drafts above, and it holds what went through this box - not what was typed
+// straight into the terminal, which the agent's own history already has.
+
+const HISTORY_KEY = "webterm-history";
+// Long enough to cover a working session, short enough that this never becomes somewhere data quietly accumulates.
+const HISTORY_MAX = 50;
+
+// sid -> [oldest, ..., newest].
+const histories = new Map();
+// How far back the walk has got in the attached session's history, or null when the box holds the user's own text.
+export let historyAt = null;
+
+function persistHistory() {
+    try {
+        sessionStorage.setItem(HISTORY_KEY, JSON.stringify([...histories]));
+    } catch {
+        // Storage that will not take it costs the recall after a reload and nothing else.
+    }
+}
+
+try {
+    const stored = JSON.parse(sessionStorage.getItem(HISTORY_KEY) ?? "[]");
+    if (Array.isArray(stored)) {
+        for (const pair of stored) {
+            const [sid, list] = Array.isArray(pair) ? pair : [];
+            if (typeof sid !== "string" || !Array.isArray(list)) continue;
+            histories.set(
+                sid,
+                list.filter((line) => typeof line === "string"),
+            );
+        }
+    }
+} catch {
+    // Nothing to recall.
+}
+
+window.addEventListener("pagehide", persistHistory);
+
+// The same message twice running is one entry: sending something again is normal, and a history filled with it is
+// not worth walking through.
+export function rememberSent(sid, text) {
+    if (!sid || !text) return;
+    const list = histories.get(sid) ?? [];
+    if (list[list.length - 1] !== text) list.push(text);
+    while (list.length > HISTORY_MAX) list.shift();
+    histories.set(sid, list);
+    persistHistory();
+}
+
+// The session is gone, and everything said to it goes too.
+export function dropHistory(sid) {
+    if (sid && histories.delete(sid)) persistHistory();
+}
+
+export function pruneHistory() {
+    if (pruneBySession(histories)) persistHistory();
+}
+
+// Where the caret is, in lines. The arrows only reach for history from the edges of what is in the box.
+export function atFirstLine() {
+    return !input.value.slice(0, input.selectionStart ?? 0).includes("\n");
+}
+
+export function atLastLine() {
+    return !input.value.slice(input.selectionEnd ?? input.value.length).includes("\n");
+}
+
+// Put an entry in the box, caret at the end of it - which is where you carry on typing from. It becomes the session's
+// draft like anything else in the box, so switching away and back does not lose a message you went and fetched.
+export function showRecalled(text) {
+    input.value = text;
+    autoGrow();
+    const end = input.value.length;
+    input.setSelectionRange(end, end);
+    captureDraft(attachedSid);
+    schedulePersist();
+}
+
+// Typing makes the box yours again.
+export function endHistoryWalk() {
+    historyAt = null;
+}
+
+// One step through the attached session's history; `back` is Up. Says whether it moved, so a step that had nowhere
+// to go leaves the keypress to the browser instead of swallowing it.
+export function walkHistory(back) {
+    const list = histories.get(attachedSid) ?? [];
+    if (list.length === 0) return false;
+    if (back) {
+        // The oldest entry is the end of the road rather than a wrap back to the newest: a list that loops has no
+        // end, and you would never know you had seen all of it.
+        historyAt = historyAt === null ? list.length - 1 : Math.max(0, historyAt - 1);
+        showRecalled(list[historyAt]);
+        return true;
+    }
+    if (historyAt === null) return false;
+    // Forward past the newest is the empty box the walk started from, not the newest all over again.
+    if (historyAt >= list.length - 1) {
+        endHistoryWalk();
+        showRecalled("");
+        return true;
+    }
+    historyAt += 1;
+    showRecalled(list[historyAt]);
+    return true;
+}

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

@@ -0,0 +1,166 @@
+// frames.js - what to do with a frame the server sent.
+//
+// One function per frame kind and nothing else: every frame either moves this window to a session, writes to the
+// terminal, redraws the bar, or opens a card. It is the one module that talks to all the others, so nothing else
+// has to know what a frame looks like.
+
+import { refreshBrowserTab, scheduleChime } from "./alerts.js";
+import { badAgentCard, badDirCard, capCard, stopFailedCard, takenCard, takeoverCard } from "./cards.js";
+import { writeReplay } from "./clipboard.js";
+import { clearComposer, refreshComposer } from "./composer.js";
+import { hideCurtain, LAST_SID_KEY, noteSocketAlive, resumeReconnects, stoppingCurtain } from "./connection.js";
+import { stopDictation } from "./dictation.js";
+import { captureDraft, dropDraft, dropHistory, persistDrafts, pruneDrafts, pruneHistory, restoreDraft } from "./drafts.js";
+import { noteMsg } from "./note.js";
+import { applyPages, prunePanes, refreshPane } from "./pane.js";
+import { adoptSessionsFrame, attachedSid, defaultAgent, sessions, setAttachedSid } from "./state.js";
+import { applySnapshot, pruneStatuses, refreshStrip } from "./status-strip.js";
+import { noteArrivals, renderBar } from "./tabs.js";
+import { focusTerminal, scheduleRefresh, sendResize, term } from "./terminal.js";
+
+// What the terminal is holding: either a live session's screen (`shownSid`), or a message where a session used
+// to be (`shownMessage`). At most one of them is set. They are tracked because a session can end while this
+// window is watching it - nothing replays over the dead screen then, and a dead screen looks exactly like a
+// live one. The last screen of an agent that exited on its own is kept rather than replaced (it usually says
+// why), so it counts as a message already delivered and no later bar update paints over it.
+const EXITED_SCREEN = "exited";
+let shownSid = null;
+let shownMessage = null;
+
+export function onFrame(msg) {
+    // Any frame at all proves the socket works, which is what a wake probe is waiting to hear.
+    noteSocketAlive();
+    if (msg.t === "sessions") {
+        applySessions(msg);
+    } else if (msg.t === "replay") {
+        // A replay for the session this window is already on is a reconnect or a session taken back, not a
+        // switch, so the composer is left exactly as it is. A real switch parks the outgoing draft, ends
+        // dictation, and loads the incoming session's draft once the screen is up.
+        const switching = attachedSid !== msg.sid;
+        if (switching) {
+            captureDraft(attachedSid);
+            persistDrafts();
+            stopDictation();
+        }
+        setAttachedSid(msg.sid);
+        sessionStorage.setItem(LAST_SID_KEY, msg.sid);
+        shownSid = msg.sid;
+        shownMessage = null;
+        // Reset first: the buffer is the whole screen, so writing it without a reset would paint it on
+        // top of whatever was there (the previous session, or this one before a reconnect).
+        term.reset();
+        // Through writeReplay, not term.write: a replayed screen still carries the OSC 52 of any copy made
+        // in that session, and re-running it would rewrite the clipboard behind the user's back.
+        writeReplay(msg.data);
+        scheduleRefresh();
+        // The click that got here (a tab, or "+ New session") left the terminal blurred.
+        focusTerminal();
+        // The PTY was last sized for whichever window had it; this one may be a different shape.
+        sendResize();
+        if (switching) restoreDraft(msg.sid);
+        refreshComposer();
+        // The pane and the strip belong to the session, so they move with the screen.
+        refreshPane();
+        refreshStrip();
+    } else if (msg.t === "pages") {
+        applyPages(msg);
+    } else if (msg.t === "snapshot") {
+        applySnapshot(msg);
+    } else if (msg.t === "out") {
+        // Output from a session this window has already left; the window that has it is showing it.
+        if (msg.sid !== attachedSid) return;
+        term.write(msg.data);
+        scheduleRefresh();
+    } else if (msg.t === "busy") {
+        takeoverCard(msg.sid);
+    } else if (msg.t === "taken") {
+        // The session is alive in the other window and can be taken back, so the draft is parked under it
+        // rather than thrown away, and comes back with it.
+        captureDraft(attachedSid);
+        persistDrafts();
+        clearComposer();
+        setAttachedSid(null);
+        takenCard(msg.sid);
+        refreshComposer();
+        refreshPane();
+        refreshStrip();
+    } else if (msg.t === "exit") {
+        if (msg.sid === attachedSid) {
+            setAttachedSid(null);
+            // The box was holding an unsent message for a conversation that no longer exists.
+            clearComposer();
+            term.write(`\r\n\x1b[90m[webterm] ${msg.agent || "the agent"} exited, so this session is gone.\x1b[0m\r\n`);
+            shownSid = null;
+            shownMessage = EXITED_SCREEN;
+        }
+        dropDraft(msg.sid);
+        dropHistory(msg.sid);
+        refreshComposer();
+        refreshPane();
+        refreshStrip();
+    } else if (msg.t === "stopping") {
+        // Sent to every window, not just the one that asked: the container is about to take them all.
+        stoppingCurtain();
+    } else if (msg.t === "error") {
+        if (msg.code === "cap") capCard();
+        else if (msg.code === "cwd") badDirCard();
+        else if (msg.code === "agent") badAgentCard();
+        else if (msg.code === "stop") {
+            // The container is still here after all, so the page goes back to being usable.
+            resumeReconnects();
+            hideCurtain();
+            stopFailedCard();
+        } else noteMsg(`could not start ${msg.agent || "the agent"} - check the webterm log in the container`, true);
+    }
+}
+
+function applySessions(msg) {
+    adoptSessionsFrame(msg);
+    // Before the bar draws: its flash reads these timestamps, so an alert plays once instead of on every frame.
+    noteArrivals();
+    renderBar();
+    // Said again where a window that is behind something else can still be heard.
+    refreshBrowserTab();
+    // And, twenty seconds from now, said out loud - if it is still true and nobody has come back by then.
+    scheduleChime();
+    // Sessions that are no longer in the bar take their unsent messages and their history with them.
+    pruneDrafts();
+    pruneHistory();
+    refreshComposer();
+    // Same for the pane: a session that left the bar takes this window's copy of its page list with it. The
+    // files themselves are untouched - a resumed conversation gets them back (FR-15).
+    const live = new Set(sessions.map((entry) => entry.id));
+    prunePanes(live);
+    refreshPane();
+    // And for the strip: the numbers belong to a session, and that session is gone.
+    pruneStatuses(live);
+    refreshStrip();
+    // A session can vanish from under this window: closed here, closed from another window, or the agent exited.
+    // Where the server had a free session to move this window to, that session's replay has already painted over
+    // it. Where it did not - every remaining session is being driven elsewhere - this is the only thing that says
+    // the screen in front of the user is dead, and the alternative is a window that looks live and swallows
+    // keystrokes. A screen this window is no longer driving but could take back is left alone: that is the
+    // takeover case, and its card offers it back.
+    if (!attachedSid && shownMessage !== EXITED_SCREEN) {
+        const gone = shownSid !== null && !sessions.some((entry) => entry.id === shownSid);
+        if (gone || shownSid === null) showMessage(idleMessage());
+    }
+}
+
+// Why there is nothing to type into, and the way out of it. Neither line names the session that went away: it
+// is gone from the bar, and what the user needs is the next step.
+function idleMessage() {
+    return sessions.length === 0
+        ? `No sessions. Use "+ New session" above to start ${defaultAgent}.`
+        : "Every session is open in another window - click one above to bring it here.";
+}
+
+// Replaces the terminal with that line. Only when it changes, so an ordinary bar update does not clear and
+// redraw the screen underneath the user.
+function showMessage(line) {
+    if (line === shownMessage) return;
+    shownSid = null;
+    shownMessage = line;
+    term.reset();
+    term.write(`\r\n  \x1b[90m${line}\x1b[0m\r\n`);
+}

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

@@ -0,0 +1,82 @@
+// main.js - xterm.js terminal, the session bar, and the rich composer, all over one WebSocket.
+//
+// The session bar is mission control for this container: every live agent is a tab, this window drives
+// one of them at a time, and none of them ends because a window closed or a laptop slept. Tabs are dragged
+// to reorder them, and the order is the registry's, so every window agrees on it. A tab also says what its
+// session is doing without being opened: a light travels round it while the agent works, and it holds lit
+// until visited when an agent finished something nobody was there to see - which the page title and the
+// favicon repeat, for when the whole window is behind something else. The terminal renders the
+// attached session's live TUI and forwards raw keystrokes and resizes. The composer handles typing, image
+// paste/drop/upload, and dictation, and what is in it belongs to the attached session: switching tabs swaps
+// the draft, and ending a session throws its draft away. Pasted images are uploaded and their container
+// paths are inserted inline, so what you see in the box is what is sent; on Send the whole composer text
+// goes as one {t:"paste"} frame the server wraps as a bracketed paste.
+//
+// Everything here rides on the key this window was handed in its URL: the socket, the uploads and the
+// status probe all carry it, and without a valid one the page is never served in the first place.
+//
+// The page is plain ES modules with no build step, one per subject:
+//
+//   state.js        what the server last told this window, and the URL's key
+//   dom.js          the elements index.html ships with
+//   theme.js        the palette, this workspace's colour, and the session colours
+//   note.js         the status pill over the terminal
+//   terminal.js     the terminal, its size, and the keystrokes that go straight to the PTY
+//   tabs.js         the session bar, its two animations, renaming, and reordering
+//   new-session.js  the panel behind the chevron: which agent, and which directory
+//   alerts.js       the browser tab (title and drawn favicon), and the chime
+//   cards.js        the overlay cards
+//   connection.js   the socket, the reconnect loop, and the curtain
+//   frames.js       what to do with each frame the server sends
+//   pane.js         the web pane: the chips bar, the drag and the spine
+//   pane-frame.js   a published page in a sandboxed frame, and the answer that comes back out of it
+//   status-strip.js the attached session's model, context, quota and version, above the composer
+//   composer.js     the box, its images, and Send
+//   drafts.js       per-session unsent messages, and what was already sent
+//   clipboard.js    copy and paste, OSC 52, and the replay gate
+//   dictation.js    the microphone button
+//
+// One rule holds them together: a module defines things and hooks up its own listeners when it is loaded, and
+// never calls into another module while the page is still loading. The graph has cycles on purpose - the frame
+// router talks to every feature and every feature answers back - so a module that ran another module's code at
+// load time would be reaching into something half-built. Everything with an order to it happens here.
+//
+// Reading at load time follows from the same thing: a module may read from one that imports nothing itself
+// (dom.js, state.js, theme.js), since a leaf is always finished by the time anything else runs, and never from
+// one inside the cycle, whose values may not exist yet.
+//
+// Every module is imported here, including the ones this file has nothing to call. Several exist for what they
+// do when they load - the microphone button, the chevron panel's Escape key, the workspace colour, the draft
+// that is saved when the page goes away - and reaching them only through whoever happens to import a function
+// from them would let an unrelated edit take a feature off the page with no test to notice. A test walks the
+// imports from this file and fails if a module is not reachable.
+
+import { refreshBrowserTab } from "./alerts.js";
+import { installClipboard } from "./clipboard.js";
+import { refreshComposer } from "./composer.js";
+import { connect } from "./connection.js";
+import "./cards.js";
+import "./dictation.js";
+import "./dom.js";
+import "./drafts.js";
+import "./frames.js";
+import "./new-session.js";
+import "./note.js";
+import "./pane.js";
+import "./pane-frame.js";
+import "./state.js";
+import "./status-strip.js";
+import "./theme.js";
+import { renderBar } from "./tabs.js";
+import { mountTerminal, term } from "./terminal.js";
+
+// --- Go ----------------------------------------------------------------------------------------------------------------------------------
+
+mountTerminal();
+installClipboard();
+refreshComposer();
+renderBar();
+// Before the first frame arrives, so the icon carries this workspace's frame from the moment the page loads.
+refreshBrowserTab();
+connect();
+term.focus();