@bakapiano/ccsm 0.20.2 → 0.21.1

package/lib/codexSeed.js

@@ -14,8 +14,8 @@
 // Filename timestamp uses dashes-only (codex's convention), but it's
 // purely cosmetic — codex looks up sessions by UUID, not filename.
 //
-// CODEX_HOME resolution. Wrappers like `cxp` relocate CODEX_HOME to a
-// non-default dir (e.g. %LOCALAPPDATA%\gc2cc\codex-home) so the seed has
+// CODEX_HOME resolution. Some wrappers relocate CODEX_HOME to a
+// non-default dir (e.g. %LOCALAPPDATA%\<wrapper>\codex-home) so the seed has
 // to land there or `resume <id>` won't find it. We probe by running
 // `<cli.command> doctor` once per (command, shell) pair and parsing the
 // "CODEX_HOME ... (dir)" line out of its output. Cached for the life of
@@ -25,6 +25,7 @@ const fs = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
 const { execFile } = require('node:child_process');
+const { spawnEnv } = require('./winPath');
 
 function isoForFilename(d = new Date()) {
   // 2026-05-25T15:39:11 → 2026-05-25T15-39-11 (codex strips ms + colons)
@@ -42,18 +43,32 @@ function execWithTimeout(exe, args, { timeoutMs = 8000 } = {}) {
       windowsHide: true,
       timeout: timeoutMs,
       maxBuffer: 1024 * 1024,
+      // Use the registry-merged user PATH so wrapper commands resolve
+      // even when the long-running server inherited a stale PATH at boot.
+      env: spawnEnv(),
     }, (err, stdout, stderr) => {
       resolve({ err, stdout: String(stdout || ''), stderr: String(stderr || '') });
     });
   });
 }
 
