npm - create-walle - Versions diffs - 0.9.30 → 0.9.32 - Mend

create-walle 0.9.30 → 0.9.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (112) hide show

package/template/claude-task-manager/docs/resume-ux-redesign.html ADDED Viewed

@@ -0,0 +1,493 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CTM Resume UX — Redesign Proposal</title>
+<style>
+  :root{
+    --bg:#0f1115; --panel:#171a21; --panel2:#1d212b; --ink:#e6e9ef; --muted:#9aa3b2;
+    --line:#2a2f3a; --accent:#5b9cff; --good:#3ecf8e; --warn:#ffb454; --bad:#ff6b6b;
+    --run:#3ecf8e; --needs:#ffb454; --idle:#7d869c; --resume:#5b9cff; --review:#b388ff;
+    --mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
+    --sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+  }
+  *{box-sizing:border-box}
+  html{scroll-behavior:smooth}
+  body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans);line-height:1.6;font-size:16px}
+  .wrap{max-width:1080px;margin:0 auto;padding:0 24px 120px}
+  header.hero{padding:56px 24px 40px;border-bottom:1px solid var(--line);background:
+    radial-gradient(900px 300px at 20% -10%, rgba(91,156,255,.18), transparent 60%),
+    radial-gradient(700px 260px at 90% -20%, rgba(62,207,142,.14), transparent 60%);}
+  .hero .wrap{padding-bottom:0}
+  .eyebrow{font-family:var(--mono);font-size:12px;letter-spacing:.18em;text-transform:uppercase;color:var(--accent);margin:0 0 12px}
+  h1{font-size:38px;line-height:1.15;margin:0 0 12px;font-weight:700;letter-spacing:-.02em}
+  .sub{font-size:18px;color:var(--muted);max-width:780px;margin:0}
+  .meta{margin-top:20px;display:flex;gap:10px;flex-wrap:wrap}
+  .pill{font-family:var(--mono);font-size:12px;border:1px solid var(--line);background:var(--panel);
+    padding:5px 10px;border-radius:999px;color:var(--muted)}
+  nav.toc{position:sticky;top:0;z-index:20;background:rgba(15,17,21,.88);backdrop-filter:blur(8px);
+    border-bottom:1px solid var(--line);padding:10px 0}
+  nav.toc .wrap{padding-top:0;padding-bottom:0;display:flex;gap:6px;flex-wrap:wrap}
+  nav.toc a{font-size:13px;color:var(--muted);text-decoration:none;padding:6px 10px;border-radius:8px;white-space:nowrap}
+  nav.toc a:hover{color:var(--ink);background:var(--panel)}
+  section{padding-top:48px}
+  h2{font-size:26px;margin:0 0 6px;letter-spacing:-.01em}
+  h2 .num{font-family:var(--mono);color:var(--accent);font-size:18px;margin-right:10px}
+  h3{font-size:18px;margin:28px 0 8px;color:var(--ink)}
+  p{margin:12px 0}
+  .lead{font-size:17px;color:#cbd2de}
+  code,kbd{font-family:var(--mono);font-size:.88em;background:var(--panel2);padding:1px 6px;border-radius:5px;border:1px solid var(--line)}
+  .card{background:var(--panel);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:18px 0}
+  .card.tight{padding:14px 18px}
+  .grid2{display:grid;grid-template-columns:1fr 1fr;gap:16px}
+  .grid3{display:grid;grid-template-columns:1fr 1fr 1fr;gap:16px}
+  @media(max-width:780px){.grid2,.grid3{grid-template-columns:1fr}}
+  .callout{border-left:3px solid var(--accent);background:var(--panel2);padding:14px 18px;border-radius:0 10px 10px 0;margin:16px 0}
+  .callout.bad{border-color:var(--bad)} .callout.good{border-color:var(--good)} .callout.warn{border-color:var(--warn)}
+  .callout h4{margin:0 0 6px;font-size:14px;letter-spacing:.04em;text-transform:uppercase;color:var(--muted)}
+  .tag{display:inline-block;font-family:var(--mono);font-size:11px;padding:2px 8px;border-radius:6px;border:1px solid var(--line);color:var(--muted)}
+  .tag.run{color:var(--run);border-color:rgba(62,207,142,.4)}
+  .tag.needs{color:var(--needs);border-color:rgba(255,180,84,.4)}
+  .tag.idle{color:var(--idle)}
+  .tag.resume{color:var(--resume);border-color:rgba(91,156,255,.4)}
+  .tag.review{color:var(--review);border-color:rgba(179,136,255,.4)}
+  .tag.srv{color:#7fd3ff;border-color:rgba(127,211,255,.3)}
+  .tag.cli{color:#ffd27f;border-color:rgba(255,210,127,.3)}
+  table{width:100%;border-collapse:collapse;font-size:13.5px;margin:12px 0}
+  th,td{text-align:left;padding:9px 10px;border-bottom:1px solid var(--line);vertical-align:top}
+  th{color:var(--muted);font-weight:600;font-size:12px;letter-spacing:.04em;text-transform:uppercase;position:sticky;top:42px;background:var(--panel)}
+  tbody tr:hover{background:var(--panel2)}
+  td code{font-size:12px;white-space:nowrap}
+  details{border:1px solid var(--line);border-radius:12px;background:var(--panel);margin:16px 0;overflow:hidden}
+  details>summary{cursor:pointer;padding:14px 18px;font-weight:600;list-style:none;display:flex;align-items:center;gap:10px}
+  details>summary::-webkit-details-marker{display:none}
+  details>summary::before{content:"▶";color:var(--accent);font-size:11px;transition:transform .15s}
+  details[open]>summary::before{transform:rotate(90deg)}
+  details .body{padding:0 18px 16px;border-top:1px solid var(--line)}
+  .legend{display:flex;gap:14px;flex-wrap:wrap;margin:10px 0;font-size:13px;color:var(--muted)}
+  .legend span{display:inline-flex;align-items:center;gap:6px}
+  .dot{width:10px;height:10px;border-radius:3px;display:inline-block}
+  .ref{font-family:var(--mono);font-size:12px;color:var(--muted)}
+  ul.clean{margin:10px 0;padding-left:20px} ul.clean li{margin:6px 0}
+  .kicker{font-family:var(--mono);font-size:12px;color:var(--accent);text-transform:uppercase;letter-spacing:.14em;margin:0 0 4px}
+  .footnote{color:var(--muted);font-size:13px}
+  a.src{color:var(--accent);text-decoration:none;border-bottom:1px dotted rgba(91,156,255,.5)}
+  a.src:hover{border-bottom-style:solid}
+  hr.sep{border:0;border-top:1px solid var(--line);margin:40px 0}
+  .phase{display:flex;gap:14px;margin:14px 0;align-items:flex-start}
+  .phase .badge{flex:0 0 auto;font-family:var(--mono);font-weight:700;font-size:13px;width:40px;height:40px;border-radius:10px;
+    display:grid;place-items:center;background:var(--panel2);border:1px solid var(--line);color:var(--accent)}
+  .phase .pbody{flex:1}
+  .phase h4{margin:2px 0 4px;font-size:16px}
+  .num-stat{display:flex;gap:18px;flex-wrap:wrap;margin:8px 0}
+  .num-stat .n{font-size:30px;font-weight:700;line-height:1;color:var(--bad)}
+  .num-stat .l{font-size:12px;color:var(--muted);text-transform:uppercase;letter-spacing:.06em}
+  .num-stat>div{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:14px 16px;min-width:130px}
+  /* resume-doc specifics */
+  pre.ascii{font-family:var(--mono);font-size:12.5px;line-height:1.45;background:#0b0d11;border:1px solid var(--line);
+    border-radius:12px;padding:16px 18px;overflow:auto;color:#cbd2de;margin:14px 0}
+  .term{font-family:var(--mono);font-size:12.5px;line-height:1.5;background:#0b0d11;border:1px solid var(--line);
+    border-radius:12px;overflow:hidden;margin:14px 0}
+  .term .bar{display:flex;align-items:center;gap:8px;padding:8px 12px;background:#13161c;border-bottom:1px solid var(--line);
+    font-size:11.5px;color:var(--muted)}
+  .term .bar .dots{display:flex;gap:5px}
+  .term .bar .dots i{width:9px;height:9px;border-radius:50%;display:inline-block}
+  .term .body{padding:14px 16px;white-space:pre-wrap;color:#cbd2de}
+  .term .dim{color:#5a6475}
+  .term .blank{color:#3a4150}
+  .term .foot{color:var(--accent)}
+  .term .skh{color:var(--resume);font-weight:600}
+  @keyframes blink{0%,100%{opacity:.45}50%{opacity:1}}
+  .pulse{animation:blink 1.6s ease-in-out infinite}
+  .badtag,.goodtag{font-family:var(--mono);font-size:11px;padding:2px 8px;border-radius:6px}
+  .badtag{color:var(--bad);border:1px solid rgba(255,107,107,.4)}
+  .goodtag{color:var(--good);border:1px solid rgba(62,207,142,.4)}
+  .statebox{display:inline-block;font-family:var(--mono);font-size:12px;padding:4px 10px;border-radius:8px;
+    border:1px solid var(--line);background:var(--panel2);color:var(--ink);margin:2px}
+  .statebox.live{color:var(--run);border-color:rgba(62,207,142,.5)}
+  .statebox.slow{color:var(--warn);border-color:rgba(255,180,84,.5)}
+  .statebox.err{color:var(--bad);border-color:rgba(255,107,107,.5)}
+  .arrow{color:var(--accent);font-family:var(--mono)}
+</style>
+</head>
+<body>
+<header class="hero">
+  <div class="wrap">
+    <p class="eyebrow">CTM · Design Proposal · 2026-06-23</p>
+    <h1>Resuming, Redesigned</h1>
+    <p class="sub">Reopen a Claude Code or Codex session and you wait — staring at a blank terminal or a lone <em style="color:var(--resume)">Resuming session…</em> line — with no idea what's happening or how long it will take. Yet the conversation you're resuming is <strong>already composed on the server</strong>. This document maps the current resume mechanism for both agents, explains why it feels broken, and proposes a single-source-of-truth <strong>skeleton-preview</strong> redesign that shows you your work instantly.</p>
+    <div class="meta">
+      <span class="pill">Resume UX</span>
+      <span class="pill">Claude Code + Codex</span>
+      <span class="pill">Skeleton preview</span>
+      <span class="pill">One resume state machine</span>
+      <span class="pill">Proposal — review before implementation</span>
+    </div>
+  </div>
+</header>
+<nav class="toc">
+  <div class="wrap">
+    <a href="#today">1 · What you see today</a>
+    <a href="#current">2 · Current mechanism</a>
+    <a href="#problems">3 · Why it's bad</a>
+    <a href="#principles">4 · Principles</a>
+    <a href="#design">5 · Proposed design</a>
+    <a href="#plan">6 · Implementation plan</a>
+    <a href="#verify">7 · Verification</a>
+  </div>
+</nav>
+<div class="wrap">
+<!-- ============================================================ -->
+<section id="today">
+  <p class="kicker">The experience</p>
+  <h2><span class="num">1</span>What you see today</h2>
+  <p class="lead">Three things go wrong, and they compound.</p>
+  <div class="num-stat">
+    <div><div class="n">~10</div><div class="l">functions own the resume UI</div></div>
+    <div><div class="n">4</div><div class="l">redundant "is resuming" flags</div></div>
+    <div><div class="n">2</div><div class="l">separate overlay systems</div></div>
+    <div><div class="n">3</div><div class="l">places guarding one blank-page race</div></div>
+  </div>
+  <div class="grid3">
+    <div class="card tight">
+      <span class="badtag">BLANK</span>
+      <h3 style="margin-top:10px">A blank page</h3>
+      <p class="footnote">Large Codex sessions go silent for minutes while the rollout loads into memory. A blank snapshot can slip through and wipe the loading state, leaving an empty terminal until the load finishes.</p>
+    </div>
+    <div class="card tight">
+      <span class="badtag">SPINNER</span>
+      <h3 style="margin-top:10px">A lonely "Resuming…"</h3>
+      <p class="footnote">A placeholder line plus a pulsing overlay — both saying the same thing — float over emptiness. No preview of the conversation, no sense of progress.</p>
+    </div>
+    <div class="card tight">
+      <span class="badtag">JITTER</span>
+      <h3 style="margin-top:10px">An unpredictable wait</h3>
+      <p class="footnote">The wait stutters through a chain of timers (250–2500&nbsp;ms, 600&nbsp;ms, 8×700&nbsp;ms, 15&nbsp;s). Irregular delay is harder to tolerate than a steady one.</p>
+    </div>
+  </div>
+  <div class="callout">
+    <h4>The core irony</h4>
+    <p style="margin:0">The server has <strong>already rendered the prior conversation</strong> by the time the user is staring at nothing. For Codex it composes the rollout history (<code>_composeCodexRolloutResp</code>); for Claude it holds the last terminal snapshot (<code>_readScrollbackSnapshotForRestore</code>). We then <em>hide</em> that content behind a spinner instead of showing it. The fix is mostly about <strong>presenting what we already have</strong>.</p>
+  </div>
+</section>
+<!-- ============================================================ -->
+<section id="current">
+  <p class="kicker">How it works now</p>
+  <h2><span class="num">2</span>Current mechanism</h2>
+  <p>Both agents share a presentation layer but diverge in how prior content is produced. Here is the end-to-end flow, traced through <code>server.js</code>, <code>public/index.html</code>, and <code>public/js/state-sync-client.js</code>.</p>
+  <h3>The shared flow</h3>
+  <pre class="ascii">User clicks a session tab
+   │  <span style="color:var(--muted)">activateTab(id) — index.html:21766</span>
+   ▼
+Terminal div becomes visible (EMPTY)
+   ├─ if resuming &amp; no content → _writeResumingPlaceholder()   <span style="color:var(--muted)">"⟳ Resuming session…" written INTO the xterm buffer</span>
+   └─ _showLoadingOverlay({resuming:true})                     <span style="color:var(--muted)">pulsing "Resuming session…" DOM overlay on top</span>
+   ▼
+Server handleCreate() spawns the PTY               <span style="color:var(--muted)">server.js:24151</span>
+   ├─ resume preflight + restore-from-.bak
+   ├─ _readScrollbackSnapshotForRestore()          <span style="color:var(--muted)">seeds the headless mirror</span>
+   └─ Codex large rollout → stamp _resumeLoading=true + 10-min timeout   <span style="color:var(--muted)">server.js:24885</span>
+   ▼
+'created' sent to client (does NOT wait for agent output)
+   ▼
+Client requests a fresh snapshot + seeds scrollback
+   ├─ 600 ms settle, then up to 8 × 700 ms retries   <span style="color:var(--muted)">_maybeSeedStateSyncResumeScrollback</span>
+   └─ DURING Codex silent-load this seeding is SKIPPED (mirror is blank)
+   ▼
+Live frames flow → overlay dismissed when "meaningful content" (&gt;80 chars) appears
+   └─ unless _resumeLoadingDismissBlocked() holds it (Codex only)</pre>
+  <div class="grid2">
+    <div class="card">
+      <span class="tag resume">CLAUDE CODE</span>
+      <h3 style="margin-top:8px">Prior content = terminal snapshot</h3>
+      <ul class="clean footnote">
+        <li>A binary terminal snapshot from the last session is read at spawn and seeded into the headless mirror.</li>
+        <li>The state-sync client then re-requests a scrollback seed at the live terminal's dimensions (600 ms + retries) so history paints under the live frames.</li>
+        <li>Server <em>holds</em> live frames during the repaint window: <code>250 ms</code> settle, <code>2500 ms</code> cap (<code>server.js:19776</code>).</li>
+        <li>Typically ready in a few seconds — but the seed path is the source of the documented "scatter / ghost / blank" rendering family.</li>
+      </ul>
+    </div>
+    <div class="card">
+      <span class="tag" style="color:#ffd27f;border-color:rgba(255,210,127,.3)">CODEX</span>
+      <h3 style="margin-top:8px">Prior content = composed rollout history</h3>
+      <ul class="clean footnote">
+        <li>History is composed from DB rows or a JSONL tail (≤16 MB), capped to ~1000 lines, rendered to ANSI, de-duplicated against the live viewport: <code>_composeCodexRolloutResp</code> (<code>server.js:27924</code>), <code>_composeCodexHistorySnapshot</code>.</li>
+        <li>The composed result is cached for the session's lifetime — cheap to re-emit on tab switch / reflow.</li>
+        <li>But a multi-GB rollout takes <strong>minutes</strong> of silent CPU before the first byte — and that's exactly when the blank-page race bites.</li>
+      </ul>
+    </div>
+  </div>
+  <h3>The timing chain (where the jitter comes from)</h3>
+  <table>
+    <thead><tr><th>Stage</th><th>Delay</th><th>Where</th><th>Purpose</th></tr></thead>
+    <tbody>
+      <tr><td>Scrollback seed — first attempt</td><td><code>600 ms</code></td><td>index.html (state-sync seed)</td><td>Wait for server repaint + resize to settle</td></tr>
+      <tr><td>Scrollback seed — retries</td><td><code>700 ms × 8</code></td><td><code>STATE_SYNC_RESUME_SEED_*</code></td><td>Re-request until a matched-width seed applies</td></tr>
+      <tr><td>Server frame-hold settle</td><td><code>250 ms</code></td><td><code>server.js:19776</code></td><td>Hold live frames until repaint quiets</td></tr>
+      <tr><td>Server frame-hold cap</td><td><code>2500 ms</code></td><td><code>server.js:19778</code></td><td>Release even if the agent streams continuously</td></tr>
+      <tr><td>Overlay "Still resuming…" degrade</td><td><code>15 s</code></td><td>index.html (degrade tick)</td><td>Change copy when content hasn't arrived</td></tr>
+      <tr><td>Codex degraded re-check loop</td><td><code>2 s</code></td><td>index.html (degrade tick)</td><td>Update elapsed timer / re-arm overlay</td></tr>
+      <tr><td>Snapshot request timeout</td><td><code>3 s</code></td><td><code>activateTab</code></td><td>Retry the snapshot if no response</td></tr>
+      <tr><td>Blank watchdog → auto-reflow</td><td><code>6 s</code></td><td><code>activateTab</code></td><td>Force a reflow if still blank</td></tr>
+      <tr><td>Codex resume-loading safety timeout</td><td><code>10 min</code></td><td><code>server.js:24129</code></td><td>Auto-clear the silent-load flag</td></tr>
+    </tbody>
+  </table>
+  <details>
+    <summary>The "is this session resuming?" signal sprawl</summary>
+    <div class="body">
+      <p>There is no single answer. Each consumer checks a different subset:</p>
+      <ul class="clean footnote">
+        <li><strong>Client flags:</strong> <code>_restoreDeferred</code>, <code>_restoreResuming</code>, <code>_restoreStarting</code>, <code>_restoreDeferredStarting</code> — plus <code>s.meta.*</code> mirrors of each.</li>
+        <li><strong>Client timestamp:</strong> <code>_resumeLoadStartedAt</code> (the anchor that the blank-page race zeroes).</li>
+        <li><strong>Server flag:</strong> <code>session._resumeLoading</code> + <code>_resumeLoadingFileSize</code>, broadcast in the session list.</li>
+        <li><strong>Codex heuristics:</strong> <code>_isLargeCodexResumeStillLoading</code>, <code>_codexLargeResumeLoadingCore</code>, <code>_resumeLoadingDismissBlocked</code>.</li>
+        <li><strong>Two overlays:</strong> <code>#reconnect-overlay</code> (WebSocket drop) and the dynamic <code>.snapshot-loading-overlay</code> (resume) — similarly named, conceptually conflated.</li>
+      </ul>
+    </div>
+  </details>
+</section>
+<!-- ============================================================ -->
+<section id="problems">
+  <p class="kicker">Diagnosis</p>
+  <h2><span class="num">3</span>Why it's bad — four findings</h2>
+  <div class="card">
+    <h3 style="margin-top:0">① We show a spinner, but we already have the content</h3>
+    <p>The user sees a blank xterm + the <code>⟳ Resuming session…</code> placeholder + a pulsing <code>Resuming session…</code> overlay. Meanwhile the prior conversation is composed and cached server-side. We gate that real content behind the 600 ms + 8×700 ms seed retries, and <em>actively skip it</em> during Codex silent-load. The content the user is resuming sits ready while they stare at nothing.</p>
+    <p class="ref">index.html — _writeResumingPlaceholder, _showLoadingOverlay · server.js:27924 _composeCodexRolloutResp · state-sync seed STATE_SYNC_RESUME_SEED_*</p>
+  </div>
+  <div class="card">
+    <h3 style="margin-top:0">② No single source of truth — the logic is scattered</h3>
+    <p>"Is this resuming, and what should the user see?" is answered by 4 redundant client flags (each mirrored on <code>s.meta</code>), a server flag, a client timestamp, and a cluster of Codex-only heuristics — spread across ~10 functions and two overlay systems. Double "Resuming" feedback (placeholder <em>and</em> overlay) shows at once. Every past fix added another guard rather than removing the ambiguity.</p>
+    <p class="ref">4 flags + meta mirrors · 2 overlays · _isLargeCodexResumeStillLoading / _renderCodexResumeLoadingOverlay / _resumeLoadingDismissBlocked</p>
+  </div>
+  <div class="card">
+    <h3 style="margin-top:0">③ The blank-page race</h3>
+    <p>A blank snapshot applied mid-resume calls <code>_dismissLoadingOverlay</code>, which zeros <code>_resumeLoadStartedAt</code>. Once that anchor is zero, <code>_isLargeCodexResumeStillLoading()</code> returns <code>false</code> <em>forever</em> → the overlay never re-arms → blank for minutes until the load finishes. It's defended in three fragile places (server <code>_serializedSnapshotIsBlank</code> ×2 + client <code>_resumeLoadingDismissBlocked</code>); miss any one and the bug returns. This is the recurring "overlay then blank for minutes" regression.</p>
+    <p class="ref">server.js:20476 / 20553 _serializedSnapshotIsBlank · index.html _resumeLoadingDismissBlocked · anchor _resumeLoadStartedAt</p>
+  </div>
+  <div class="card">
+    <h3 style="margin-top:0">④ Jitter, not steady progress</h3>
+    <p>The wait stutters through 250–2500 ms (frame-hold), 600 ms (seed), 700 ms×8 (retries), 15 s (degrade), 2 s (re-check). Large Codex shows only a bare elapsed counter for minutes with no staging or reassurance. Irregular delay (jitter) is measurably harder to tolerate than a longer but predictable one.</p>
+  </div>
+  <h3>What the research says</h3>
+  <div class="grid3">
+    <div class="card tight">
+      <h4 style="margin:0 0 6px;color:var(--muted)">Skeleton &gt; spinner</h4>
+      <p class="footnote" style="margin:0">Previewing the actual layout/content makes an identical wait feel 30–50% shorter. A 3 s skeleton ≈ a 1.5 s spinner in perceived time. Spinners create time-uncertainty; skeletons signal progress.</p>
+    </div>
+    <div class="card tight">
+      <h4 style="margin:0 0 6px;color:var(--muted)">Feedback within 100 ms</h4>
+      <p class="footnote" style="margin:0">Any user action should produce a visible response within ~100 ms. Spinners suit &lt;10 s blocking actions; past 10 s, show a determinate/staged indicator — not an open-ended spinner.</p>
+    </div>
+    <div class="card tight">
+      <h4 style="margin:0 0 6px;color:var(--muted)">Restore without a flash</h4>
+      <p class="footnote" style="margin:0">Terminal session-restore must not dump the buffer into scrollback or flash blank (Windows Terminal #17274). Jitter hurts more than steady latency — even sub-conscious jitter degrades the feel.</p>
+    </div>
+  </div>
+  <p class="footnote">Sources:
+    <a class="src" href="https://www.nngroup.com/articles/skeleton-screens/">NN/g — Skeleton Screens 101</a> ·
+    <a class="src" href="https://blog.logrocket.com/ux-design/skeleton-loading-screen-design/">LogRocket — Skeleton loading &amp; perceived performance</a> ·
+    <a class="src" href="https://www.onething.design/post/skeleton-screens-vs-loading-spinners">Onething — Skeletons vs spinners</a> ·
+    <a class="src" href="https://github.com/microsoft/terminal/issues/17274">microsoft/terminal #17274 — buffer restore without scrollback flash</a>
+  </p>
+</section>
+<!-- ============================================================ -->
+<section id="principles">
+  <p class="kicker">What good looks like</p>
+  <h2><span class="num">4</span>Three principles</h2>
+  <div class="grid3">
+    <div class="card">
+      <h3 style="margin-top:0">Content-wait, not spinner-wait</h3>
+      <p class="footnote">If we have the prior conversation (we do), show it immediately as a dimmed, read-only skeleton. The user reads "where I left off" instead of watching a spinner. The live terminal fades in on top when ready.</p>
+    </div>
+    <div class="card">
+      <h3 style="margin-top:0">One source of truth</h3>
+      <p class="footnote">A single pure reducer derives the resume state from a small set of signals. Every consumer (overlay, skeleton, sidebar tag, input-enable) reads from it. No more flag sprawl, no more per-consumer disagreement.</p>
+    </div>
+    <div class="card">
+      <h3 style="margin-top:0">Eliminate the race, don't guard it</h3>
+      <p class="footnote">Make the state machine the <em>only</em> thing that can dismiss. A blank snapshot then simply fails to advance state — it can't wipe the anchor. The bug becomes structurally impossible, not defended in three places.</p>
+    </div>
+  </div>
+</section>
+<!-- ============================================================ -->
+<section id="design">
+  <p class="kicker">The proposal</p>
+  <h2><span class="num">5</span>Proposed design</h2>
+  <p class="lead">Turn resume into a content-wait: show the prior conversation as a skeleton instantly, governed by one resume state machine, and cross-fade to the live terminal when it paints.</p>
+  <h3>A · One resume state machine — <code>public/js/resume-state.js</code></h3>
+  <p>A new pure module mirroring the existing <code>session-phase.js</code> SSOT pattern. A single reducer maps signals to everything the UI needs:</p>
+  <pre class="ascii">deriveResumeState(signals) → { state, showSkeleton, showSlowProgress, headerText, inputEnabled, dismissBlocked }</pre>
+  <p>States, and the transitions between them:</p>
+  <p>
+    <span class="statebox">idle</span><span class="arrow"> → </span>
+    <span class="statebox">spawning</span><span class="arrow"> → </span>
+    <span class="statebox" style="color:var(--resume);border-color:rgba(91,156,255,.5)">preview</span><span class="arrow"> → </span>
+    <span class="statebox">live-pending</span><span class="arrow"> → </span>
+    <span class="statebox live">live</span>
+    &nbsp;&nbsp;<span class="arrow">⤷ </span><span class="statebox slow">slow</span> &nbsp;<span class="arrow">⤷ </span><span class="statebox err">error</span>
+  </p>
+  <table>
+    <thead><tr><th>State</th><th>Meaning</th><th>User sees</th></tr></thead>
+    <tbody>
+      <tr><td><code>spawning</code></td><td>PTY requested, no history yet</td><td>Header + subtle pulse (≤100 ms window)</td></tr>
+      <tr><td><code>preview</code></td><td>Prior conversation available</td><td><strong>Dimmed skeleton of the conversation</strong> + "reconnecting live session…"</td></tr>
+      <tr><td><code>live-pending</code></td><td>Live frames arriving, not yet settled</td><td>Skeleton holds; live paints underneath</td></tr>
+      <tr><td><code>live</code></td><td>First settled live paint</td><td>Cross-fade out; input enabled</td></tr>
+      <tr><td><code>slow</code></td><td>Genuine large-Codex silent-load</td><td>Skeleton + steady staged progress + escape hatches</td></tr>
+      <tr><td><code>error</code></td><td>Preflight/spawn failed</td><td>Clear error + "Start fresh here"</td></tr>
+    </tbody>
+  </table>
+  <p class="footnote">Signals in: <code>agentType, hasHistorySnapshot, serverResumeLoading, firstLiveByteAt, meaningfulContent, fileSize, elapsedMs, preflightError</code>. This single function subsumes the 4 flags, <code>_isLargeCodexResumeStillLoading</code>, and <code>_resumeLoadingDismissBlocked</code>.</p>
+  <h3>B · Skeleton as a dedicated preview layer (decoupled from the xterm buffer)</h3>
+  <p>The skeleton renders the already-composed prior content in a <strong>separate styled layer above the terminal</strong> — <em>not</em> by seeding the live xterm buffer. This is deliberate: seeding history into the live buffer is the source of the documented scatter / spinner-ghost / blank-on-seed bugs. A decoupled layer sidesteps that family entirely and gives a clean cross-fade. The existing xterm seed still runs underneath; the user watches the preview until the live keyframe settles, then the preview fades and input enables.</p>
+  <div class="grid2">
+    <div>
+      <p class="footnote" style="margin-bottom:6px"><strong>Claude resume — the moment you click</strong></p>
+      <div class="term">
+        <div class="bar"><span class="dots"><i style="background:#ff5f57"></i><i style="background:#febc2e"></i><i style="background:#28c840"></i></span><span>Resuming: refactor auth module</span></div>
+        <div class="body"><span class="skh">┌─ Resuming where you left off ───────────────┐</span>
+<span class="dim">› you: add rate limiting to /login</span>
+<span class="dim">● claude: I'll add a token-bucket limiter…</span>
+<span class="dim">  ⎿ edited auth.js, middleware.js  (+47 −3)</span>
+<span class="dim">› you: now add tests for the limiter</span>
+<span class="dim">● claude: Added 6 cases to auth.test.js…</span>
+<span class="foot pulse">░░░ reconnecting live session… ░░░</span></div>
+      </div>
+      <p class="footnote">Dimmed, read-only, instant. Input disabled until live.</p>
+    </div>
+    <div>
+      <p class="footnote" style="margin-bottom:6px"><strong>Large Codex — the honest slow case</strong></p>
+      <div class="term">
+        <div class="bar"><span class="dots"><i style="background:#ff5f57"></i><i style="background:#febc2e"></i><i style="background:#28c840"></i></span><span>Resuming: data-pipeline migration</span></div>
+        <div class="body"><span class="skh">┌─ Resuming where you left off ───────────────┐</span>
+<span class="dim">› you: migrate the ingest job to the new schema</span>
+<span class="dim">• codex: ran migration, 3 tables altered…</span>
+<span class="dim">  ⎿ schema.sql, ingest.py changed</span>
+<span style="color:var(--warn)">⏳ Loading 4.2 GB session into memory — this</span>
+<span style="color:var(--warn)">   can take a few minutes. (elapsed 0:48)</span>
+<span class="foot">[ Start fresh here ]   [ Reload render ]</span></div>
+      </div>
+      <p class="footnote">Steady staged copy + existing escape hatches. No bare counter over a void.</p>
+    </div>
+  </div>
+  <h3>C · Dismissal owned solely by the state machine</h3>
+  <p>Individual snapshot handlers stop calling <code>_dismissLoadingOverlay</code> and stop zeroing the anchor. The skeleton is removed only when the reducer transitions to <code>live</code> (first settled meaningful paint). A blank snapshot can no longer wipe anything — it simply doesn't advance the state, so the session stays in <code>preview</code>/<code>slow</code>. The three scattered blank-guards collapse into this one rule.</p>
+  <h3>D · Consolidation</h3>
+  <ul class="clean">
+    <li>Merge the terminal placeholder + the resume overlay into the single skeleton component.</li>
+    <li>Centralize every copy string in one map (no more hard-coded "Resuming…" / "Still resuming…" scattered inline).</li>
+    <li>Keep <code>#reconnect-overlay</code> as a clearly separate WebSocket-reconnect concern; rename to remove the conceptual conflation.</li>
+    <li>Collapse the 4 client flags (+ <code>meta</code> mirrors) into the reducer's input signals.</li>
+  </ul>
+</section>
+<!-- ============================================================ -->
+<section id="plan">
+  <p class="kicker">Execution</p>
+  <h2><span class="num">6</span>Implementation plan</h2>
+  <p>Four phases, smallest-risk first. Each is independently shippable and validated on a <code>/ctm-dev</code> instance (never primary).</p>
+  <div class="phase">
+    <div class="badge">0</div>
+    <div class="pbody">
+      <h4>SSOT module + tests — no behavior change</h4>
+      <p>Add <code>public/js/resume-state.js</code> (pure reducer, states, centralized strings) and <code>tests/resume-state.test.js</code>. Mirror the structure and test style of <code>session-phase.js</code> / <code>session-phase.test.js</code>. Nothing wired in yet.</p>
+      <p class="ref">NEW public/js/resume-state.js · NEW tests/resume-state.test.js</p>
+    </div>
+  </div>
+  <div class="phase">
+    <div class="badge">1</div>
+    <div class="pbody">
+      <h4>Consolidate + kill the race</h4>
+      <p>Route the 4 client flags + server <code>_resumeLoading</code> + <code>_resumeLoadStartedAt</code> through <code>deriveResumeState</code>. Make the state machine the <strong>sole owner of dismissal</strong> — no handler zeroes the anchor. Merge placeholder + overlay into one component; centralize copy. Port the blank-page-race and dismiss-block scenarios into the new test so the regression can't return.</p>
+      <p class="ref">index.html — activateTab, _showLoadingOverlay/_dismissLoadingOverlay, _writeResumingPlaceholder, the Codex overlay cluster</p>
+    </div>
+  </div>
+  <div class="phase">
+    <div class="badge">2</div>
+    <div class="pbody">
+      <h4>Skeleton preview — the win</h4>
+      <p>New preview layer that renders the already-composed prior content immediately: Codex reuses the cached rollout compose; Claude reads the scrollback snapshot at spawn and sends an early <code>restore-preview</code> message. Dimmed, read-only, header <code>Resuming: &lt;title&gt;</code>, footer <code>reconnecting live session…</code>. Cross-fade to the live xterm on the first settled paint. Validate against the render-test suite to confirm the decoupled layer avoids the seed-corruption family.</p>
+      <p class="ref">server.js — handleCreate resume path, _composeCodexRolloutResp, _readScrollbackSnapshotForRestore · lib/codex-rollout-snapshot.js · lib/session-history.js · state-sync-client.js</p>
+    </div>
+  </div>
+  <div class="phase">
+    <div class="badge">3</div>
+    <div class="pbody">
+      <h4>Slow-case polish + de-jitter</h4>
+      <p>Steady staged progress for multi-GB Codex (a determinate hint if one is derivable from bytes-read). Drop the 600 ms pre-preview gate — we already have content to show. Keep the server frame-hold, but now it's invisible because the skeleton covers the repaint window.</p>
+      <p class="ref">server.js frame-hold (19776) · seed timing constants</p>
+    </div>
+  </div>
+  <h3>Files touched</h3>
+  <table>
+    <thead><tr><th>File</th><th>Role</th></tr></thead>
+    <tbody>
+      <tr><td><code>public/js/resume-state.js</code> <span class="goodtag">NEW</span></td><td>The reducer / SSOT for resume state + copy</td></tr>
+      <tr><td><code>tests/resume-state.test.js</code> <span class="goodtag">NEW</span></td><td>Unit coverage incl. ported race/dismiss scenarios</td></tr>
+      <tr><td><code>public/index.html</code></td><td>activateTab, overlay + placeholder → skeleton layer, flags → signals</td></tr>
+      <tr><td><code>public/js/state-sync-client.js</code></td><td>Seed runs underneath; preview decoupled from it</td></tr>
+      <tr><td><code>server.js</code></td><td>handleCreate resume path, early restore-preview, blank-guard cleanup, frame-hold</td></tr>
+      <tr><td><code>lib/codex-rollout-snapshot.js</code>, <code>lib/session-history.js</code></td><td>Reused as-is for Codex history compose</td></tr>
+    </tbody>
+  </table>
+</section>
+<!-- ============================================================ -->
+<section id="verify">
+  <p class="kicker">Proving it</p>
+  <h2><span class="num">7</span>Verification</h2>
+  <ol class="clean">
+    <li><strong>Unit:</strong> <code>cd claude-task-manager &amp;&amp; npm test</code> — <code>resume-state.test.js</code> green; every ported race/dismiss scenario passes.</li>
+    <li><strong>Dev only — never primary (3456/3457):</strong> a <code>/ctm-dev</code> instance on a random port. Resume a Claude session and a large Codex session; confirm the skeleton shows the prior conversation within ~100 ms, no blank window, clean cross-fade to live, input disabled until live.</li>
+    <li><strong>Render safety:</strong> run the <code>ctm-render-test</code> Playwright suite — no regression in the scrollback/seed rendering family.</li>
+    <li><strong>Differential:</strong> snapshot the resume visual states before/after on dev; any blank window is a regression to explain before merge.</li>
+    <li><strong>Deploy:</strong> do not restart primary; the user authorizes any primary deploy explicitly.</li>
+  </ol>
+  <div class="callout good">
+    <h4>The outcome</h4>
+    <p style="margin:0">Click a session and you immediately see the conversation you're resuming — dimmed, with a clear "reconnecting" footer — then the live terminal fades in. No blank page, no double "Resuming…", no jitter. One state machine decides it all, and the blank-page race is gone by construction.</p>
+  </div>
+  <hr class="sep">
+  <p class="footnote">CTM · Resume UX Redesign · design proposal, review before implementation · companion docs: <code>session-status-redesign.html</code>, <code>terminal-rendering-redesign.html</code>, <code>conversation-log-redesign.html</code>.</p>
+</section>
+</div>
+</body>
+</html>