@oddessentials/agent-guild 0.28.0 → 0.28.1

package/README.md

@@ -68,6 +68,12 @@ session name in the header switches the focused terminal to another session.
 On a phone one terminal shows at a time, with a button to switch to the
 other. This browser reopens the terminals you had open after a reload.
 
+On phones and tablets, a strip below the terminal provides **← ↑ ↓ → Enter
+Esc**. Tap once to move through a prompt, confirm a choice or send Escape.
+The keys act on the focused terminal and leave the on-screen keyboard as
+it is. They are disabled while the terminal reconnects or after it exits;
+taps made while disconnected are never replayed.
+
 On a touchscreen, **Copy…** opens a still copy of the terminal text. Touch and
 hold to select, then use **Copy selection** or the browser's Copy menu. **Done**
 returns to the live terminal; the session keeps running while you copy. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "Launch and watch AI coding-assistant terminal sessions from one local web page. A bundled session manager owns the terminals so the page can close and reconnect.",
   "license": "MIT",
   "repository": {

package/web/app.js

@@ -3,6 +3,7 @@
 
 import { SOUNDS, MAX_ALERT_AGE_MS, playOnce, rearmSound, managerLossWatcher, stopWatcher, updateWatcher } from './alerts.js';
 import { TerminalCopy } from './terminal-copy.js';
+import { TerminalControls, bindTerminalViewport } from './terminal-controls.js';
 import { topbarInline, dockMode, clampDockWidth, stageBesideDock, splitMode, clampRatio, bindSplitter, DOCK_MIN, SPLIT_RATIO_MIN } from './layout.js';
 import { highlightParts, rankRepos, recentFirst, remember, repoForOrigin, repoKey } from './repo-search.js';
 import { createActivityFavicon, isSessionWorking } from './activity-favicon.js';
@@ -124,6 +125,7 @@ function setConnection(kind, label) {
   el.title = label;
   // The manager can only be stopped, restarted or upgraded while the page can reach it.
   state.connected = kind === 'ok';
+  terminalControls.refresh();
   state.remoteAccessUI?.connectionChanged();
   $('manager').hidden = !state.connected;
   if (!state.connected) closeMenu($('manager-menu'));
@@ -4426,11 +4428,18 @@ class TerminalView {
 
   connect() {
     if (this.disposed || state.remoteRevoked) return;
+    this.inputReady = false;
+    this.inputSnapshot = null;
+    terminalControls.refresh();
     const ws = new WebSocket(wsUrl(`/sessions/${this.id}/terminal`));
     this.ws = ws;
     ws.onopen = () => { this.retry = 0; this.sent = { cols: 0, rows: 0 }; this.sendSize(); };
-    ws.onmessage = (event) => this.onMessage(JSON.parse(event.data));
+    ws.onmessage = (event) => { if (!this.disposed && this.ws === ws) this.onMessage(JSON.parse(event.data)); };
     ws.onclose = (event) => {
+      if (this.ws !== ws) return;
+      this.inputReady = false;
+      this.inputSnapshot = null;
+      terminalControls.refresh();
       if (this.disposed || event.code === 4403 || event.code === 4404 || event.code === 4410) return;
       const delay = Math.min(5000, 300 * 2 ** this.retry++);
       setTimeout(() => this.connect(), delay);
@@ -4440,14 +4449,31 @@ class TerminalView {
   onMessage(msg) {
     switch (msg.type) {
       case 'snapshot':
+        this.inputReady = false;
+        this.inputSnapshot = msg;
+        this.inputRun = msg.session.startedAt;
+        terminalControls.refresh();
         this.term.reset();
         this.term.resize(msg.cols, msg.rows);
-        this.term.write(msg.data, () => { this.sent = { cols: 0, rows: 0 }; this.refit(); });
+        {
+          const ws = this.ws;
+          this.term.write(msg.data, () => {
+            if (this.disposed || this.ws !== ws || ws.readyState !== WebSocket.OPEN || this.inputSnapshot !== msg) return;
+            this.inputReady = msg.session.status === 'running';
+            this.inputSnapshot = null;
+            this.sent = { cols: 0, rows: 0 };
+            this.refit();
+            terminalControls.refresh();
+          });
+        }
         break;
       case 'data':
         this.term.write(msg.data);
         break;
       case 'exit':
+        this.inputReady = false;
+        this.inputSnapshot = null;
+        terminalControls.refresh();
         if (dictation?.id === this.id) stopDictation();
         this.term.write(`\r\n\x1b[2m${exitLine(state.sessions.get(this.id), msg)}\x1b[0m\r\n`);
         break;
@@ -4532,6 +4558,9 @@ class TerminalView {
 
   dispose() {
     this.disposed = true;
+    this.inputReady = false;
+    this.inputSnapshot = null;
+    terminalControls.refresh();
     this.resizeObserver.disconnect();
     this.ws?.close();
     this.term.dispose();
@@ -4541,6 +4570,20 @@ class TerminalView {
 
 // ---- terminal panel -------------------------------------------------------
 
+const terminalControls = new TerminalControls({
+  element: $('terminal-controls'), panel: $('terminal-panel'),
+  getCurrent: () => {
+    const session = state.sessions.get(state.activeId);
+    const view = state.views.get(state.activeId);
+    if (!session || session.status !== 'running' || !view?.inputReady || view.disposed
+      || session.startedAt !== view.inputRun || view.ws?.readyState !== WebSocket.OPEN
+      || !state.connected || state.pageAway || state.remoteRevoked || state.stopping
+      || $('app').hidden || $('terminal-panel').hidden || !view.el.isConnected) return null;
+    return { term: view.term, socket: view.ws, run: session.startedAt, name: session.name };
+  },
+});
+bindTerminalViewport($('terminal-panel'), $('terminal-controls'));
+
 const terminalCopy = new TerminalCopy({
   opener: $('panel-copy'), dialog: $('terminal-copy'),
   getCurrent: () => {
@@ -4578,7 +4621,7 @@ function openPanel(id, { beside = false, restoring = false } = {}) {
 function focusPane(index, { focusTerminal = true } = {}) {
   const id = state.panes[index];
   if (!id) return;
-  if (state.activeId !== id) terminalCopy.close();
+  if (state.activeId !== id) { terminalCopy.close(); terminalControls.cancel(); }
   if (dictation && dictation.id !== id) stopDictation();
   state.focusedPane = index;
   state.activeId = id;
@@ -4599,6 +4642,7 @@ function closePane(index, { focusTerminal = true } = {}) {
 }
 
 function closePanel() {
+  terminalControls.cancel();
   terminalCopy.close();
   stopDictation();
   for (const id of state.panes) state.views.get(id)?.unmount();
@@ -4613,7 +4657,8 @@ function closePanel() {
 
 function stageSplit() {
   const box = $('terminal-panel').getBoundingClientRect();
-  return splitMode(box.width, box.height);
+  const controls = $('terminal-controls');
+  return splitMode(box.width, box.height - (controls.hidden ? 0 : controls.offsetHeight));
 }
 
 function layoutPanes() {
@@ -4709,6 +4754,7 @@ function restorePanes() {
 }
 
 function updatePanel() {
+  terminalControls.refresh();
   renderVoice();
   const s = state.sessions.get(state.activeId);
   if (!s) return;
@@ -5222,7 +5268,12 @@ bindSplitter($('pane-splitter'), {
   home: () => setSplitRatio(SPLIT_RATIO_MIN),
   endKey: () => setSplitRatio(1 - SPLIT_RATIO_MIN),
 });
-new ResizeObserver(layoutPanes).observe($('terminal-panel'));
+let terminalLayoutFrame;
+const terminalLayoutObserver = new ResizeObserver(() => {
+  cancelAnimationFrame(terminalLayoutFrame);
+  terminalLayoutFrame = requestAnimationFrame(layoutPanes);
+});
+for (const node of [$('terminal-panel'), $('terminal-controls')]) terminalLayoutObserver.observe(node);
 $('panel-voice').addEventListener('click', () => {
   if (dictation) {
     const { id } = dictation;
@@ -5570,8 +5621,13 @@ setInterval(() => { if (dockShows('github') && state.github) renderGitHub(); },
 // The terminal panel and the dock sit below the top bar; publish where it ends so they never cover its controls.
 const topbar = document.querySelector('.topbar');
 const publishTopbarHeight = () => document.documentElement.style.setProperty('--topbar-h', `${Math.max(0, Math.round(topbar.getBoundingClientRect().bottom))}px`);
-new ResizeObserver(publishTopbarHeight).observe(topbar);
-addEventListener('scroll', publishTopbarHeight, { passive: true });
+let topbarFrame;
+const scheduleTopbarHeight = () => {
+  cancelAnimationFrame(topbarFrame);
+  topbarFrame = requestAnimationFrame(publishTopbarHeight);
+};
+new ResizeObserver(scheduleTopbarHeight).observe(topbar);
+addEventListener('scroll', scheduleTopbarHeight, { passive: true });
 publishTopbarHeight();
 applyDockLayout();
 

package/web/index.html

@@ -169,6 +169,14 @@
         <div class="terminal-host"></div>
       </section>
     </div>
+    <div id="terminal-controls" class="terminal-controls" role="group" aria-label="Terminal keys" hidden>
+      <button class="btn terminal-key" type="button" data-key="ArrowLeft" aria-label="Left arrow" title="Left arrow" disabled>←</button>
+      <button class="btn terminal-key" type="button" data-key="ArrowUp" aria-label="Up arrow" title="Up arrow" disabled>↑</button>
+      <button class="btn terminal-key" type="button" data-key="ArrowDown" aria-label="Down arrow" title="Down arrow" disabled>↓</button>
+      <button class="btn terminal-key" type="button" data-key="ArrowRight" aria-label="Right arrow" title="Right arrow" disabled>→</button>
+      <button class="btn terminal-key" type="button" data-key="Enter" title="Send Enter to the terminal" disabled>Enter</button>
+      <button class="btn terminal-key" type="button" data-key="Escape" aria-label="Escape" title="Send Escape to the terminal" disabled>Esc</button>
+    </div>
     <div id="voice-preview" class="voice-preview" hidden aria-live="polite"></div>
   </div>
 

package/web/styles.css

@@ -443,7 +443,7 @@ body:has(#app[hidden]):has(#auth[hidden]):has(#stopped[hidden])::after {
 
 .terminal-panel {
   /* Below the top bar, whose bottom edge the page publishes as --topbar-h. */
-  position: fixed; inset: calc(var(--topbar-h, 52px) + 12px) calc(16px + var(--dock-stage-space, 0px)) 16px 16px; z-index: 10; display: flex; flex-direction: column;
+  position: fixed; inset: max(calc(var(--topbar-h, 52px) + 12px), var(--terminal-viewport-top, 0px)) calc(16px + var(--dock-stage-space, 0px)) calc(16px + var(--terminal-viewport-bottom, 0px)) 16px; z-index: 10; display: flex; flex-direction: column;
   background: var(--term-bg); border: 1px solid var(--border); border-radius: var(--radius);
   box-shadow: 0 20px 50px rgba(0, 0, 0, 0.35); overflow: hidden;
 }
@@ -518,6 +518,30 @@ body:has(#app[hidden]):has(#auth[hidden]):has(#stopped[hidden])::after {
 }
 .terminal-host { flex: 1; min-height: 0; padding: 8px 4px 4px 10px; }
 .terminal-host > div { height: 100%; }
+.terminal-controls {
+  flex: none; display: flex; justify-content: center; gap: 4px;
+  padding: 6px max(8px, env(safe-area-inset-right)) max(6px, env(safe-area-inset-bottom)) max(8px, env(safe-area-inset-left));
+  border-top: 1px solid var(--border); background: var(--surface);
+  touch-action: manipulation; user-select: none; -webkit-user-select: none; -webkit-touch-callout: none;
+}
+.terminal-controls .terminal-key {
+  flex: 1 1 0; min-width: 44px; max-width: 64px; min-height: 48px; padding: 4px;
+  font: 600 0.85rem var(--font-mono); touch-action: manipulation;
+}
+.terminal-key[data-key^="Arrow"] { font-size: 1.3rem; }
+.terminal-key[data-key="Enter"] { flex-grow: 1.25; max-width: 80px; }
+.terminal-key.pressed:not(:disabled) { background: var(--accent-fill); border-color: var(--accent-fill); color: var(--accent-text); transform: translateY(1px); }
+.terminal-key:disabled { cursor: default; }
+.terminal-panel:has(.terminal-controls:not([hidden])) .voice-preview { bottom: calc(72px + env(safe-area-inset-bottom)); }
+/* A docked keyboard in landscape leaves little height. Keep the session and actions
+   available in one header row; Hide still returns to the normal page. */
+.terminal-panel[data-compact] { top: var(--terminal-viewport-top, 0px); }
+.terminal-panel[data-compact] .panel-bar { flex-wrap: nowrap; gap: 6px; padding: 6px 8px; }
+.terminal-panel[data-compact] .panel-title { flex: 1 1 0; }
+.terminal-panel[data-compact] :is(.panel-title .sub, .panel-title .agents, .panel-title .provider-icon) { display: none; }
+.terminal-panel[data-compact] .panel-actions { flex-wrap: nowrap; gap: 4px; max-width: 65%; overflow-x: auto; }
+.terminal-panel[data-compact] .panel-actions .btn { flex: none; }
+.terminal-panel[data-compact] #panel-close { position: sticky; right: 0; z-index: 1; box-shadow: -4px 0 0 var(--surface); }
 .terminal-copy {
   width: min(880px, calc(100vw - 24px)); height: min(720px, calc(100dvh - 24px));
   max-width: none; max-height: none; padding: 0; overflow: hidden;
@@ -545,7 +569,7 @@ body:has(#app[hidden]):has(#auth[hidden]):has(#stopped[hidden])::after {
 }
 @media (pointer: coarse) and (max-width: 900px) {
   /* Tablets in portrait are wider than the phone layout but still want the whole width. */
-  .terminal-panel { inset: var(--topbar-h, 56px) 0 0; border-radius: 0; }
+  .terminal-panel { inset: max(var(--topbar-h, 56px), var(--terminal-viewport-top, 0px)) 0 var(--terminal-viewport-bottom, 0px); border-radius: 0; }
 }
 
 .models {
@@ -558,7 +582,8 @@ body:has(#app[hidden]):has(#auth[hidden]):has(#stopped[hidden])::after {
 .models-bar { display: flex; align-items: center; gap: 10px; padding: 12px 14px; border-bottom: 1px solid var(--border); }
 .models-heading { flex: 1; min-width: 0; }
 .models-heading .sub { margin: 2px 0 0; color: var(--muted); font-size: 0.78rem; }
-.models-body { flex: 1; min-height: 0; overflow: auto; padding: 0 14px 14px; }
+/* Content supplies the basis for auto-height dialogs; a zero basis collapses in Safari. */
+.models-body { flex: 1 1 auto; min-height: 0; overflow: auto; padding: 0 14px 14px; }
 .remote-access { width: min(560px, calc(100vw - 24px)); max-height: calc(100dvh - 24px); }
 .remote-body { padding: 4px 20px 20px; font-size: 0.9rem; }
 .remote-body > p { color: var(--muted); line-height: 1.6; }
@@ -968,7 +993,7 @@ a.btn.github-out::after {
 @media (max-width: 640px) {
   .topbar { padding: 10px 16px; }
   .connection .label { position: absolute; width: 1px; height: 1px; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
-  .terminal-panel { inset: var(--topbar-h, 56px) 0 0; border-radius: 0; }
+  .terminal-panel { inset: max(var(--topbar-h, 56px), var(--terminal-viewport-top, 0px)) 0 var(--terminal-viewport-bottom, 0px); border-radius: 0; }
   .session-grid { grid-template-columns: 1fr; }
   .cwd { flex-basis: 100%; }
   .launch-tools { flex-basis: 100%; justify-content: stretch; }

package/web/terminal-controls.js

@@ -0,0 +1,130 @@
+const ARROWS = { ArrowUp: 'A', ArrowDown: 'B', ArrowRight: 'C', ArrowLeft: 'D' };
+
+/** Use the same cursor mode as a physical keyboard, including inside full-screen tools. */
+export function terminalKey(key, modes) {
+  if (Object.hasOwn(ARROWS, key)) return `\x1b${modes.applicationCursorKeysMode ? 'O' : '['}${ARROWS[key]}`;
+  if (key === 'Enter') return '\r';
+  if (key === 'Escape') return '\x1b';
+  return null;
+}
+
+const sameTarget = (a, b) => Boolean(a && b && a.term === b.term && a.socket === b.socket && a.run === b.run);
+
+/** Six ordinary buttons. A gesture belongs to the session and connection where it began. */
+export class TerminalControls {
+  constructor({ element, panel, getCurrent }) {
+    this.element = element;
+    this.getCurrent = getCurrent;
+    this.buttons = [...element.querySelectorAll('button')];
+    const touch = matchMedia('(any-pointer: coarse)');
+    const availability = () => {
+      element.hidden = !touch.matches && !navigator.maxTouchPoints;
+      this.refresh();
+    };
+    touch.addEventListener('change', availability);
+    for (const button of this.buttons) {
+      button.addEventListener('pointerdown', (event) => {
+        this.cancel();
+        if (!event.isPrimary || event.button !== 0 || button.disabled) return;
+        // Retain xterm's focus if typing, and leave the keyboard closed if it is closed.
+        event.preventDefault();
+        const target = this.current();
+        if (!target) return;
+        this.press = { button, target, pointer: event.pointerId };
+        button.setPointerCapture(event.pointerId);
+        button.classList.add('pressed');
+      });
+      button.addEventListener('pointermove', (event) => {
+        if (this.press?.pointer === event.pointerId && document.elementFromPoint(event.clientX, event.clientY) !== button) this.cancel();
+      });
+      button.addEventListener('pointerup', (event) => {
+        const press = this.press;
+        if (press?.pointer !== event.pointerId) return;
+        this.cancel();
+        if (document.elementFromPoint(event.clientX, event.clientY) === button) this.activate(button, press.target);
+      });
+      for (const type of ['pointercancel', 'lostpointercapture', 'blur']) button.addEventListener(type, () => this.cancel());
+      button.addEventListener('keydown', (event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') return;
+        event.preventDefault();
+        if (event.repeat) return;
+        this.cancel();
+        this.press = { button, target: this.current(), key: event.key };
+        button.classList.add('pressed');
+      });
+      button.addEventListener('keyup', (event) => {
+        const press = this.press;
+        if (!press || press.key !== event.key || press.button !== button) return;
+        event.preventDefault();
+        this.cancel();
+        this.activate(button, press.target);
+      });
+      // Pointer and keyboard releases were handled above. Keep assistive-technology
+      // activation working without sending a second key for the following click.
+      button.addEventListener('click', (event) => {
+        if (event.detail === 0 && !event.pointerType) this.activate(button, this.current());
+      });
+    }
+    addEventListener('blur', () => this.cancel());
+    addEventListener('pagehide', () => this.cancel());
+    document.addEventListener('visibilitychange', () => { this.cancel(); this.refresh(); });
+    // Modal Copy (and other dialogs) must cancel a press even if it closes before release.
+    new MutationObserver(() => { this.cancel(); this.refresh(); }).observe(document.body, {
+      subtree: true, attributes: true, attributeFilter: ['open'],
+    });
+    new MutationObserver(() => this.refresh()).observe(panel, { attributes: true, attributeFilter: ['hidden'] });
+    availability();
+  }
+
+  current() {
+    if (this.element.hidden || document.visibilityState !== 'visible' || document.querySelector('dialog[open]')) return null;
+    return this.getCurrent();
+  }
+
+  refresh() {
+    const target = this.current();
+    if (!sameTarget(this.press?.target, target)) this.cancel();
+    for (const button of this.buttons) button.disabled = !target;
+    this.element.setAttribute('aria-label', target ? `Terminal keys for ${target.name}` : 'Terminal keys unavailable');
+  }
+
+  cancel() {
+    this.press?.button.classList.remove('pressed');
+    this.press = null;
+  }
+
+  activate(button, target) {
+    if (!sameTarget(target, this.current())) return;
+    const data = terminalKey(button.dataset.key, target.term.modes);
+    if (data !== null) target.term.input(data);
+  }
+}
+
+/** Fit the touch panel to a docked keyboard without changing global page layout. */
+export function bindTerminalViewport(panel, controls) {
+  const viewport = window.visualViewport;
+  let frame;
+  const update = () => {
+    if (panel.hidden || controls.hidden) {
+      panel.style.removeProperty('--terminal-viewport-top');
+      panel.style.removeProperty('--terminal-viewport-bottom');
+      delete panel.dataset.compact;
+      return;
+    }
+    // Magnification belongs to the browser; it must not resize the shared PTY.
+    if (viewport && Math.abs(viewport.scale - 1) > 0.01) return;
+    const top = viewport?.offsetTop || 0;
+    const height = viewport?.height ?? innerHeight;
+    panel.style.setProperty('--terminal-viewport-top', `${top}px`);
+    panel.style.setProperty('--terminal-viewport-bottom', `${Math.max(0, innerHeight - top - height)}px`);
+    panel.toggleAttribute('data-compact', height < 420);
+  };
+  const schedule = () => { cancelAnimationFrame(frame); frame = requestAnimationFrame(update); };
+  viewport?.addEventListener('resize', schedule);
+  viewport?.addEventListener('scroll', schedule);
+  addEventListener('resize', schedule);
+  addEventListener('pageshow', schedule);
+  const observer = new MutationObserver(schedule);
+  for (const element of [panel, controls]) observer.observe(element, { attributes: true, attributeFilter: ['hidden'] });
+  schedule();
+}