-// Parse `CODEX_HOME    <path> (dir)` out of `codex doctor` output. Codex
-// formats it with variable whitespace; the `(dir)` / `(file)` suffix is
-// the easiest anchor to identify the path end.
+// Pull CODEX_HOME out of a wrapper's `doctor` (or `--version`) output. Two
+// shapes appear, and we must handle BOTH:
+//   1. Diagnostic table:  `CODEX_HOME    <path> (dir)`  — only when `doctor`
+//      fully succeeds. Variable whitespace; the `(dir)`/`(file)` suffix marks
+//      the path end.
+//   2. Wrapper banner:    `CODEX_HOME=<path>`  — printed on EVERY invocation.
+//      Critical because in ccsm's non-interactive spawn `doctor` often exits
+//      non-zero (skipping the table) yet still prints this banner line, so it's
+//      the reliable source. Without it the probe returns null and the seed
+//      lands in ~/.codex instead of the wrapper's relocated home, breaking
+//      `resume <id>` ("No saved session found with ID …").
+// Some wrappers colour the label (`\x1b[7mCODEX_HOME\x1b[0m`); strip ANSI first.
 function parseCodexHomeFromDoctor(text) {
   if (!text) return null;
-  const m = text.match(/\bCODEX_HOME\s+(.+?)\s*\((?:dir|file)\)/);
+  const clean = String(text).replace(/\x1b\[[0-9;]*m/g, '');
+  let m = clean.match(/\bCODEX_HOME\s+(.+?)\s*\((?:dir|file)\)/);   // table form
+  if (!m) m = clean.match(/\bCODEX_HOME=(.+?)\s*$/m);               // banner form
   if (!m) return null;
   const p = m[1].trim();
   return p || null;
@@ -99,7 +114,7 @@ async function probeCodexHome({ command, shell }) {
   const inv = buildDoctorInvocation(command, shell);
   if (!inv) { codexHomeCache.set(key, null); return null; }
   const { stdout, stderr } = await execWithTimeout(inv.exe, inv.args);
-  // Wrappers like cxp print their banner to stderr; doctor itself prints
+  // Some wrappers print their banner to stderr; doctor itself prints
   // the CODEX_HOME line to stdout. Search both to be safe.
   const home = parseCodexHomeFromDoctor(stdout) || parseCodexHomeFromDoctor(stderr);
   codexHomeCache.set(key, home);
@@ -109,7 +124,7 @@ async function probeCodexHome({ command, shell }) {
 async function seedCodexSession({ id, cwd, cli }) {
   if (!id || !cwd) throw new Error('seedCodexSession: id and cwd required');
   // Resolution order:
-  //   1. `<cli.command> doctor` probe (handles wrappers like cxp that
+  //   1. `<cli.command> doctor` probe (handles wrappers that
   //      relocate CODEX_HOME)
   //   2. process.env.CODEX_HOME (global override)
   //   3. ~/.codex (codex's own default)

package/lib/config.js

@@ -70,7 +70,7 @@ const DEFAULTS = {
   // Repos available for cloning into a fresh workspace at launch time.
   //   { name: 'foo', url: 'https://github.com/me/foo.git', defaultSelected: true }
   repos: [],
-  // Pluggable CLIs. Add wrappers like `ccp` (gc2cc) or self-hosted
+  // Pluggable CLIs. Add custom wrappers or self-hosted
   // proxies by appending an entry. defaultCliId picks one for the
   // Launch button when the user doesn't override.
   clis: DEFAULT_CLIS,
@@ -170,8 +170,8 @@ function mergeWithDefaults(partial) {
       type: ['claude', 'codex', 'copilot', 'other'].includes(rest.type) ? rest.type : 'other',
       builtin: !!rest.builtin,
     };
-    // Type-based fallback for non-builtin CLIs (wrappers like `ccp`
-    // that just call claude under the hood). If user picked
+    // Type-based fallback for non-builtin CLIs (wrappers that
+    // just call claude under the hood). If user picked
     // type='claude' but left newSessionIdArgs / resumeIdArgs blank,
     // assume they want the same args claude / copilot / codex use
     // canonically — without this the wrapped CLI gets spawned with

package/lib/localCliSessions.js

@@ -103,16 +103,47 @@ async function discoverClaude() {
   return all;
 }
 
+// Codex sessions can live under a RELOCATED CODEX_HOME. Some wrappers
+// point it at e.g. %LOCALAPPDATA%\<wrapper>\codex-home, so `~/.codex` is empty
+// of the sessions the user actually created. Seeding already honours this
+// (codexSeed.probeCodexHome runs `<cli> doctor`); the import scan must too,
+// or those relocated sessions are invisible in the adopt modal. Gather every
+// candidate `<home>/sessions` dir: each configured codex CLI's detected
+// home, the CODEX_HOME env override, and codex's own ~/.codex default.
+async function codexSessionRoots() {
+  const roots = new Set();
+  try {
+    const { loadConfig } = require('./config');
+    const { probeCodexHome } = require('./codexSeed');
+    const cfg = await loadConfig();
+    const codexClis = (cfg?.clis || []).filter((c) => c.type === 'codex' || c.id === 'codex');
+    for (const c of codexClis) {
+      if (!c.command) continue;
+      let home = null;
+      try { home = await probeCodexHome({ command: c.command, shell: c.shell }); }
+      catch { /* probe is best-effort */ }
+      if (home) roots.add(path.join(home, 'sessions'));
+    }
+  } catch { /* config/probe unavailable — fall through to defaults */ }
+  if (process.env.CODEX_HOME) roots.add(path.join(process.env.CODEX_HOME, 'sessions'));
+  roots.add(path.join(os.homedir(), '.codex', 'sessions'));
+  return [...roots];
+}
+
 async function discoverCodex() {
-  const root = path.join(os.homedir(), '.codex', 'sessions');
+  const roots = await codexSessionRoots();
   const candidates = [];
-  await walkFiles(root, async (filepath, st) => {
-    if (!filepath.endsWith('.jsonl')) return;
-    const base = path.basename(filepath);
-    const m = base.match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i);
-    if (!m) return;
-    candidates.push({ id: m[1], filepath, mtimeMs: st.mtimeMs });
-  });
+  const seen = new Set();   // dedup by session id across homes
+  for (const root of roots) {
+    await walkFiles(root, async (filepath, st) => {
+      if (!filepath.endsWith('.jsonl')) return;
+      const base = path.basename(filepath);
+      const m = base.match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i);
+      if (!m || seen.has(m[1])) return;
+      seen.add(m[1]);
+      candidates.push({ id: m[1], filepath, mtimeMs: st.mtimeMs });
+    });
+  }
   candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
   return candidates;
 }
@@ -121,8 +152,14 @@ async function discoverCodex() {
 // records by parsing each jsonl head. cliType is the discriminator in the
 // returned record.
 async function hydrateJsonl(candidates, cliType) {
+  // codex prepends a big system preamble (<permissions instructions> +
+  // <environment_context>, ~32KB) before the first user message, so 16KB
+  // catches the cwd (line 1) but not the summary. Read a larger head for
+  // codex; its dataset is tiny so the extra bytes are free. claude/copilot
+  // keep the cheap 16KB.
+  const headBytes = cliType === 'codex' ? 48 * 1024 : HEAD_BYTES;
   const parseTasks = candidates.map((c) => async () => {
-    const { cwd, summary } = await parseJsonlHead(c.filepath, c.mtimeMs);
+    const { cwd, summary } = await parseJsonlHead(c.filepath, c.mtimeMs, headBytes);
     if (!cwd) return null;
     return {
       cliType,
@@ -328,74 +365,53 @@ async function listForTypeWithActive(cliType) {
   }));
 }
 
-// Paginated list — the fast path used by the import modal.
-//
-// Strategy:
-//   1. Discover phase = stat all candidates. Cheap, even at 1000+ files.
-//   2. Compute active set in parallel.
-//   3. ALWAYS hydrate every active candidate (they go first, never paged
-//      out — user explicitly wants live sessions visible up top).
-//   4. For non-active, hydrate only `[offset, offset+limit)` sorted mtime
-//      desc. "Load more" = call again with the next offset.
+// Page-based list for the import modal. offset/limit is a window into the
+// full candidate set, ordered active-first then newest-first. Each call
+// returns exactly that page — the modal renders ‹ Prev · X–Y of Z · Next ›.
 //
-// Returns: { sessions, totalActive, totalNonActive, offset, limit, hasMore }
-async function listPaginated(cliType, { offset = 0, limit = 30 } = {}) {
-  // copilot's "discover" is also the parse (no separate jsonl head to read
-  // cheaply), so for now we just list all of it. Codex/Claude get the
-  // proper two-phase treatment.
+// Returns: { sessions, total, totalActive, totalNonActive, offset, limit, hasMore }
+async function listPaginated(cliType, { offset = 0, limit = 20 } = {}) {
+  const now = Date.now();
+
+  // copilot's "discover" is also the parse (no cheap jsonl head), so we
+  // already have the full hydrated list — just slice the requested page.
   if (cliType === 'copilot') {
     const all = await listForTypeWithActive('copilot');
-    all.sort((a, b) => {
-      if (a.active !== b.active) return a.active ? -1 : 1;
-      return b.mtime - a.mtime;
-    });
+    all.sort((a, b) => (a.active !== b.active ? (a.active ? -1 : 1) : b.mtime - a.mtime));
+    const totalActive = all.filter((x) => x.active).length;
     return {
-      sessions: all,
-      totalActive: all.filter((x) => x.active).length,
-      totalNonActive: all.filter((x) => !x.active).length,
-      offset: 0,
-      limit: all.length,
-      hasMore: false,
+      sessions: all.slice(offset, offset + limit),
+      total: all.length,
+      totalActive,
+      totalNonActive: all.length - totalActive,
+      offset, limit,
+      hasMore: offset + limit < all.length,
     };
   }
 
+  // claude / codex: two-phase — cheap discover (stat only), hydrate just the
+  // page's slice.
   const discover = cliType === 'codex' ? discoverCodex : discoverClaude;
-  const [candidates, activeIds] = await Promise.all([
-    discover(),
-    getActiveIds(cliType),
-  ]);
-  // Already sorted mtime desc inside discover.
-  const now = Date.now();
-  const isActiveCand = (c) =>
-    activeIds.has(c.id) || (now - c.mtimeMs) < RECENT_MS;
-  const active = candidates.filter(isActiveCand);
-  const rest = candidates.filter((c) => !isActiveCand(c));
-
-  // Slice non-active to the requested page.
-  const slice = rest.slice(offset, offset + limit);
-
-  // Hydrate active (always all) + slice of non-active.
-  // First page: hydrate both. Later pages: only the slice — frontend
-  // already has the active set from page 0.
-  const toHydrate = offset === 0 ? [...active, ...slice] : slice;
-  const hydrated = await hydrateJsonl(toHydrate, cliType);
-
-  // Stamp active flag back on. Doing it post-hydrate so we don't have
-  // to thread it through hydrateJsonl.
-  const activeIdSet = new Set(active.map((c) => c.id));
+  const [candidates, activeIds] = await Promise.all([discover(), getActiveIds(cliType)]);
+  const isActive = (c) => activeIds.has(c.id) || (now - c.mtimeMs) < RECENT_MS;
+  // Active-first; discover already sorted mtime-desc so a stable partition
+  // keeps newest-first within each group.
+  const ordered = [...candidates.filter(isActive), ...candidates.filter((c) => !isActive(c))];
+  const totalActive = ordered.length - candidates.filter((c) => !isActive(c)).length;
+
+  const slice = ordered.slice(offset, offset + limit);
+  const hydrated = await hydrateJsonl(slice, cliType);
   for (const s of hydrated) {
-    s.active = activeIdSet.has(s.cliSessionId)
-      || activeIds.has(s.cliSessionId)
-      || (now - s.mtime) < RECENT_MS;
+    s.active = activeIds.has(s.cliSessionId) || (now - s.mtime) < RECENT_MS;
   }
 
   return {
     sessions: hydrated,
-    totalActive: active.length,
-    totalNonActive: rest.length,
-    offset,
-    limit,
-    hasMore: offset + limit < rest.length,
+    total: candidates.length,
+    totalActive,
+    totalNonActive: candidates.length - totalActive,
+    offset, limit,
+    hasMore: offset + limit < candidates.length,
   };
 }
 
@@ -442,17 +458,17 @@ function truncate(s, n) {
 // cwd lives in the head of every jsonl (it's part of the per-message
 // envelope), so 16KB is more than enough. First user text usually too;
 // if it's beyond the head we just don't preview, that's fine.
-async function parseJsonlHead(filepath, mtimeMs) {
+async function parseJsonlHead(filepath, mtimeMs, headBytes = HEAD_BYTES) {
   const cached = cacheGet(filepath, mtimeMs);
   if (cached) return cached;
 
   let fh;
   try { fh = await fsp.open(filepath, 'r'); }
   catch { return { cwd: null, summary: '' }; }
-  const buf = Buffer.allocUnsafe(HEAD_BYTES);
+  const buf = Buffer.allocUnsafe(headBytes);
   let bytesRead = 0;
   try {
-    const r = await fh.read(buf, 0, HEAD_BYTES, 0);
+    const r = await fh.read(buf, 0, headBytes, 0);
     bytesRead = r.bytesRead || 0;
   } catch {
     /* leave bytesRead = 0 */
@@ -468,7 +484,7 @@ async function parseJsonlHead(filepath, mtimeMs) {
   const text = buf.slice(0, bytesRead).toString('utf8');
   // Drop the trailing partial line — JSON.parse on it will fail anyway.
   const lines = text.split('\n');
-  if (bytesRead === HEAD_BYTES) lines.pop();
+  if (bytesRead === headBytes) lines.pop();
 
   let cwd = null;
   let summary = '';
@@ -477,10 +493,24 @@ async function parseJsonlHead(filepath, mtimeMs) {
     if (!line) continue;
     let obj;
     try { obj = JSON.parse(line); } catch { continue; }
-    if (!cwd && obj && obj.cwd) cwd = obj.cwd;
-    if (!summary && obj && obj.type === 'user' && obj.message?.content) {
-      const c = obj.message.content;
-      if (typeof c === 'string') summary = truncate(c, SUMMARY_MAX);
+    if (!obj) continue;
+    // cwd —
+    //   claude · top-level { cwd: "..." } on every message envelope
+    //   codex  · session_meta line { payload: { cwd: "..." } }
+    if (!cwd) {
+      if (typeof obj.cwd === 'string') cwd = obj.cwd;
+      else if (obj.payload && typeof obj.payload.cwd === 'string') cwd = obj.payload.cwd;
+    }
+    // first user message (preview) —
+    //   claude · { type:'user', message:{ content:'...' } }
+    //   codex  · { type:'event_msg', payload:{ type:'user_message', message:'...' } }
+    if (!summary) {
+      if (obj.type === 'user' && typeof obj.message?.content === 'string') {
+        summary = truncate(obj.message.content, SUMMARY_MAX);
+      } else if (obj.type === 'event_msg' && obj.payload?.type === 'user_message'
+                 && typeof obj.payload.message === 'string') {
+        summary = truncate(obj.payload.message, SUMMARY_MAX);
+      }
     }
   }
   const v = { cwd, summary };

package/lib/webTerminal.js

@@ -54,7 +54,13 @@ function spawn({ command, args = [], cwd, env, cols = 120, rows = 30, meta = {},
     name: 'xterm-256color',
     cols, rows,
     cwd: cwd ? path.resolve(cwd) : process.cwd(),
-    env: { ...process.env, ...(env || {}) },
+    // Advertise 24-bit colour. xterm.js renders truecolor, and CLIs like
+    // claude paint their diffs with 24-bit DARK red/green backgrounds +
+    // white text when COLORTERM says so. Without it they downgrade to the
+    // bright ANSI-16 red/green backgrounds, which wash the white foreground
+    // out (the "white text gets buried" report). VSCode sets the same on its
+    // terminal PTYs; our ANSI-16 palette already matches VSCode's verbatim.
+    env: { ...process.env, ...(env || {}), COLORTERM: 'truecolor' },
   };
   if (process.platform === 'win32') {
     ptyOpts.useConpty = true;

package/lib/winPath.js

@@ -0,0 +1,67 @@
+'use strict';
+
+// Windows user-PATH merge. A long-running ccsm server inherits whatever PATH
+// it was launched with, which can be stale — e.g. a CLI (or a wrapper for one)
+// installed or put on PATH AFTER the server started. We read the
+// persisted user PATH from the registry and merge it in, then hand the
+// deduped env to every child we spawn. server.js uses this for session
+// launches; codexSeed uses it for the `<cli> doctor` home probe so the wrapper
+// resolves regardless of the parent process's PATH.
+//
+// (server.js keeps its own equivalent inline for the hot spawn path; this
+// module is the shared copy used by lib/ code that can't depend on server.js.)
+
+const { spawnSync } = require('node:child_process');
+
+let _merged = null; // cached for the process lifetime
+
+function buildMergedUserPath() {
+  if (process.platform !== 'win32') return process.env.PATH;
+  try {
+    const r = spawnSync('reg.exe', ['query', 'HKCU\\Environment', '/v', 'PATH'],
+      { encoding: 'utf8', windowsHide: true });
+    if (r.status !== 0 || !r.stdout) return process.env.PATH;
+    const line = r.stdout.split(/\r?\n/).find((l) => /\bPATH\b/i.test(l) && /REG_(EXPAND_)?SZ/i.test(l));
+    if (!line) return process.env.PATH;
+    const m = line.match(/REG_(?:EXPAND_)?SZ\s+(.+)$/);
+    if (!m) return process.env.PATH;
+    // REG_EXPAND_SZ keeps %VAR% literal — expand against the current env.
+    const userPath = m[1].replace(/%([^%]+)%/g, (_, name) => process.env[name] || '');
+    const existing = (process.env.PATH || '').split(';').map((s) => s.trim()).filter(Boolean);
+    const adds = userPath.split(';').map((s) => s.trim()).filter(Boolean);
+    const merged = [];
+    const seen = new Set();
+    for (const p of [...adds, ...existing]) {
+      const k = p.toLowerCase();
+      if (seen.has(k)) continue;
+      seen.add(k);
+      merged.push(p);
+    }
+    return merged.join(';');
+  } catch {
+    return process.env.PATH;
+  }
+}
+
+function mergedUserPath() {
+  if (_merged === null) _merged = buildMergedUserPath();
+  return _merged;
+}
+
+// Fresh env for a child spawn: process.env + extras, every case variant of
+// PATH stripped and replaced by the merged user PATH. Windows resolves the
+// FIRST path-case key in the env block, so a stale inherited `Path` would
+// otherwise shadow our `PATH`.
+function spawnEnv(extraEnv = {}) {
+  const env = { ...process.env, ...extraEnv };
+  if (process.platform === 'win32') {
+    for (const k of Object.keys(env)) {
+      if (k.toLowerCase() === 'path') delete env[k];
+    }
+  }
+  const mp = mergedUserPath();
+  if (mp) env.PATH = mp;
+  return env;
+}
+
+module.exports = { mergedUserPath, spawnEnv, buildMergedUserPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakapiano/ccsm",
-  "version": "0.20.2",
+  "version": "0.21.1",
   "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/css/responsive.css

@@ -66,6 +66,22 @@
      the FAB sits over the terminal corner — leave it; the user can
      scroll the terminal independently. */
 
+  /* Touch scrolling: drive xterm's OWN scrollable .xterm-viewport natively
+     so finger drags get real momentum and never "drop" mid-flick. A
+     JS-intercepted scroll can't: the moment Chrome's compositor decides the
+     drag is a vertical pan it cancels the touch sequence, so the handler
+     only ever sees the opening frames — the "滑一点就断触" symptom. The
+     catch is that the .xterm-screen layer (DOM rows on mobile) sits ON TOP
+     of the viewport and swallows every touch; only the thin scrollbar strip
+     at the right edge reached the viewport, which is exactly the
+     "中间滑不动、侧边能滑" report. Make the screen transparent to pointers so
+     the drag lands on the viewport underneath; pan-y marks it a vertical
+     scroller so the compositor scrolls it directly. (Tap-to-focus is then
+     re-added in JS — see TerminalView — since taps no longer reach xterm's
+     own focus path.) */
+  .app.is-mobile .terminal-host .xterm-screen { pointer-events: none; }
+  .app.is-mobile .terminal-host .xterm-viewport { touch-action: pan-y; }
+
   /* Long inline code (URLs, paths) in the About / Remote bodies break
      out of card edges on a narrow viewport. Let them wrap on any
      character instead of stretching the line. */

package/public/css/terminals.css

@@ -125,49 +125,37 @@
   min-height: 0;
   width: 100%;
   /* IME composition (Chinese/Japanese pinyin) lives in absolutely-positioned
-     .xterm-helper-textarea + .composition-view that grow with the composed
-     string. Near the right edge they overflow the viewport and trigger a
-     horizontal scrollbar that visually "pushes" the layout. Clip here so
-     the overflow is silently absorbed instead of expanding the page.
-     Do NOT touch the textarea/composition-view's own text properties —
-     xterm relies on their single-line behaviour to keep IME events firing
-     correctly (forcing pre-wrap / break-all eats compositionupdate events
+     .xterm-helper-textarea + .composition-view at the cursor. xterm 5.5 caps
+     the view's width to the remaining columns, but as a belt-and-braces guard
+     we still clip here so any residual right-edge overflow is absorbed rather
+     than expanding the page (it used to trigger a horizontal scrollbar that
+     "pushed" the layout). Do NOT touch the textarea/composition-view's own
+     text properties — xterm relies on their single-line behaviour to keep IME
+     events firing (forcing pre-wrap / break-all eats compositionupdate events
      in Chromium and Chinese input stops working entirely). */
   overflow: hidden;
   contain: layout;
 }
-/* While the user is composing (IME), pin the helper textarea to the right
-   edge of the terminal so it grows leftward instead of pushing the layout
-   rightward. Only touches positioning — NOT width / wrap / max-width, which
-   would break Chromium's compositionupdate event flow and stop Chinese
-   input from working. The class is toggled by TerminalView.js. */
-.terminal-host.is-composing .xterm-helper-textarea {
-  left: auto !important;
-  right: 0 !important;
-  text-align: right;
-  /* xterm un-hides the textarea during composition so the user can see the
-     composed string inline. We've moved it to the right edge to stop it
-     pushing layout — but that means the composed pinyin would now visibly
-     appear on the right. Hide its glyphs (caret + text) so the user only
-     sees the OS-native IME candidate popup, which floats independently
-     and is unaffected. */
-  color: transparent !important;
-  caret-color: transparent !important;
-  background: transparent !important;
-  text-shadow: none !important;
-}
-/* xterm also overlays a .composition-view (a small box at the cursor with
-   the in-progress string + a gold caret using THEME.cursor). We can't
-   display:none it — Chromium needs it in the layout tree to keep the IME
-   compositionupdate events flowing — but we can make it visually invisible
-   while leaving it laid out. */
+/* IME composition box. While you're typing pinyin — before committing the
+   Chinese characters — xterm writes the in-progress string into
+   .composition-view at the cursor. VSCode's terminal shows this box in the
+   terminal's own colours; we do the same. An earlier version hid it outright
+   (opacity:0) to dodge a layout push, which is why the typed letters were
+   invisible — but the host's overflow:hidden + contain:layout above already
+   absorb any overflow, and xterm caps the box width, so hiding it was both
+   unnecessary and the bug. The helper textarea is left exactly where xterm
+   puts it (at the cursor, opacity:0) so the OS IME candidate popup anchors
+   correctly — we no longer move or restyle it. */
 .terminal-host .composition-view {
-  opacity: 0 !important;
-  color: transparent !important;
-  background: transparent !important;
-  border-color: transparent !important;
-  box-shadow: none !important;
-  pointer-events: none;
+  /* !important to beat xterm.css's own `.xterm .composition-view`
+     (#000/#FFF, same specificity, loaded after us). var() still re-resolves
+     per theme, so this tracks light/dark automatically. */
+  background: var(--term-surface) !important;
+  color: var(--term-on) !important;
+  border: 1px solid var(--accent);
+  border-radius: 3px;
+  padding: 0 3px;
+  z-index: 5;
 }
 /* Don't override xterm's background — its renderer (canvas/WebGL) assumes
    an opaque surface and ghosts on scroll if we force transparent. The