@bakapiano/ccsm 0.19.1 → 0.19.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakapiano/ccsm",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "description": "Claude Code Session Manager — Windows web UI to manage many concurrent claude sessions: live list, snapshot/restore, focus existing window, new session in an isolated workspace with repo clones",
   "license": "MIT",
   "main": "server.js",

package/public/assets/cloudflare-color.svg

@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Cloudflare</title><path d="M16.493 17.4c.135-.52.08-.983-.161-1.338-.215-.328-.592-.519-1.05-.519l-8.663-.109a.148.148 0 01-.135-.082c-.027-.054-.027-.109-.027-.163.027-.082.108-.164.189-.164l8.744-.11c1.05-.054 2.153-.9 2.556-1.937l.511-1.31c.027-.055.027-.11.027-.164C17.92 8.91 15.66 7 12.942 7c-2.503 0-4.628 1.638-5.381 3.903a2.432 2.432 0 00-1.803-.491c-1.21.109-2.153 1.092-2.287 2.32-.027.328 0 .628.054.9C1.56 13.688 0 15.326 0 17.319c0 .19.027.355.027.545 0 .082.08.137.161.137h15.983c.08 0 .188-.055.215-.164l.107-.437" fill="#F38020"></path><path d="M19.238 11.75h-.242c-.054 0-.108.054-.135.109l-.35 1.2c-.134.52-.08.983.162 1.338.215.328.592.518 1.05.518l1.855.11c.054 0 .108.027.135.082.027.054.027.109.027.163-.027.082-.108.164-.188.164l-1.91.11c-1.05.054-2.153.9-2.557 1.937l-.134.355c-.027.055.026.137.107.137h6.592c.081 0 .162-.055.162-.137.107-.41.188-.846.188-1.31-.027-2.62-2.153-4.777-4.762-4.777" fill="#FCAD32"></path></svg>

package/public/assets/microsoft-color.svg

@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Azure</title><path d="M11.49 2H2v9.492h9.492V2h-.002z" fill="#F25022"></path><path d="M22 2h-9.492v9.492H22V2z" fill="#7FBA00"></path><path d="M11.49 12.508H2V22h9.492v-9.492h-.002z" fill="#00A4EF"></path><path d="M22 12.508h-9.492V22H22v-9.492z" fill="#FFB900"></path></svg>

package/public/css/layout.css

@@ -115,9 +115,12 @@ body.is-resizing-sidebar .app {
   align-items: center;
   justify-content: space-between;
   gap: var(--s-3);
-  height: calc(40px * var(--anti-zoom, 1));
-  min-height: calc(40px * var(--anti-zoom, 1));
-  max-height: calc(40px * var(--anti-zoom, 1));
+  /* `max(36px, …)` floors the anti-zoom shrink — at heavy page zoom the
+     counter-scale would otherwise collapse the strip past readable
+     (e.g. 250% zoom → ~16px, title text overlaps the action row). */
+  height: max(36px, calc(40px * var(--anti-zoom, 1)));
+  min-height: max(36px, calc(40px * var(--anti-zoom, 1)));
+  max-height: max(36px, calc(40px * var(--anti-zoom, 1)));
   flex-shrink: 0;
   box-sizing: border-box;
   margin: 0 calc(-1 * var(--s-4)) 0;

package/public/css/terminals.css

@@ -494,3 +494,93 @@
   font-size: 11.5px !important;
   color: rgba(232, 227, 213, 0.45) !important;
 }
