@oddessentials/agent-guild 0.28.0 → 0.29.0

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.29.0",
   "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/src/manager/folder-browser.mjs

@@ -16,6 +16,20 @@ export function folderSegments(dir, paths = path) {
   return segments;
 }
 
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(\..*)?$/i;
+
+export function folderNameProblem(name, platform = process.platform) {
+  if (!name) return 'Enter a folder name.';
+  if (name === '.' || name === '..') return 'Choose a different folder name.';
+  if (/[/\\]/.test(name)) return 'A folder name cannot contain / or \\.';
+  if (/[\u0000-\u001f]/.test(name)) return 'A folder name cannot contain control characters.';
+  if (platform !== 'win32') return null;
+  if (/[<>:"|?*]/.test(name)) return 'A folder name cannot contain < > : " | ? or *.';
+  if (/[. ]$/.test(name)) return 'A folder name cannot end with a dot or a space.';
+  if (WINDOWS_RESERVED.test(name)) return `Windows reserves the name ${name}.`;
+  return null;
+}
+
 export function createFolderBrowser({ platform = process.platform, home = os.homedir(), limit = 2000, driveTimeoutMs = 500, fsp = fs.promises } = {}) {
   const paths = platform === 'win32' ? path.win32 : path.posix;
 
@@ -59,7 +73,30 @@ export function createFolderBrowser({ platform = process.platform, home = os.hom
     return folders.filter(Boolean).sort(byName);
   }
 
-  return {
+  const browser = {
+    async create(rawParent, rawName) {
+      if (typeof rawParent !== 'string' || !rawParent.trim() || rawParent.includes('\0')) throw failure(400, 'bad_path', 'The folder must be a path.');
+      const name = typeof rawName === 'string' ? rawName.trim() : '';
+      const problem = folderNameProblem(name, platform);
+      if (problem) throw failure(400, 'bad_name', problem);
+      const parent = paths.resolve(rawParent.trim());
+      const missing = () => failure(409, 'folder_missing', `${parent} no longer exists.`);
+      try {
+        if (!(await fsp.stat(parent)).isDirectory()) throw missing();
+      } catch (error) {
+        if (error.status) throw error;
+        throw error.code === 'ENOENT' || error.code === 'ENOTDIR' ? missing() : failure(409, 'folder_unreadable', `Agent Guild cannot read ${parent}.`);
+      }
+      const dir = paths.join(parent, name);
+      try {
+        await fsp.mkdir(dir);
+      } catch (error) {
+        if (error.code === 'EEXIST') throw failure(409, 'folder_exists', `${name} already exists in ${parent}.`);
+        if (error.code === 'ENOENT') throw missing();
+        throw failure(409, 'folder_unwritable', `Agent Guild cannot create ${dir}.`);
+      }
+      return browser.list(dir);
+    },
     async list(raw) {
       if (raw !== undefined && raw !== null && (typeof raw !== 'string' || raw.includes('\0'))) {
         throw failure(400, 'bad_path', 'The folder must be a path.');
@@ -82,4 +119,5 @@ export function createFolderBrowser({ platform = process.platform, home = os.hom
       };
     },
   };
+  return browser;
 }

package/src/manager/server.mjs

@@ -287,6 +287,10 @@ export function createManagerServer({
     if (route === '/folders' && method === 'GET') {
       return sendJson(res, 200, await folderBrowser.list(url.searchParams.get('path') ?? undefined));
     }
+    if (route === '/folders' && method === 'POST') {
+      const { path: parent, name } = await readJsonBody(req);
+      return sendJson(res, 201, await folderBrowser.create(parent, name));
+    }
     if (route === '/upgrade' && method === 'POST') {
       const session = await manager.upgrade();
       return sendJson(res, 201, { session: session.toJSON() });

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';
@@ -22,6 +23,7 @@ const GITHUB_ACCOUNT_KEY = 'agentGuild.githubAccount';
 const CLONE_PARENT_KEY = 'agentGuild.cloneParent';
 const HIDDEN_FOLDERS_KEY = 'agentGuild.showHiddenFolders';
 const RECENT_CWDS_KEY = 'agentGuild.recentCwds';
+const RECENT_CLONE_PARENTS_KEY = 'agentGuild.recentCloneParents';
 const GITHUB_REPO_KEY = 'agentGuild.githubRepo';
 const GITHUB_RECENT_KEY = 'agentGuild.githubRecent';
 const GITHUB_VIEW_KEY = 'agentGuild.githubView';
@@ -124,6 +126,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'));
@@ -765,68 +768,78 @@ async function openWorkingFolder() {
   }
 }
 
-// ---- recent working folders -----------------------------------------------
+// ---- recent folders ---------------------------------------------------------
 
-const recentView = { open: false, typed: false, active: -1 };
+const RECENT_FIELDS = {
+  cwd: { input: 'cwd', list: 'cwd-recent', key: RECENT_CWDS_KEY, pick: (dir) => useFolder(dir) },
+  clone: { input: 'github-parent', list: 'github-parent-recent', key: RECENT_CLONE_PARENTS_KEY, pick: (dir) => setCloneParent(dir) },
+};
+const recentView = { field: null, typed: false, active: -1 };
 
-function recentCwds() {
-  return readRecentFolders(load(RECENT_CWDS_KEY));
+function recentFolders(field) {
+  return readRecentFolders(load(RECENT_FIELDS[field].key));
 }
 
-function rememberCwd(dir) {
-  if (dir) save(RECENT_CWDS_KEY, JSON.stringify(rememberFolder(recentCwds(), dir, { caseless: state.platform === 'win32' })));
+function rememberRecent(field, dir) {
+  if (dir) save(RECENT_FIELDS[field].key, JSON.stringify(rememberFolder(recentFolders(field), dir, { caseless: state.platform === 'win32' })));
 }
 
-function renderRecentCwds() {
-  const input = $('cwd'), list = $('cwd-recent');
-  const shown = recentView.open ? matchFolders(recentCwds(), recentView.typed ? input.value : '') : [];
-  recentView.active = Math.min(recentView.active, shown.length - 1);
+function renderRecent(field) {
+  const { input: inputId, list: listId } = RECENT_FIELDS[field];
+  const input = $(inputId), list = $(listId);
+  const open = recentView.field === field;
+  const shown = open ? matchFolders(recentFolders(field), recentView.typed ? input.value : '') : [];
+  if (open) recentView.active = Math.min(recentView.active, shown.length - 1);
   list.replaceChildren(...shown.map((dir, i) => {
     const option = el('li', 'cwd-recent-option', dir);
-    option.id = `cwd-recent-${i}`;
+    option.id = `${listId}-${i}`;
     option.setAttribute('role', 'option');
-    option.setAttribute('aria-selected', String(i === recentView.active));
+    option.setAttribute('aria-selected', String(open && i === recentView.active));
     option.addEventListener('pointerdown', (e) => e.preventDefault());
-    option.addEventListener('click', () => pickRecentCwd(dir));
+    option.addEventListener('click', () => pickRecent(field, dir));
     return option;
   }));
   list.hidden = !shown.length;
   input.setAttribute('aria-expanded', String(!list.hidden));
-  if (recentView.active >= 0) input.setAttribute('aria-activedescendant', `cwd-recent-${recentView.active}`);
+  if (open && recentView.active >= 0) input.setAttribute('aria-activedescendant', `${listId}-${recentView.active}`);
   else input.removeAttribute('aria-activedescendant');
 }
 
-function showRecentCwds(typed = false) {
-  Object.assign(recentView, { open: true, typed, active: -1 });
-  renderRecentCwds();
+function showRecent(field, typed = false) {
+  const previous = recentView.field;
+  Object.assign(recentView, { field, typed, active: -1 });
+  if (previous && previous !== field) renderRecent(previous);
+  renderRecent(field);
 }
 
-function hideRecentCwds() {
-  Object.assign(recentView, { open: false, active: -1 });
-  renderRecentCwds();
+function hideRecent(field) {
+  if (recentView.field !== field) return;
+  Object.assign(recentView, { field: null, active: -1 });
+  renderRecent(field);
 }
 
-function pickRecentCwd(dir) {
-  hideRecentCwds();
-  useFolder(dir);
+function pickRecent(field, dir) {
+  hideRecent(field);
+  RECENT_FIELDS[field].pick(dir);
 }
 
-function recentCwdKeys(e) {
-  const options = $('cwd-recent').hidden ? [] : [...$('cwd-recent').children];
+function recentKeys(field, e) {
+  const list = $(RECENT_FIELDS[field].list);
+  const options = list.hidden ? [] : [...list.children];
   if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
     e.preventDefault();
-    if (!recentView.open) showRecentCwds();
-    const count = $('cwd-recent').children.length;
+    if (recentView.field !== field) showRecent(field);
+    const count = list.children.length;
     if (!count) return;
     recentView.active = e.key === 'ArrowDown' ? (recentView.active + 1) % count : recentView.active <= 0 ? count - 1 : recentView.active - 1;
-    renderRecentCwds();
-    $(`cwd-recent-${recentView.active}`).scrollIntoView?.({ block: 'nearest' });
+    renderRecent(field);
+    $(`${RECENT_FIELDS[field].list}-${recentView.active}`).scrollIntoView?.({ block: 'nearest' });
   } else if (e.key === 'Enter' && recentView.active >= 0 && options[recentView.active]) {
     e.preventDefault();
-    pickRecentCwd(options[recentView.active].textContent);
+    pickRecent(field, options[recentView.active].textContent);
   } else if (e.key === 'Escape' && options.length) {
     e.preventDefault();
-    hideRecentCwds();
+    hideRecent(field);
   }
 }
 
@@ -852,7 +865,52 @@ function chooseFolder(field) {
   browseTo($(FOLDER_FIELDS[field].input).value.trim());
 }
 
+function showNewFolder(open) {
+  $('folder-new').hidden = !open;
+  $('folder-new-open').setAttribute('aria-expanded', String(open));
+  if (open) $('folder-new-name').value = '';
+  renderFolderBrowser();
+  (open ? $('folder-new-name') : $('folder-new-open')).focus();
+}
+
+async function createFolder(e) {
+  e?.preventDefault();
+  const parent = folderView.listing?.path;
+  const name = $('folder-new-name').value.trim();
+  if (!parent || !name || folderView.loading) return;
+  const request = ++folderView.request;
+  folderView.loading = true;
+  folderView.error = null;
+  renderFolderBrowser();
+  try {
+    const listing = await api('POST', '/folders', { path: parent, name });
+    if (request !== folderView.request) return;
+    folderView.listing = listing;
+    $('folder-filter').value = '';
+    $('folder-new').hidden = true;
+    $('folder-new-open').setAttribute('aria-expanded', 'false');
+  } catch (err) {
+    if (request !== folderView.request) return;
+    if (err instanceof AuthError) {
+      $('folder-browser').close();
+      return showAuth(err.message);
+    }
+    folderView.error = err.message || 'Could not create the folder.';
+  }
+  folderView.loading = false;
+  renderFolderBrowser();
+  if ($('folder-browser').open) ($('folder-new').hidden ? $('folder-use') : $('folder-new-name')).focus();
+}
+
+function newFolderKeys(e) {
+  if (e.key !== 'Escape') return;
+  e.preventDefault();
+  showNewFolder(false);
+}
+
 async function browseTo(dir) {
+  $('folder-new').hidden = true;
+  $('folder-new-open').setAttribute('aria-expanded', 'false');
   const request = ++folderView.request;
   folderView.loading = true;
   folderView.error = null;
@@ -906,6 +964,8 @@ function renderFolderBrowser() {
   status.classList.toggle('error', Boolean(error));
   $('folder-current').textContent = listing?.path ?? '';
   $('folder-use').disabled = loading || !listing;
+  $('folder-new-open').disabled = loading || !listing;
+  $('folder-new-create').disabled = loading || !listing || !$('folder-new-name').value.trim();
 }
 
 function folderBrowserClosed() {
@@ -923,11 +983,9 @@ function useBrowsedFolder() {
   if (!dir || folderView.loading) return;
   const field = folderView.field;
   $('folder-browser').close();
+  rememberRecent(field, dir);
   if (field === 'clone') setCloneParent(dir);
-  else {
-    rememberCwd(dir);
-    useFolder(dir);
-  }
+  else useFolder(dir);
 }
 
 function moveInFolders(e) {
@@ -2416,7 +2474,7 @@ async function startSession(provider, card, { resume, cwd, account = selectedAcc
       ({ session } = await api('POST', '/sessions', { ...body, cwd: working || undefined }));
     }
     upsertSession(session);
-    rememberCwd(session.cwd);
+    rememberRecent('cwd', session.cwd);
     closeHistory({ focusOpener: false });
     openPanel(session.id);
   } catch (err) {
@@ -2626,7 +2684,7 @@ const GITHUB_SCOPES = {
   repo: 'Read and write access to your repositories, private ones included, so you can browse repositories and create or edit issues.',
   'write:public_key': 'Add the SSH key Agent Guild creates for this account.',
 };
-const githubView = { accountId: null, repos: null, reposFor: null, loading: null, error: null, parentError: null, card: null, started: new Set(), announced: new Set() };
+const githubView = { accountId: null, repos: null, reposFor: null, loading: null, error: null, parentError: null, card: null, started: new Map(), announced: new Set() };
 let githubLoading = null;
 
 function el(tag, className, ...children) {
@@ -3091,8 +3149,9 @@ function renderGitHubRepos(github, account, repos) {
 }
 
 async function startClone(account, fullName) {
-  const { session } = await api('POST', '/github/clone', { account: account.id, repo: fullName, parent: cloneParent() });
-  githubView.started.add(session.id);
+  const parent = cloneParent();
+  const { session } = await api('POST', '/github/clone', { account: account.id, repo: fullName, parent });
+  githubView.started.set(session.id, parent);
   upsertSession(session);
   openPanel(session.id);
 }
@@ -3202,8 +3261,10 @@ function noticeClone(s) {
   githubPick.origins.clear();
   if (dockShows('github')) loadRepos();
   if (!githubView.started.has(s.id)) return;
-  if (clonedPath(s)) toast(`Cloned ${s.clone.repo} into ${s.clone.path}.`, 12000, { label: 'Use folder', run: () => useFolder(s.clone.path) });
-  else toast(`Cloning ${s.clone?.repo ?? 'the repository'} did not finish. Its session shows why.`, 8000);
+  if (clonedPath(s)) {
+    rememberRecent('clone', githubView.started.get(s.id));
+    toast(`Cloned ${s.clone.repo} into ${s.clone.path}.`, 12000, { label: 'Use folder', run: () => useFolder(s.clone.path) });
+  } else toast(`Cloning ${s.clone?.repo ?? 'the repository'} did not finish. Its session shows why.`, 8000);
 }
 
 function useFolder(dir) {
@@ -4426,11 +4487,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 +4508,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 +4617,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 +4629,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 +4680,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 +4701,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 +4716,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 +4813,7 @@ function restorePanes() {
 }
 
 function updatePanel() {
+  terminalControls.refresh();
   renderVoice();
   const s = state.sessions.get(state.activeId);
   if (!s) return;
@@ -5222,7 +5327,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;
@@ -5536,11 +5646,13 @@ $('panel-stop').addEventListener('click', () => {
 });
 $('cwd').value = load(CWD_KEY) || '';
 $('cwd-pick').addEventListener('click', firstClick(() => chooseFolder('cwd')));
-$('cwd').addEventListener('focus', () => showRecentCwds());
-$('cwd').addEventListener('click', () => { if (!recentView.open) showRecentCwds(); });
-$('cwd').addEventListener('input', () => showRecentCwds(true));
-$('cwd').addEventListener('blur', hideRecentCwds);
-$('cwd').addEventListener('keydown', recentCwdKeys);
+for (const [field, { input }] of Object.entries(RECENT_FIELDS)) {
+  $(input).addEventListener('focus', () => showRecent(field));
+  $(input).addEventListener('click', () => { if (recentView.field !== field) showRecent(field); });
+  $(input).addEventListener('input', () => showRecent(field, true));
+  $(input).addEventListener('blur', () => hideRecent(field));
+  $(input).addEventListener('keydown', (e) => recentKeys(field, e));
+}
 $('folder-cancel').addEventListener('click', () => $('folder-browser').close());
 $('folder-browser').addEventListener('click', (e) => { if (e.target === $('folder-browser')) $('folder-browser').close(); });
 $('folder-browser').addEventListener('close', folderBrowserClosed);
@@ -5554,6 +5666,11 @@ $('folder-hidden').addEventListener('change', (e) => {
   renderFolderBrowser();
 });
 $('folder-use').addEventListener('click', useBrowsedFolder);
+$('folder-new-open').addEventListener('click', () => showNewFolder($('folder-new').hidden));
+$('folder-new-cancel').addEventListener('click', () => showNewFolder(false));
+$('folder-new').addEventListener('submit', createFolder);
+$('folder-new-name').addEventListener('input', renderFolderBrowser);
+$('folder-new-name').addEventListener('keydown', newFolderKeys);
 $('cwd-open').addEventListener('click', firstClick(openWorkingFolder));
 try { state.accounts = JSON.parse(load(ACCOUNTS_KEY)) || {}; } catch { state.accounts = {}; }
 try { state.shellPicks = JSON.parse(load(SHELLS_KEY)) || {}; } catch { state.shellPicks = {}; }
@@ -5570,8 +5687,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>
 
@@ -236,7 +244,8 @@
       <div id="github-clone-into" class="history-form github-form">
         <label for="github-parent">Clone into</label>
         <div class="cwd-field single">
-          <input id="github-parent" type="text" placeholder="Folder that holds your clones" spellcheck="false" autocomplete="off">
+          <input id="github-parent" type="text" placeholder="Folder that holds your clones" spellcheck="false" autocomplete="off" role="combobox" aria-autocomplete="list" aria-expanded="false" aria-controls="github-parent-recent">
+          <ul id="github-parent-recent" class="cwd-recent above" role="listbox" aria-label="Recent clone folders" hidden></ul>
           <div class="cwd-tools">
             <button id="github-parent-pick" class="cwd-tool" type="button" aria-label="Choose a folder…" title="Connect to the session manager to choose folders" disabled>
               <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
@@ -426,7 +435,13 @@
       <button id="folder-up" class="btn" type="button">Up</button>
       <button id="folder-home" class="btn folder-chip" type="button">Home</button>
       <div id="folder-roots" class="folder-roots"></div>
+      <button id="folder-new-open" class="btn folder-new-open" type="button" aria-expanded="false" aria-controls="folder-new">New folder</button>
     </div>
+    <form id="folder-new" class="history-tools folder-new" hidden>
+      <input id="folder-new-name" type="text" placeholder="New folder name" aria-label="New folder name" spellcheck="false" autocomplete="off" autocapitalize="off" enterkeyhint="done">
+      <button id="folder-new-create" class="btn primary" type="submit">Create</button>
+      <button id="folder-new-cancel" class="btn" type="button">Cancel</button>
+    </form>
     <div class="history-tools">
       <input id="folder-filter" type="search" placeholder="Filter folders" aria-label="Filter folders" spellcheck="false" autocomplete="off">
       <label class="history-here"><input id="folder-hidden" type="checkbox"><span>Show hidden</span></label>

package/web/skins/gnomeland/skin.css

@@ -243,7 +243,7 @@
   }
   .btn.primary:hover { filter: brightness(1.08); box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25), inset 0 0 0 1px rgba(233, 196, 122, 0.6), 0 5px 16px rgba(40, 70, 30, 0.35); }
   .btn.danger:hover { border-color: var(--danger); box-shadow: 0 0 0 3px color-mix(in srgb, var(--danger) 14%, transparent); }
-  .cwd input, .auth input, .history-tools input[type="search"], .history-form input, .github-fields input, .github-fields select, .notes-text { background: var(--panel-strong); }
+  .cwd input, .auth input, .history-tools input[type="search"], .folder-new input, .history-form input, .github-fields input, .github-fields select, .notes-text { background: var(--panel-strong); }
 
   .models, .news-panel, .dock, .auth, .news-latest, .menu:popover-open { background: var(--panel-strong); backdrop-filter: blur(16px); }
   .models, .news-panel { box-shadow: var(--dialog-shadow); }
@@ -362,7 +362,7 @@
   .btn.primary { border-color: #6a8f3a; background: linear-gradient(#55924a, #35662f); box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.2), inset 0 0 0 1px rgba(233, 196, 122, 0.3), 0 0 16px rgba(110, 170, 80, 0.3); }
   .btn.danger { color: #f59a8c; }
   .btn.danger:hover { border-color: #b8402f; box-shadow: 0 0 12px rgba(240, 123, 106, 0.3); }
-  .cwd input, .auth input, .history-tools input[type="search"], .history-form input, .github-fields input, .github-fields select, .notes-text { border-color: #4a3824; background: rgba(10, 7, 4, 0.7); }
+  .cwd input, .auth input, .history-tools input[type="search"], .folder-new input, .history-form input, .github-fields input, .github-fields select, .notes-text { border-color: #4a3824; background: rgba(10, 7, 4, 0.7); }
 
   .models::backdrop, .news-panel::backdrop { background: rgba(6, 4, 2, 0.66); }
   .terminal-panel { border-color: #5a4226; box-shadow: 0 0 0 1px rgba(233, 196, 122, 0.06), 0 30px 80px rgba(0, 0, 0, 0.7); }

package/web/skins/goblinville/skin.css

@@ -249,7 +249,7 @@
   }
   .btn.primary:hover { filter: brightness(1.08); box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25), inset 0 0 0 1px rgba(227, 166, 119, 0.6), 0 5px 16px rgba(20, 70, 56, 0.35); }
   .btn.danger:hover { border-color: var(--danger); box-shadow: 0 0 0 3px color-mix(in srgb, var(--danger) 14%, transparent); }
-  .cwd input, .auth input, .history-tools input[type="search"], .history-form input, .github-fields input, .github-fields select, .notes-text { background: var(--panel-strong); }
+  .cwd input, .auth input, .history-tools input[type="search"], .folder-new input, .history-form input, .github-fields input, .github-fields select, .notes-text { background: var(--panel-strong); }
 
   .models, .news-panel, .dock, .auth, .news-latest, .menu:popover-open { background: var(--panel-strong); backdrop-filter: blur(16px); }
   .models, .news-panel { box-shadow: var(--dialog-shadow); }
@@ -369,7 +369,7 @@
   .btn.primary { border-color: #3f9a80; background: linear-gradient(#2f8a73, #1b5a4b); box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.2), inset 0 0 0 1px rgba(227, 166, 119, 0.3), 0 0 16px rgba(60, 170, 140, 0.3); }
   .btn.danger { color: #f59a8c; }
   .btn.danger:hover { border-color: #b8402f; box-shadow: 0 0 12px rgba(240, 123, 106, 0.3); }
-  .cwd input, .auth input, .history-tools input[type="search"], .history-form input, .github-fields input, .github-fields select, .notes-text { border-color: #3a4a3f; background: rgba(5, 8, 6, 0.7); }
+  .cwd input, .auth input, .history-tools input[type="search"], .folder-new input, .history-form input, .github-fields input, .github-fields select, .notes-text { border-color: #3a4a3f; background: rgba(5, 8, 6, 0.7); }
 
   .models::backdrop, .news-panel::backdrop { background: rgba(2, 5, 3, 0.66); }
   .terminal-panel { border-color: #5a3a22; box-shadow: 0 0 0 1px rgba(227, 166, 119, 0.06), 0 30px 80px rgba(0, 0, 0, 0.7); }

package/web/skins/grove/skin.css

@@ -244,7 +244,7 @@
   }
   .btn.primary:hover { filter: brightness(1.07); box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.22), 0 6px 20px rgba(45, 107, 69, 0.36); }
   .btn.danger:hover { border-color: var(--danger); box-shadow: 0 0 0 3px color-mix(in srgb, var(--danger) 14%, transparent); }
-  .cwd input, .auth input, .history-tools input[type="search"], .history-form input, .github-fields input, .github-fields select, .notes-text { background: var(--paper-strong); }
+  .cwd input, .auth input, .history-tools input[type="search"], .folder-new input, .history-form input, .github-fields input, .github-fields select, .notes-text { background: var(--paper-strong); }
 
   .models, .news-panel, .dock, .auth, .news-latest, .menu:popover-open { background: var(--paper-strong); backdrop-filter: blur(16px); }
   .models, .news-panel { box-shadow: var(--dialog-shadow); }
@@ -371,7 +371,7 @@
   .btn.primary { background: linear-gradient(135deg, #4a8c5e, #2a6340); box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.18), 0 0 18px rgba(80, 160, 105, 0.35); }
   .btn.danger { color: #ff9a8e; }
   .btn.danger:hover { border-color: #b8443a; box-shadow: 0 0 12px rgba(240, 122, 108, 0.3); }
-  .cwd input, .auth input, .history-tools input[type="search"], .history-form input, .github-fields input, .github-fields select, .notes-text { border-color: #2e4a3d; background: rgba(4, 10, 8, 0.7); }
+  .cwd input, .auth input, .history-tools input[type="search"], .folder-new input, .history-form input, .github-fields input, .github-fields select, .notes-text { border-color: #2e4a3d; background: rgba(4, 10, 8, 0.7); }
 
   .models::backdrop, .news-panel::backdrop { background: rgba(2, 6, 5, 0.66); }
   .terminal-panel { border-color: #2e4a3d; box-shadow: 0 0 0 1px rgba(140, 210, 160, 0.06), 0 30px 80px rgba(0, 0, 0, 0.7); }

package/web/skins/guild/skin.css

@@ -480,7 +480,7 @@
   }
   .btn.primary:hover { border-color: #b8892f; filter: brightness(1.08); }
   .btn.danger:hover { border-color: #c4625d; }
-  .cwd input, .auth input, .history-tools input[type="search"], .history-form input, .notes-text {
+  .cwd input, .auth input, .history-tools input[type="search"], .folder-new input, .history-form input, .notes-text {
     border-color: #dccba5; background: #fffdf8; box-shadow: inset 0 1px 2px rgba(70, 48, 12, 0.06);
   }
   .auth { border-color: #e4d6b6; box-shadow: var(--card-shadow); }

package/web/skins/orbital/skin.css

@@ -246,7 +246,7 @@
   }
   .btn.primary:hover { filter: brightness(1.08); box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.25), 0 6px 20px rgba(122, 79, 232, 0.4); }
   .btn.danger:hover { border-color: var(--danger); box-shadow: 0 0 0 3px color-mix(in srgb, var(--danger) 14%, transparent); }
-  .cwd input, .auth input, .history-tools input[type="search"], .history-form input, .github-fields input, .github-fields select, .notes-text { background: var(--glass-strong); }
+  .cwd input, .auth input, .history-tools input[type="search"], .folder-new input, .history-form input, .github-fields input, .github-fields select, .notes-text { background: var(--glass-strong); }
 
   .models, .news-panel, .dock, .auth, .news-latest, .menu:popover-open { background: var(--glass-strong); backdrop-filter: blur(16px); }
   .models, .news-panel { box-shadow: var(--dialog-shadow); }
@@ -367,7 +367,7 @@
   .btn.primary { box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.22), 0 0 18px rgba(106, 92, 240, 0.45); }
   .btn.danger { color: #ff8c9c; }
   .btn.danger:hover { border-color: #c23a52; box-shadow: 0 0 12px rgba(255, 107, 129, 0.3); }
-  .cwd input, .auth input, .history-tools input[type="search"], .history-form input, .github-fields input, .github-fields select, .notes-text { border-color: #26355c; background: rgba(4, 7, 16, 0.7); }
+  .cwd input, .auth input, .history-tools input[type="search"], .folder-new input, .history-form input, .github-fields input, .github-fields select, .notes-text { border-color: #26355c; background: rgba(4, 7, 16, 0.7); }
 
   .models::backdrop, .news-panel::backdrop { background: rgba(2, 4, 10, 0.66); }
   .terminal-panel { border-color: #2a3a66; box-shadow: 0 0 0 1px rgba(120, 170, 255, 0.06), 0 30px 80px rgba(0, 0, 0, 0.7); }

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; }
@@ -724,7 +749,7 @@ a.news-link:visited { color: var(--muted); }
 }
 
 .history-tools { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; padding: 10px 14px 0; }
-.history-tools input[type="search"] {
+.history-tools input[type="search"], .folder-new input {
   flex: 1 1 220px; min-width: 0; padding: 7px 10px; border-radius: var(--radius); border: 1px solid var(--border);
   background: var(--surface); color: var(--text); font: inherit; font-size: 0.9rem;
 }
@@ -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; }
@@ -1010,6 +1035,9 @@ a.btn.github-out::after {
 .folder-crumb:focus-visible, .folder-row:focus-visible { outline: 2px solid var(--focus); outline-offset: -2px; }
 .folder-places, .folder-roots { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; }
 .folder-places .btn { min-height: 36px; }
+.folder-new-open { margin-left: auto; }
+.folder-new { flex-wrap: nowrap; }
+.folder-new input { flex: 1; min-width: 0; }
 .folder-list { display: flex; flex-direction: column; }
 .folder-row {
   display: flex; align-items: center; gap: 10px; min-height: 44px; padding: 8px; border: 0; border-bottom: 1px solid var(--border);
@@ -1022,6 +1050,9 @@ a.btn.github-out::after {
 .folder-footer { justify-content: space-between; }
 .folder-current { flex: 1; min-width: 0; font-family: ui-monospace, "Cascadia Code", "SF Mono", Menlo, Consolas, monospace; font-size: 0.8rem; overflow-wrap: anywhere; }
 .folder-footer .btn { min-height: 42px; }
+@media (pointer: coarse), (max-width: 640px) {
+  .folder-places .btn, .folder-new .btn, .folder-new input, .folder-footer .btn, #folder-cancel { min-height: 44px; }
+}
 .cwd-recent {
   position: absolute; top: calc(100% + 4px); left: 0; right: 0; z-index: 5; margin: 0; padding: 4px; list-style: none;
   border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); box-shadow: 0 12px 30px rgba(0, 0, 0, 0.3);
@@ -1031,4 +1062,5 @@ a.btn.github-out::after {
   color: var(--text); font-family: ui-monospace, "Cascadia Code", "SF Mono", Menlo, Consolas, monospace; font-size: 0.82rem; overflow-wrap: anywhere; cursor: pointer;
 }
 .cwd-recent-option:hover, .cwd-recent-option[aria-selected="true"] { background: color-mix(in srgb, var(--accent) 14%, transparent); }
-@media (pointer: coarse) { .cwd-recent-option { min-height: 46px; } }
+@media (pointer: coarse), (max-width: 640px) { .cwd-recent-option { min-height: 46px; } }
+.cwd-recent.above { top: auto; bottom: calc(100% + 4px); }

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