create-walle 0.9.30 → 0.9.32

package/template/claude-task-manager/public/js/resume-state.js

@@ -0,0 +1,186 @@
+'use strict';
+
+/*
+ * resume-state.js — the single source of truth for "what should the user see
+ * while a session is resuming?"
+ *
+ * Redesign goal (see docs/resume-ux-redesign.html): replace the scattered web of
+ * 4 client flags (+ s.meta mirrors), a server flag, a client timestamp, and a
+ * cluster of Codex-only heuristics spread across ~10 functions and two overlays
+ * with ONE pure reducer. Every consumer — the loading overlay, the skeleton
+ * preview, the sidebar tag, the input-enable gate — reads from this.
+ *
+ * Two design rules encode the operator's guidance:
+ *   - "Content-wait, not spinner-wait." → when the prior conversation is already
+ *     composed (it usually is), surface it as a dimmed read-only skeleton instead
+ *     of a spinner over a blank buffer.
+ *   - "Eliminate the race, don't guard it." → the reducer is the SOLE owner of
+ *     dismissal. A blank snapshot simply fails to advance to `live`, so it can
+ *     never wipe the skeleton. The blank-page race becomes structurally
+ *     impossible rather than defended in three fragile places.
+ *
+ * Isomorphic: same dual node/browser export as session-phase.js, so the server
+ * and the client derive resume state from identical code, and node can unit-test it.
+ */
+
+(function initResumeState(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.ResumeState = factory();
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : this, function buildResumeState() {
+  // ---- states ------------------------------------------------------------
+  const STATES = {
+    IDLE: 'idle',                 // no resume underway
+    SPAWNING: 'spawning',         // PTY requested, no history yet (≤100ms window)
+    PREVIEW: 'preview',           // prior conversation available → skeleton
+    LIVE_PENDING: 'live-pending', // live frames arriving, not yet settled
+    LIVE: 'live',                 // first settled meaningful paint → done
+    SLOW: 'slow',                 // genuine large silent-load (server still loading)
+    ERROR: 'error',               // preflight/spawn failed
+  };
+
+  // ---- timing ------------------------------------------------------------
+  // Only enter the `slow` state once a server-side load has genuinely run long,
+  // so fast resumes never flash the "this can take a few minutes" copy. This is
+  // the lone resume timing constant the UI needs; the old 600ms/700ms×8/250–2500ms
+  // chain is an implementation detail the skeleton now hides.
+  const SLOW_ELAPSED_MS = 3000;
+
+  // ---- copy (one home for every resume string) ---------------------------
+  const STRINGS = {
+    spawning: 'Resuming…',
+    resuming: 'Resuming',
+    error: "Couldn't resume this session",
+    footerReconnecting: 'reconnecting live session…',
+    skeletonHeader: 'Resuming where you left off',
+  };
+
+  // ---- helpers -----------------------------------------------------------
+  function formatBytes(bytes) {
+    const n = Number(bytes) || 0;
+    if (n <= 0) return '';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let i = 0;
+    let v = n;
+    while (v >= 1024 && i < units.length - 1) { v /= 1024; i += 1; }
+    const rounded = v >= 100 || i === 0 ? Math.round(v) : Math.round(v * 10) / 10;
+    return `${rounded} ${units[i]}`;
+  }
+
+  function formatElapsed(ms) {
+    const total = Math.max(0, Math.floor((Number(ms) || 0) / 1000));
+    const m = Math.floor(total / 60);
+    const s = total % 60;
+    return `${m}:${String(s).padStart(2, '0')}`;
+  }
+
+  function slowProgressText(signals) {
+    const size = formatBytes(signals.fileSize);
+    const sizePart = size ? `${size} ` : '';
+    const elapsed = signals.elapsedMs ? ` (elapsed ${formatElapsed(signals.elapsedMs)})` : '';
+    return `Loading ${sizePart}session into memory — this can take a few minutes.${elapsed}`;
+  }
+
+  // Build the dimmed skeleton lines from the prior user prompts (s.promptPreviews — already
+  // maintained client-side, so the preview is decoupled from the live xterm buffer: no seeding,
+  // no scatter/ghost/blank-on-seed risk). Newest-last, capped, whitespace-collapsed, truncated.
+  const PREVIEW_MARKER = '› ';
+  function previewLines(prompts, opts) {
+    if (!Array.isArray(prompts) || !prompts.length) return [];
+    const max = Math.max(1, (opts && opts.max) || 6);
+    const width = Math.max(8, (opts && opts.width) || 64);
+    return prompts
+      .filter((p) => p != null && String(p).trim())
+      .slice(-max)
+      .map((p) => {
+        const text = String(p).replace(/\s+/g, ' ').trim();
+        const clipped = text.length > width ? text.slice(0, width - 1).trimEnd() + '…' : text;
+        return PREVIEW_MARKER + clipped;
+      });
+  }
+
+  function headerFor(state, title) {
+    const named = title ? `${STRINGS.resuming}: ${title}` : STRINGS.resuming;
+    switch (state) {
+      case STATES.SPAWNING: return title ? named : STRINGS.spawning;
+      case STATES.PREVIEW:
+      case STATES.LIVE_PENDING:
+      case STATES.SLOW: return named;
+      case STATES.ERROR: return STRINGS.error;
+      default: return ''; // idle / live → no resume header
+    }
+  }
+
+  // ------------------------------------------------------------------------
+  // deriveResumeState — the ONLY place the resume state is decided.
+  //
+  // Signals (all optional):
+  //   resuming            bool   a resume is underway (set at handleCreate, cleared on live)
+  //   agentType           string 'codex' | 'claude' | …
+  //   hasHistorySnapshot  bool   the prior conversation has been composed/cached
+  //   serverResumeLoading bool   the server reports it is still loading the session
+  //   firstLiveByteAt     number ts of the first live PTY frame (truthy ⇒ painting)
+  //   meaningfulContent   bool   a settled, non-blank live paint has landed
+  //   fileSize            number bytes of the session being loaded (for slow copy)
+  //   elapsedMs           number ms since the resume began
+  //   preflightError      string non-empty ⇒ resume cannot proceed
+  //   title               string session title for the skeleton header
+  // ------------------------------------------------------------------------
+  function deriveResumeState(signals = {}) {
+    const resuming = !!signals.resuming;
+    const hasHistory = !!signals.hasHistorySnapshot;
+    const live = !!signals.firstLiveByteAt;
+    const elapsedMs = Number(signals.elapsedMs) || 0;
+    const isSlow = !!signals.serverResumeLoading && elapsedMs >= SLOW_ELAPSED_MS;
+
+    let state;
+    if (signals.preflightError) {
+      state = STATES.ERROR;
+    } else if (signals.meaningfulContent) {
+      state = STATES.LIVE;                 // settled → resume complete
+    } else if (!resuming) {
+      state = STATES.IDLE;
+    } else if (live) {
+      state = STATES.LIVE_PENDING;         // painting beats "silently loading"
+    } else if (isSlow) {
+      state = STATES.SLOW;
+    } else if (hasHistory) {
+      state = STATES.PREVIEW;
+    } else {
+      state = STATES.SPAWNING;
+    }
+
+    const inResumeFlow = state === STATES.SPAWNING || state === STATES.PREVIEW
+      || state === STATES.LIVE_PENDING || state === STATES.SLOW;
+    const showSkeleton = hasHistory
+      && (state === STATES.PREVIEW || state === STATES.LIVE_PENDING || state === STATES.SLOW);
+    const showSlowProgress = state === STATES.SLOW;
+
+    return {
+      state,
+      showSkeleton,
+      showSlowProgress,
+      headerText: headerFor(state, signals.title),
+      footerText: inResumeFlow ? STRINGS.footerReconnecting : '',
+      progressText: showSlowProgress ? slowProgressText(signals) : '',
+      // dismissal is owned solely here: only the non-terminal resume states block
+      // the skeleton from being torn down. A blank snapshot can never reach `live`,
+      // so it can never unblock — the blank-page race is impossible by construction.
+      dismissBlocked: inResumeFlow,
+      inputEnabled: state === STATES.IDLE || state === STATES.LIVE,
+    };
+  }
+
+  return {
+    STATES,
+    STRINGS,
+    SLOW_ELAPSED_MS,
+    formatBytes,
+    formatElapsed,
+    slowProgressText,
+    previewLines,
+    deriveResumeState,
+  };
+});