+
+/* ─── Mobile terminal accessory bar (TerminalKeyBar.js) ───────────────
+   Floats just above the soft keyboard via a JS-set `bottom` offset
+   (visualViewport keyboard height). Styled against the dark terminal
+   palette — it visually belongs to the terminal, not the cream chrome —
+   so it reads as one surface with the xterm canvas above it. */
+.term-keybar {
+  position: fixed;
+  left: 0;
+  right: 0;
+  z-index: 215;                 /* above the mobile FAB (210) */
+  background: #201d19;
+  border-top: 1px solid rgba(232, 227, 213, 0.12);
+  padding: 6px 8px;
+  touch-action: manipulation;   /* kill the 300ms double-tap-zoom delay */
+  user-select: none;
+  -webkit-user-select: none;
+  /* NOT overflow:auto here — that would clip the Ctrl popover (which sits
+     at bottom:100%, above the bar). The horizontal scroll lives on the
+     inner .term-keybar-row instead. */
+}
+/* Inner scroll row — holds the keys; scrolls horizontally if they don't
+   fit, without clipping the popover that escapes the bar upward. */
+.term-keybar-row {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  white-space: nowrap;
+}
+.term-keybar-row::-webkit-scrollbar { display: none; }
+
+.tkb-key {
+  flex: 0 0 auto;
+  min-width: 42px;
+  height: 38px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0 12px;
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1;
+  color: #e8e3d5;
+  background: rgba(232, 227, 213, 0.06);
+  border: 1px solid rgba(232, 227, 213, 0.14);
+  border-radius: 8px;
+  touch-action: manipulation;
+  -webkit-tap-highlight-color: transparent;
+}
+.tkb-key:active,
+.tkb-key.is-active {
+  background: rgba(232, 227, 213, 0.20);
+  border-color: rgba(232, 227, 213, 0.32);
+}
+.tkb-arrow { padding: 0 10px; }
+.tkb-arrow svg { width: 18px; height: 18px; }
+/* S-Tab carries a multi-char label — let it size to content. */
+.tkb-wide { padding: 0 12px; }
+/* The ↵ glyph renders a touch small in the mono stack; bump it so it
+   matches the arrow icons' optical weight. */
+.tkb-glyph { font-size: 17px; line-height: 1; }
+
+/* Ctrl combos — a wrap grid that pops ABOVE the bar (bottom:100%). */
+.term-keybar-pop {
+  position: absolute;
+  bottom: 100%;
+  left: 8px;
+  right: 8px;
+  z-index: 1;                   /* above the key row inside the bar's context */
+  margin-bottom: 6px;
+  display: grid;
+  grid-template-columns: repeat(5, 1fr);
+  gap: 6px;
+  padding: 8px;
+  background: #201d19;
+  border: 1px solid rgba(232, 227, 213, 0.16);
+  border-radius: 10px;
+  box-shadow: 0 -8px 24px -8px rgba(0, 0, 0, 0.5);
+}
+.tkb-combo {
+  flex-direction: column;
+  height: auto;
+  min-width: 0;
+  padding: 7px 4px;
+  gap: 2px;
+}
+.tkb-combo-label { font-family: var(--mono); font-size: 13px; color: #e8e3d5; }
+.tkb-combo-hint  { font-size: 9.5px; color: rgba(232, 227, 213, 0.5); letter-spacing: 0.01em; }

package/public/css/wco.css

@@ -157,9 +157,14 @@ body.is-wco .sidebar-top {
      min-floor on the JS path: the OS knows its own caption height best,
      and over-padding (the previous max(40px, …)) made the chrome look
      visibly chunkier than the rest of the window. */
-  height: calc(var(--titlebar-h, env(titlebar-area-height, 32px)) * var(--anti-zoom, 1));
-  min-height: calc(var(--titlebar-h, env(titlebar-area-height, 32px)) * var(--anti-zoom, 1));
-  max-height: calc(var(--titlebar-h, env(titlebar-area-height, 32px)) * var(--anti-zoom, 1));
+  /* `max(36px, …)` floors the anti-zoom shrink — at heavy page zoom the
+     counter-scale would otherwise collapse the WCO strip past the OS
+     control row height, jamming the brand mark / collapse toggle into
+     the title text. 36px matches the standalone page-title-bar floor
+     in layout.css so both modes degrade to the same minimum. */
+  height: max(36px, calc(var(--titlebar-h, env(titlebar-area-height, 32px)) * var(--anti-zoom, 1)));
+  min-height: max(36px, calc(var(--titlebar-h, env(titlebar-area-height, 32px)) * var(--anti-zoom, 1)));
+  max-height: max(36px, calc(var(--titlebar-h, env(titlebar-area-height, 32px)) * var(--anti-zoom, 1)));
 }
 body.is-wco .sidebar-brand,
 body.is-wco .sidebar-brand-button,

package/public/js/components/TerminalKeyBar.js

@@ -0,0 +1,148 @@
+// Mobile-only terminal accessory bar. The soft keyboard has no Esc / Tab /
+// arrows / Ctrl, which are exactly the keys claude & codex TUIs lean on
+// (menu nav, cancel, autocomplete, interrupt). We float a row of those
+// keys just above the soft keyboard — the same "extra-keys row" pattern
+// Termux / Blink / Termius all settled on.
+//
+// Web has no native keyboard-accessory API, so the bar is a position:fixed
+// element anchored to the top of the keyboard via the visualViewport API:
+// when the keyboard opens, visualViewport.height shrinks and the gap below
+// it (window.innerHeight − vv.height) is the keyboard's height; we park the
+// bar at that offset.
+//
+// Every button MUST preventDefault on pointerdown — otherwise tapping it
+// blurs the terminal's hidden textarea, which dismisses the soft keyboard
+// (and would hide this bar). preventDefault keeps focus on the textarea so
+// the keyboard stays up and we just inject the escape sequence over the WS.
+
+import { html } from '../html.js';
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { isMobile } from '../state.js';
+import { IconChevronUp, IconChevronDown, IconChevronLeft, IconChevronRight } from '../icons.js';
+
+// Ctrl+<letter> is the letter's code & 0x1f. Pre-computed for the combos
+// that actually come up in a REPL / TUI session.
+const CTRL_COMBOS = [
+  { label: '^C', data: '\x03', hint: 'interrupt' },
+  { label: '^D', data: '\x04', hint: 'EOF' },
+  { label: '^Z', data: '\x1a', hint: 'suspend' },
+  { label: '^R', data: '\x12', hint: 'rev-search' },
+  { label: '^L', data: '\x0c', hint: 'clear' },
+  { label: '^A', data: '\x01', hint: 'line start' },
+  { label: '^E', data: '\x05', hint: 'line end' },
+  { label: '^U', data: '\x15', hint: 'kill line' },
+  { label: '^K', data: '\x0b', hint: 'kill to end' },
+  { label: '^W', data: '\x17', hint: 'kill word' },
+];
+
+export function TerminalKeyBar({ send, cliType }) {
+  if (!isMobile.value) return null;
+  const [visible, setVisible] = useState(false);
+  const [kbOffset, setKbOffset] = useState(0);
+  const [ctrlOpen, setCtrlOpen] = useState(false);
+  const gesture = useRef({ x: 0, y: 0, id: null, moved: false });
+
+  // Show only while the terminal textarea holds focus (i.e. keyboard up).
+  // Buttons preventDefault so they never steal focus → no spurious blur
+  // while the bar is in use; focusout only fires on a genuine dismissal.
+  useEffect(() => {
+    const inTerm = (el) => !!(el && el.closest && el.closest('.terminal-host'));
+    const onFocusIn = (e) => { if (inTerm(e.target)) setVisible(true); };
+    const onFocusOut = () => {
+      // Defer one tick so document.activeElement settles to the new target.
+      setTimeout(() => {
+        if (!inTerm(document.activeElement)) { setVisible(false); setCtrlOpen(false); }
+      }, 0);
+    };
+    document.addEventListener('focusin', onFocusIn);
+    document.addEventListener('focusout', onFocusOut);
+    return () => {
+      document.removeEventListener('focusin', onFocusIn);
+      document.removeEventListener('focusout', onFocusOut);
+    };
+  }, []);
+
+  // Track the keyboard's top edge. window.innerHeight stays constant when
+  // the soft keyboard opens (both iOS Safari & Android Chrome with the
+  // default resizes-visual behaviour); vv.height shrinks. The difference
+  // is the keyboard height → the bar's distance from the layout-viewport
+  // bottom.
+  useEffect(() => {
+    const vv = window.visualViewport;
+    if (!vv) return;
+    const sync = () => setKbOffset(Math.max(0, window.innerHeight - vv.height - vv.offsetTop));
+    sync();
+    vv.addEventListener('resize', sync);
+    vv.addEventListener('scroll', sync);
+    return () => { vv.removeEventListener('resize', sync); vv.removeEventListener('scroll', sync); };
+  }, []);
+
+  if (!visible) return null;
+
+  // Insert-newline (composer multi-line). Mirrors TerminalView's Shift/Ctrl
+  // +Enter handler: claude's prompt parses a bare LF as insert-newline;
+  // crossterm-based TUIs (codex/copilot) take ESC+CR i.e. Alt+Enter. This
+  // is the ONLY way to add a newline on a soft keyboard whose Enter submits.
+  const newlineData = cliType === 'claude' ? '\n' : '\x1b\r';
+
+  // Tap-vs-drag discrimination. The key row scrolls horizontally
+  // (overflow-x), so a swipe to scroll it starts on a button — firing the
+  // key on pointerdown meant every scroll-drag injected a keystroke. Track
+  // the pointer from down→up and only fire if it stayed put (a real tap).
+  // One pointer at a time on a touch bar, so a single shared ref is enough.
+  //
+  // preventDefault on pointerdown keeps the terminal's textarea focused (the
+  // button never grabs focus) so the soft keyboard stays up. Scrolling is
+  // governed by touch-action, not this preventDefault, so the row still pans.
+  const DRAG_PX = 8;
+  const onDown = (e) => {
+    gesture.current = { x: e.clientX, y: e.clientY, id: e.pointerId, moved: false };
+    e.preventDefault();
+  };
+  const onMove = (e) => {
+    const g = gesture.current;
+    if (g.id !== e.pointerId || g.moved) return;
+    if (Math.hypot(e.clientX - g.x, e.clientY - g.y) > DRAG_PX) g.moved = true;
+  };
+  const onCancel = () => { gesture.current.moved = true; };
+  // Fire on release, but only for a tap (no drag) and the same pointer.
+  const keyProps = (fn) => ({
+    onPointerDown: onDown,
+    onPointerMove: onMove,
+    onPointerCancel: onCancel,
+    onPointerUp: (e) => {
+      const g = gesture.current;
+      if (g.id !== e.pointerId || g.moved) return;
+      e.preventDefault();
+      fn();
+    },
+  });
+  const sendKey = (data) => keyProps(() => send(data));
+  const ctrlCombo = (data) => keyProps(() => { send(data); setCtrlOpen(false); });
+
+  return html`
+    <div class="term-keybar" style=${`bottom:${kbOffset}px`}>
+      ${ctrlOpen ? html`
+        <div class="term-keybar-pop">
+          ${CTRL_COMBOS.map((c) => html`
+            <button class="tkb-key tkb-combo" key=${c.label}
+                    ...${ctrlCombo(c.data)} title=${c.hint}>
+              <span class="tkb-combo-label">${c.label}</span>
+              <span class="tkb-combo-hint">${c.hint}</span>
+            </button>`)}
+        </div>` : null}
+
+      <div class="term-keybar-row">
+        <button class=${`tkb-key${ctrlOpen ? ' is-active' : ''}`}
+                ...${keyProps(() => setCtrlOpen((v) => !v))}>Ctrl</button>
+        <button class="tkb-key" ...${sendKey('\x1b')}>Esc</button>
+        <button class="tkb-key" ...${sendKey('\t')}>Tab</button>
+        <button class="tkb-key tkb-wide" ...${sendKey('\x1b[Z')}>S-Tab</button>
+        <button class="tkb-key tkb-arrow" ...${sendKey(newlineData)} aria-label="newline"><span class="tkb-glyph">↵</span></button>
+        <button class="tkb-key tkb-arrow" ...${sendKey('\x1b[A')} aria-label="up"><${IconChevronUp} /></button>
+        <button class="tkb-key tkb-arrow" ...${sendKey('\x1b[B')} aria-label="down"><${IconChevronDown} /></button>
+        <button class="tkb-key tkb-arrow" ...${sendKey('\x1b[D')} aria-label="left"><${IconChevronLeft} /></button>
+        <button class="tkb-key tkb-arrow" ...${sendKey('\x1b[C')} aria-label="right"><${IconChevronRight} /></button>
+      </div>
+    </div>`;
+}

package/public/js/components/TerminalView.js

@@ -3,6 +3,7 @@
 // output frames into xterm. Disposes everything on unmount or id change.
 
 import { html } from '../html.js';
+import { Fragment } from 'preact';
 import { useEffect, useRef, useState } from 'preact/hooks';
 import { Terminal } from '@xterm/xterm';
 import { FitAddon } from '@xterm/addon-fit';
@@ -10,6 +11,7 @@ import { WebLinksAddon } from '@xterm/addon-web-links';
 import { ClipboardAddon } from '@xterm/addon-clipboard';
 import { WebglAddon } from '@xterm/addon-webgl';
 import { wsBase, getToken, getDeviceId } from '../backend.js';
+import { TerminalKeyBar } from './TerminalKeyBar.js';
 
 // Dark xterm theme. We give the terminal a near-black ink background to
 // match what claude code's TUI assumes (it paints its own input box +
@@ -44,6 +46,13 @@ export function TerminalView({ terminalId, cliType }) {
   const [displaced, setDisplaced] = useState(false);
   const [reattachNonce, setReattach] = useState(0);
 
+  // Raw escape-sequence injector for the mobile key bar. Reads wsRef at
+  // call time so it stays valid across reattaches without re-binding.
+  const sendInput = (data) => {
+    const ws = wsRef.current;
+    if (ws && ws.readyState === 1) ws.send(JSON.stringify({ type: 'input', data }));
+  };
+
   useEffect(() => {
     if (!terminalId || !hostRef.current) return;
 
@@ -418,5 +427,9 @@ export function TerminalView({ terminalId, cliType }) {
         </div>
       </section>`;
   }
-  return html`<div key="host" ref=${hostRef} class="terminal-host"></div>`;
+  return html`
+    <${Fragment}>
+      <div key="host" ref=${hostRef} class="terminal-host"></div>
+      <${TerminalKeyBar} send=${sendInput} cliType=${cliType} />
+    </${Fragment}>`;
 }

package/public/js/pages/ConfigurePage.js

@@ -25,6 +25,22 @@ import { PageTitleBar } from '../components/PageTitleBar.js';
 import { EntityFormModal } from '../components/EntityFormModal.js';
 import { useDragSort } from '../components/useDragSort.js';
 import { IconPlus, IconPencil, IconClose, IconTerminal, IconFolder, IconBranch, IconRefresh, IconChevronUp, IconChevronDown, IconForCliType, IconClaudeColor, IconCodexColor, IconCopilotColor } from '../icons.js';
+import { parseArgs, formatArgs } from '../util.js';
+
+// Tokenize the three free-form args fields into string[] before they hit
+// the backend. Form values arrive as strings (text inputs) — backend
+// stores arrays. parseArgs handles shell-style quoting so users can type
+// `-Model "claude-opus-4-8"` or `-Path 'C:\some dir\bin'` and get sane
+// argv splitting instead of a literal-quote token.
+function tokenizeCliArgs(v) {
+  const tok = (x) => typeof x === 'string' ? parseArgs(x) : x;
+  return {
+    ...v,
+    args:             tok(v.args),
+    resumeIdArgs:     tok(v.resumeIdArgs),
+    newSessionIdArgs: tok(v.newSessionIdArgs),
+  };
+}
 
 // Type → smart defaults. Choosing a type in the form auto-fills resumeArgs
 // (and command if blank) so users don't need to remember the per-CLI flag.
@@ -72,8 +88,8 @@ function cliFieldsFor({ creating } = {}) {
     },
     { key: 'name', label: 'Name', placeholder: 'My CLI', required: true },
     { key: 'command', label: 'Command', mono: true, placeholder: 'ccp / claude / ...', required: true },
-    { key: 'args', label: 'Args (space-separated)', mono: true, placeholder: '',
-      hint: 'Used on every launch.' },
+    { key: 'args', label: 'Args', mono: true, placeholder: '',
+      hint: 'Used on every launch. Shell-style quoting: -Model "claude-opus-4-8" or -Path \'C:\\some dir\\bin\'.' },
     { key: 'newSessionIdArgs', label: 'New session id args', mono: true, placeholder: '--session-id <id>',
       // Lock for known types — those args are an integration contract
       // with the upstream CLI, not a user knob. Only Type=Other allows
@@ -194,7 +210,7 @@ export function ConfigurePage() {
             id: c.id,
             icon: html`<${Icon} />`,
             primary: c.name,
-            secondary: html`<span class="mono">${c.command}${c.args?.length ? ' ' + c.args.join(' ') : ''}</span>${c.shell && c.shell !== 'direct' ? html` · ${c.shell}` : null}`,
+            secondary: html`<span class="mono">${c.command}${c.args?.length ? ' ' + formatArgs(c.args) : ''}</span>${c.shell && c.shell !== 'direct' ? html` · ${c.shell}` : null}`,
             badges: tags,
             undeletable: c.builtin,
             raw: c,
@@ -291,7 +307,7 @@ export function ConfigurePage() {
         onClose=${close} submitLabel="Create"
         onTest=${(v) => testCli({ command: v.command, shell: v.shell, type: v.type })}
         onSubmit=${async (v) => {
-          try { await createCli(v); setToast(`created CLI · ${v.name}`); }
+          try { await createCli(tokenizeCliArgs(v)); setToast(`created CLI · ${v.name}`); }
           catch (e) { setToast(e.message, 'error'); throw e; }
         }} />` : null}
 
@@ -300,21 +316,15 @@ export function ConfigurePage() {
         readOnlyKeys=${edit.payload.builtin ? ['type'] : []}
         initial=${{
           ...edit.payload,
-          args: (edit.payload.args || []).join(' '),
-          resumeIdArgs: (edit.payload.resumeIdArgs || []).join(' '),
-          newSessionIdArgs: (edit.payload.newSessionIdArgs || []).join(' '),
+          args: formatArgs(edit.payload.args),
+          resumeIdArgs: formatArgs(edit.payload.resumeIdArgs),
+          newSessionIdArgs: formatArgs(edit.payload.newSessionIdArgs),
         }}
         onClose=${close}
         onTest=${(v) => testCli({ command: v.command, shell: v.shell, type: v.type })}
         onSubmit=${async (v) => {
           try {
-            const patch = {
-              ...v,
-              args: typeof v.args === 'string' ? v.args.split(/\s+/).filter(Boolean) : v.args,
-              resumeIdArgs: typeof v.resumeIdArgs === 'string' ? v.resumeIdArgs.split(/\s+/).filter(Boolean) : v.resumeIdArgs,
-              newSessionIdArgs: typeof v.newSessionIdArgs === 'string' ? v.newSessionIdArgs.split(/\s+/).filter(Boolean) : v.newSessionIdArgs,
-            };
-            await updateCli(edit.payload.id, patch);
+            await updateCli(edit.payload.id, tokenizeCliArgs(v));
             setToast('saved');
           } catch (e) { setToast(e.message, 'error'); throw e; }
         }} />` : null}

package/public/js/util.js

@@ -22,3 +22,47 @@ export function displayTitle(label, fallback) {
 export function nowClock() {
   return new Date().toLocaleTimeString(undefined, { hour12: false });
 }
+
+// Shell-style argv tokenizer / formatter used by the CLI editor's
+// args / resumeIdArgs / newSessionIdArgs fields. Modeled on POSIX sh
+// word splitting + bash quoting (the rules every dev already has in
+// muscle memory) — not a full shell parser. Handles:
+//   bare token        -Model         → "-Model"
+//   double-quoted     "a b c"        → "a b c"
+//                                    \\ and \" are escapes inside ""; any
+//                                    other backslash is kept literal, so
+//                                    "C:\Users\foo" survives intact (bash
+//                                    rule, matters for Windows paths).
+//   single-quoted     'a b c'        → "a b c"   literal, no escapes
+//   mixed             -Foo "x y" 'z' → ["-Foo","x y","z"]
+// Anything malformed (unclosed quote, etc.) falls through to a bare
+// best-effort match so the user can keep typing without the field
+// nuking their input mid-type.
+export function parseArgs(input) {
+  const s = String(input || '');
+  const out = [];
+  const re = /'([^']*)'|"((?:[^"\\]|\\.)*)"|(\S+)/g;
+  let m;
+  while ((m = re.exec(s)) !== null) {
+    if (m[1] !== undefined)      out.push(m[1]);
+    else if (m[2] !== undefined) out.push(m[2].replace(/\\([\\"])/g, '$1'));
+    else                         out.push(m[3]);
+  }
+  return out;
+}
+
+// Inverse of parseArgs — used when re-populating the textarea from a
+// stored array. Bare-emit when the token has no shell-significant chars;
+// otherwise double-quote with \" and \\ escapes. Round-trip is stable
+// (parse(format(arr)) === arr) for any string array.
+export function formatArgs(arr) {
+  if (!Array.isArray(arr)) return '';
+  return arr.map((a) => {
+    const s = String(a ?? '');
+    if (s === '') return '""';
+    if (/[\s"'\\`$]/.test(s)) {
+      return '"' + s.replace(/([\\"])/g, '\\$1') + '"';
+    }
+    return s;
+  }).join(' ');
+}