Codeman/src/web/public/entrance-animations.js

/**
 * @fileoverview Entrance animations for the four things that appear when work
 * starts: session TABS, the main TERMINAL pane a session's CLI runs in, floating
 * agent WINDOWS, and the CONNECTION LINES tying a window back to its parent tab.
 * One picker per surface, plus themes that set all four to a matching look.
 *
 * Everything is OFF by default (the `legacy` theme), so an untouched install
 * behaves exactly as it did before this module existed. Opt in via App Settings
 * → Appearance → Entrance Animations.
 *
 * Four constraints shape the design:
 *
 * 1. `_fullRenderSessionTabs()` replaces the tab strip's entire innerHTML, and
 *    `_updateConnectionLinesImmediate()` does `svg.innerHTML = ''` and rebuilds
 *    every path. Both run constantly while sessions and agents are spawning, so
 *    an animating tab or line element is DESTROYED mid-flight. Those two are
 *    therefore tracked by id in `_tabEnterActive` / `_lineEnterActive` and
 *    re-applied to the fresh element with a NEGATIVE animation-delay, resuming at
 *    the same offset instead of restarting or snapping to the end. Windows are
 *    stable DOM and need none of this.
 * 2. Connection-line geometry comes from `getBoundingClientRect()` on the window.
 *    A window entrance that starts with a transform would move that rect, so the
 *    `beam` style (which must hold still while its line draws toward it) animates
 *    opacity and filter only. Every other style refreshes the lines when it ends.
 * 3. The terminal pane is ONE shared element, so its entrance is marked at
 *    session creation but played at selection: a session created in the
 *    background must not animate the pane the user is currently looking at. Its
 *    styles are also restricted to transform/opacity/clip-path (see below).
 * 4. Nothing may animate on page load or reconnect replay. Only ids that pass
 *    through `markSessionTabEntering()` animate, and `_tabEnterSeen` makes that
 *    once-per-id even though the POST response and the SSE event both call
 *    `_onSessionCreated`.
 *
 * Styles are selected by `data-tab-anim` / `data-term-anim` / `data-win-anim` /
 * `data-line-anim` on <html>; the keyframes live in styles.css. `?animlab=1`
 * opens a floating picker that fakes tabs, a pane replay, a window and a line,
 * so styles can be compared without spawning real sessions or agents.
 *
 * @mixin Extends CodemanApp.prototype via Object.assign
 * @dependency app.js (tab render pipeline), subagent-windows.js (window + line hooks)
 * @dependency constants.js (escapeHtml)
 * @loadorder 12.6 of 16, after webview-tabs.js, before ralph-wizard.js
 */

/** Tab entrance styles. `key` doubles as the `data-tab-anim` value. */
const TAB_ANIM_STYLES = [
  { key: 'slide', label: 'Slide', blurb: 'Drifts in from the right.', duration: 380 },
  { key: 'pop', label: 'Pop', blurb: 'Springs past full size, then settles.', duration: 460 },
  { key: 'crt', label: 'CRT', blurb: 'Snaps open as a hot line, then unfolds.', duration: 520 },
  { key: 'unroll', label: 'Unroll', blurb: 'The strip makes room and the tab widens in.', duration: 480 },
  { key: 'boot', label: 'Boot', blurb: 'Flickers on under a green scan sweep.', duration: 720 },
  { key: 'flip', label: 'Flip', blurb: 'Drops in as a card hinged on its top edge.', duration: 520 },
  { key: 'off', label: 'Off', blurb: 'Tabs just appear.', duration: 0 },
];

/**
 * Window entrance styles. `fly` is the pre-existing behaviour (the window flies
 * out of its parent tab via a JS transition in subagent-windows.js); every other
 * style positions the window at its resting spot and runs a CSS animation there.
 */
const WIN_ANIM_STYLES = [
  { key: 'fly', label: 'Fly from tab', blurb: 'Current behaviour: flies out of the tab, scaling up.', duration: 400 },
  { key: 'crt', label: 'CRT', blurb: 'Bursts open as a hot line, then unfolds vertically.', duration: 560 },
  { key: 'materialize', label: 'Materialize', blurb: 'Resolves out of a blur with a short glitch.', duration: 620 },
  { key: 'unfold', label: 'Unfold', blurb: 'Hinges down from its top edge in 3D.', duration: 560 },
  { key: 'beam', label: 'Beam down', blurb: 'Waits for its line to reach it, then materializes.', duration: 620 },
  { key: 'pop', label: 'Pop', blurb: 'Springs open from its centre.', duration: 460 },
  { key: 'off', label: 'Off', blurb: 'Windows just appear.', duration: 0 },
];

/** Connection-line entrance styles. `key` doubles as the `data-line-anim` value. */
const LINE_ANIM_STYLES = [
  { key: 'draw', label: 'Draw', blurb: 'Draws itself from the tab down to the window.', duration: 420 },
  { key: 'packet', label: 'Packet', blurb: 'Line fades in, then a bright packet runs down it.', duration: 700 },
  { key: 'fade', label: 'Fade', blurb: 'Simply fades in.', duration: 300 },
  { key: 'off', label: 'Off', blurb: 'Lines just appear.', duration: 0 },
];

/**
 * Main-terminal entrance styles: the pane a session's CLI actually runs in.
 *
 * ⚠ These may only animate transform, opacity and clip-path. xterm's FitAddon
 * derives rows/cols from `getComputedStyle(parent).width/height`, which reports
 * the untransformed layout box, so transforms are safe, but animating width,
 * height or padding would feed wrong dimensions into `resize()` and through to
 * the PTY. Colour washes go on `.terminal-container::before`, never a `filter`
 * on the container: that would blur a full-screen WebGL canvas every frame.
 */
const TERM_ANIM_STYLES = [
  { key: 'crt', label: 'CRT', blurb: 'Power-on: a hot line that expands to full height.', duration: 560 },
  { key: 'boot', label: 'Boot', blurb: 'Flickers on under a green scan sweep.', duration: 760 },
  { key: 'wipe', label: 'Wipe', blurb: 'Reveals top-to-bottom behind a bright edge.', duration: 520 },
  { key: 'slide', label: 'Slide up', blurb: 'Rises into place from below.', duration: 420 },
  { key: 'fade', label: 'Fade', blurb: 'Quiet fade with a touch of scale.', duration: 340 },
  { key: 'off', label: 'Off', blurb: 'Current behaviour: the pane just appears.', duration: 0 },
];

/** How long a `beam` window waits before materializing. Just under the line draw. */
const BEAM_HOLD_MS = 360;

/** One-click combinations that read as a single look. */
const ANIM_THEMES = [
  { key: 'terminal', label: 'Terminal', tab: 'crt', win: 'crt', line: 'draw', term: 'crt' },
  { key: 'beamdown', label: 'Beam down', tab: 'crt', win: 'beam', line: 'draw', term: 'wipe' },
  { key: 'quiet', label: 'Quiet', tab: 'slide', win: 'materialize', line: 'fade', term: 'fade' },
  { key: 'playful', label: 'Playful', tab: 'pop', win: 'pop', line: 'packet', term: 'slide' },
  { key: 'legacy', label: 'Legacy', tab: 'off', win: 'fly', line: 'off', term: 'off' },
];

/**
 * Defaults are the `legacy` theme: every entrance OFF, and agent windows on the
 * `fly` behaviour Codeman already had before this module existed. So a user who
 * never opens the picker sees exactly the pre-existing UI, and each mark/apply
 * hook short-circuits on its first line. Opt in via App Settings → Appearance →
 * Entrance Animations, which persists to the localStorage keys below.
 */
const TAB_ANIM_DEFAULT = 'off';
const WIN_ANIM_DEFAULT = 'fly';
const LINE_ANIM_DEFAULT = 'off';
const TERM_ANIM_DEFAULT = 'off';
const TAB_ANIM_STAGGER_DEFAULT = 90;
/** A new id joins the current cascade if it arrives within this of the last one. */
const TAB_ANIM_BATCH_WINDOW_MS = 600;

const ANIM_KEYS = {
  tab: 'codeman:tabAnim',
  win: 'codeman:winAnim',
  line: 'codeman:lineAnim',
  term: 'codeman:termAnim',
  termSwitch: 'codeman:termAnimOnSwitch',
  stagger: 'codeman:tabAnimStagger',
  speed: 'codeman:tabAnimSpeed',
};

Object.assign(CodemanApp.prototype, {
  // ── Setup ─────────────────────────────────────────────────────────────────

  /** Resolve every style/timing and stamp them on <html>. Called once at startup. */
  initEntranceAnimations() {
    this._tabEnterSeen = new Set();
    this._tabEnterActive = new Map();
    this._lineEnterActive = new Map();
    this._tabEnterBatchIndex = 0;
    this._tabEnterLastMarkTs = 0;

    const params = new URLSearchParams(location.search);
    // ?tabanim= / ?winanim= / ?lineanim= win for a single load, so a style can be
    // tried without persisting over whatever is saved.
    const pick = (param, styles, storeKey, fallback) => {
      const fromUrl = params.get(param);
      if (styles.some((s) => s.key === fromUrl)) return fromUrl;
      return this._animRead(storeKey, fallback);
    };

    this.setTabAnimStyle(pick('tabanim', TAB_ANIM_STYLES, ANIM_KEYS.tab, TAB_ANIM_DEFAULT), { persist: false });
    this.setWinAnimStyle(pick('winanim', WIN_ANIM_STYLES, ANIM_KEYS.win, WIN_ANIM_DEFAULT), { persist: false });
    this.setLineAnimStyle(pick('lineanim', LINE_ANIM_STYLES, ANIM_KEYS.line, LINE_ANIM_DEFAULT), { persist: false });
    this.setTermAnimStyle(pick('termanim', TERM_ANIM_STYLES, ANIM_KEYS.term, TERM_ANIM_DEFAULT), { persist: false });
    this.setTermAnimOnSwitch(this._animRead(ANIM_KEYS.termSwitch, '0') === '1', { persist: false });

    this.setTabAnimStagger(Number(this._animRead(ANIM_KEYS.stagger, TAB_ANIM_STAGGER_DEFAULT)), { persist: false });
    this.setAnimSpeed(Number(this._animRead(ANIM_KEYS.speed, 1)), { persist: false });

    if (params.get('animlab') === '1' || params.get('tabanimlab') === '1') this.openAnimLab();
  },

  _animRead(key, fallback) {
    try {
      const raw = localStorage.getItem(key);
      return raw === null || raw === '' ? fallback : raw;
    } catch {
      return fallback;
    }
  },

  _animWrite(key, value) {
    try {
      localStorage.setItem(key, String(value));
    } catch {
      /* private mode / quota, the in-memory value still applies for this load */
    }
  },

  _setAnimStyle(prop, key, styles, fallback, attr, storeKey, persist) {
    const style = styles.some((s) => s.key === key) ? key : fallback;
    this[prop] = style;
    document.documentElement.setAttribute(attr, style);
    if (persist) this._animWrite(storeKey, style);
    // Keep the lab's highlight honest when a style is set from anywhere other
    // than the lab's own buttons (a theme, a URL param, the console).
    this._syncAnimLab?.();
  },

  setTabAnimStyle(key, { persist = true } = {}) {
    // prettier-ignore
    this._setAnimStyle('_tabAnimStyle', key, TAB_ANIM_STYLES, TAB_ANIM_DEFAULT, 'data-tab-anim', ANIM_KEYS.tab, persist);
  },

  setWinAnimStyle(key, { persist = true } = {}) {
    // prettier-ignore
    this._setAnimStyle('_winAnimStyle', key, WIN_ANIM_STYLES, WIN_ANIM_DEFAULT, 'data-win-anim', ANIM_KEYS.win, persist);
  },

  setLineAnimStyle(key, { persist = true } = {}) {
    // prettier-ignore
    this._setAnimStyle('_lineAnimStyle', key, LINE_ANIM_STYLES, LINE_ANIM_DEFAULT, 'data-line-anim', ANIM_KEYS.line, persist);
  },

  setTermAnimStyle(key, { persist = true } = {}) {
    // prettier-ignore
    this._setAnimStyle('_termAnimStyle', key, TERM_ANIM_STYLES, TERM_ANIM_DEFAULT, 'data-term-anim', ANIM_KEYS.term, persist);
  },

  /** Replay the terminal entrance on every tab switch, not just on a new session. */
  setTermAnimOnSwitch(on, { persist = true } = {}) {
    this._termAnimOnSwitch = !!on;
    if (persist) this._animWrite(ANIM_KEYS.termSwitch, on ? '1' : '0');
    this._syncAnimLab?.();
  },

  /** Apply a theme: one look across tabs, windows, lines and the terminal. */
  setAnimTheme(themeKey) {
    const theme = ANIM_THEMES.find((t) => t.key === themeKey);
    if (!theme) return;
    this.setTabAnimStyle(theme.tab);
    this.setWinAnimStyle(theme.win);
    this.setLineAnimStyle(theme.line);
    this.setTermAnimStyle(theme.term);
    this._syncEntranceAnimSetting?.();
  },

  /** The theme matching the four current styles, or 'custom' for a lab mix. */
  currentAnimTheme() {
    const match = ANIM_THEMES.find(
      (t) =>
        t.tab === this._tabAnimStyle &&
        t.win === this._winAnimStyle &&
        t.line === this._lineAnimStyle &&
        t.term === this._termAnimStyle
    );
    return match ? match.key : 'custom';
  },

  // ── App Settings picker ───────────────────────────────────────────────────
  //
  // Wired straight to setAnimTheme() rather than through saveAppSettings(): the
  // styles live in their own localStorage keys, so they stay per-device and never
  // reach `PUT /api/settings`, whose schema is .strict() and would reject them.

  _syncEntranceAnimSetting() {
    const sel = document.getElementById('appSettingsEntranceAnim');
    if (!sel) return;
    sel.value = this.currentAnimTheme();
    if (!sel.dataset.bound) {
      sel.dataset.bound = '1';
      sel.addEventListener('change', () => {
        // 'custom' is a readout of a lab mix, not something you can select into.
        if (sel.value === 'custom') sel.value = this.currentAnimTheme();
        else this.setAnimTheme(sel.value);
      });
    }
  },

  setTabAnimStagger(ms, { persist = true } = {}) {
    const value = Number.isFinite(ms) ? Math.max(0, Math.min(400, Math.round(ms))) : TAB_ANIM_STAGGER_DEFAULT;
    this._tabAnimStagger = value;
    if (persist) this._animWrite(ANIM_KEYS.stagger, value);
  },

  setAnimSpeed(multiplier, { persist = true } = {}) {
    const value = Number.isFinite(multiplier) ? Math.max(0.25, Math.min(3, multiplier)) : 1;
    this._animSpeed = value;
    // Every keyframe block reads this, so one variable retimes all of them.
    document.documentElement.style.setProperty('--anim-enter-scale', String(1 / value));
    if (persist) this._animWrite(ANIM_KEYS.speed, value);
  },

  _styleDuration(styles, key) {
    return (styles.find((s) => s.key === key)?.duration || 0) / (this._animSpeed || 1);
  },

  _tabAnimDuration() {
    return this._styleDuration(TAB_ANIM_STYLES, this._tabAnimStyle);
  },

  _winAnimDuration() {
    return this._styleDuration(WIN_ANIM_STYLES, this._winAnimStyle);
  },

  _lineAnimDuration() {
    return this._styleDuration(LINE_ANIM_STYLES, this._lineAnimStyle);
  },

  _termAnimDuration() {
    return this._styleDuration(TERM_ANIM_STYLES, this._termAnimStyle);
  },

  // ── Tabs ──────────────────────────────────────────────────────────────────

  /** Queue a session id to animate on its next render. Idempotent per id. */
  markSessionTabEntering(id) {
    if (!id || this._tabAnimStyle === 'off') return;
    if (!this._tabEnterSeen) return; // initEntranceAnimations() has not run yet
    if (this._tabEnterSeen.has(id)) return;
    this._tabEnterSeen.add(id);

    const now = performance.now();
    // A launch landing well after the previous one starts its own cascade rather
    // than inheriting a large stale offset.
    if (now - this._tabEnterLastMarkTs > TAB_ANIM_BATCH_WINDOW_MS) this._tabEnterBatchIndex = 0;
    this._tabEnterLastMarkTs = now;

    this._tabEnterActive.set(id, {
      startTs: now,
      staggerMs: this._tabEnterBatchIndex * this._tabAnimStagger,
    });
    this._tabEnterBatchIndex += 1;
  },

  /** Attach (or resume) the entrance animation on freshly rendered tabs. */
  _applyTabEntrances() {
    const active = this._tabEnterActive;
    if (!active || active.size === 0) return;
    if (this._tabAnimStyle === 'off') {
      active.clear();
      return;
    }

    const container = this.$('sessionTabs');
    if (!container) return;

    const now = performance.now();
    const duration = this._tabAnimDuration();

    for (const [id, state] of active) {
      const elapsed = now - state.startTs;
      // Ran to completion while the element was detached, nothing left to show.
      if (elapsed > state.staggerMs + duration + 50) {
        active.delete(id);
        continue;
      }

      const tab = container.querySelector(`.session-tab[data-id="${CSS.escape(id)}"]`);
      if (!tab) continue; // not rendered yet; a later render picks it up
      // Already running on this element. Re-stamping the delay would jump it, and
      // the incremental render path can reach here for the same element.
      if (tab.classList.contains('tab-enter')) continue;

      // Negative delay resumes mid-animation, so an unrelated re-render mid-cascade
      // does not restart the tab or make it snap.
      tab.style.setProperty('--tab-enter-delay', `${state.staggerMs - elapsed}ms`);
      tab.classList.add('tab-enter');
      const done = () => {
        tab.classList.remove('tab-enter');
        tab.style.removeProperty('--tab-enter-delay');
        this._tabEnterActive?.delete(id);
      };
      tab.addEventListener('animationend', done, { once: true });
      tab.addEventListener('animationcancel', done, { once: true });
    }
  },

  // ── Main terminal ─────────────────────────────────────────────────────────

  /**
   * Queue the terminal pane to animate the first time this session is shown.
   * Marked at creation but PLAYED at selection, because the pane is one shared
   * element: a session created in the background must not animate the pane the
   * user is currently looking at.
   */
  markTerminalEntering(id) {
    if (!id || this._termAnimStyle === 'off') return;
    if (!this._termEnterPending) this._termEnterPending = new Set();
    this._termEnterPending.add(id);
  },

  /** Play the terminal entrance for `sessionId`, if it is owed one. */
  playTerminalEntrance(sessionId) {
    const style = this._termAnimStyle || TERM_ANIM_DEFAULT;
    if (style === 'off') return;

    const owed = sessionId && this._termEnterPending?.delete(sessionId);
    if (!owed && !this._termAnimOnSwitch) return;

    const el = this.$('terminalContainer');
    if (!el) return;

    // Restart cleanly when switching tabs faster than the animation runs.
    el.classList.remove('term-enter');
    void el.offsetWidth;
    el.classList.add('term-enter');

    clearTimeout(this._termEnterTimer);
    const done = () => {
      el.classList.remove('term-enter');
      clearTimeout(this._termEnterTimer);
    };
    el.addEventListener('animationend', done, { once: true });
    el.addEventListener('animationcancel', done, { once: true });
    // Backstop: a backgrounded tab never fires animationend, which would leave
    // the pane stuck at its 0% keyframe (invisible) when you come back to it.
    this._termEnterTimer = setTimeout(done, this._termAnimDuration() + 900);
  },

  // ── Windows ───────────────────────────────────────────────────────────────

  /**
   * True when the window should be parked on its parent tab and flown to its
   * resting spot by subagent-windows.js. False for every CSS-animated style,
   * which needs the window to start at its final position.
   */
  windowEntranceFliesFromTab() {
    return (this._winAnimStyle || WIN_ANIM_DEFAULT) === 'fly';
  },

  /**
   * Run the window entrance on an already-positioned window.
   * @param {HTMLElement} win a .subagent-window or .ultracode-window
   */
  applyWindowEntrance(win) {
    if (!win) return;
    const style = this._winAnimStyle || WIN_ANIM_DEFAULT;
    if (style === 'off' || style === 'fly') return;

    // `beam` holds the window still (opacity/filter only) while its line draws
    // toward it, then materializes. Everything else starts immediately.
    if (style === 'beam') win.style.setProperty('--win-enter-delay', `${BEAM_HOLD_MS / (this._animSpeed || 1)}ms`);

    win.classList.add('win-enter');
    const done = () => {
      win.classList.remove('win-enter');
      win.style.removeProperty('--win-enter-delay');
      // A transformed window reports a transformed rect, so lines drawn while it
      // was animating are slightly off. Redraw once it has settled.
      this.updateConnectionLines?.();
    };
    win.addEventListener('animationend', done, { once: true });
    win.addEventListener('animationcancel', done, { once: true });
  },

  // ── Connection lines ──────────────────────────────────────────────────────

  /** Queue an agent's connection line to draw itself on the next line rebuild. */
  markConnectionLineEntering(agentId) {
    if (!agentId || this._lineAnimStyle === 'off') return;
    if (!this._lineEnterActive) return;
    if (this._lineEnterActive.has(agentId)) return;
    this._lineEnterActive.set(agentId, { startTs: performance.now() });
  },

  /**
   * Attach (or resume) the draw-in animation on freshly rebuilt paths. Called at
   * the end of `_updateConnectionLinesImmediate()`, which has just thrown away
   * and recreated every path element.
   */
  _applyLineEntrances(svg) {
    const active = this._lineEnterActive;
    if (!active || active.size === 0 || !svg) return;
    const style = this._lineAnimStyle || LINE_ANIM_DEFAULT;
    if (style === 'off') {
      active.clear();
      return;
    }

    const now = performance.now();
    const duration = this._lineAnimDuration();

    for (const [agentId, state] of active) {
      const elapsed = now - state.startTs;
      if (elapsed > duration + 50) {
        active.delete(agentId);
        continue;
      }

      const path = svg.querySelector(`path[data-agent-id="${CSS.escape(agentId)}"]`);
      if (!path) continue;

      const len = Math.max(1, Math.round(path.getTotalLength()));
      path.style.setProperty('--line-len', `${len}px`);
      path.style.setProperty('--line-enter-delay', `${-elapsed}ms`);
      path.classList.add('line-enter');

      // `packet` rides a bright dash ON TOP of the normal dashed line, so the base
      // line keeps its look instead of being taken over by the animation.
      if (style === 'packet') {
        const packet = path.cloneNode(false);
        packet.removeAttribute('data-agent-id');
        packet.setAttribute('class', 'connection-line-packet');
        packet.style.setProperty('--line-len', `${len}px`);
        packet.style.setProperty('--line-enter-delay', `${-elapsed}ms`);
        svg.appendChild(packet);
      }
    }
  },

  // ── Lab (compare styles without spawning sessions or agents) ───────────────

  /** Floating picker: switch styles per surface and replay fake entrances. */
  openAnimLab() {
    if (document.getElementById('animLab')) return;

    const group = (title, styles, attr) => `
      <div class="anim-lab-group">
        <div class="anim-lab-group-title">${title}</div>
        ${styles
          .map(
            (s) => `<button type="button" class="anim-lab-style" data-attr="${attr}" data-style="${s.key}">
                 <strong>${escapeHtml(s.label)}</strong><em>${escapeHtml(s.blurb)}</em>
               </button>`
          )
          .join('')}
      </div>`;

    const panel = document.createElement('div');
    panel.id = 'animLab';
    panel.className = 'anim-lab';
    panel.innerHTML = `
      <div class="anim-lab-head">
        <span>Entrance lab</span>
        <button type="button" class="anim-lab-close" aria-label="Close">&times;</button>
      </div>
      <div class="anim-lab-themes">
        ${ANIM_THEMES.map((t) => `<button type="button" data-theme="${t.key}">${escapeHtml(t.label)}</button>`).join('')}
      </div>
      <div class="anim-lab-scroll">
        ${group('Tabs', TAB_ANIM_STYLES, 'tab')}
        ${group('Terminal pane', TERM_ANIM_STYLES, 'term')}
        <label class="anim-lab-check">
          <input type="checkbox" data-check="termSwitch"> Also on every tab switch
        </label>
        ${group('Agent windows', WIN_ANIM_STYLES, 'win')}
        ${group('Connection lines', LINE_ANIM_STYLES, 'line')}
      </div>
      <label class="anim-lab-range">Tab stagger <output data-out="stagger"></output>
        <input type="range" data-range="stagger" min="0" max="260" step="10">
      </label>
      <label class="anim-lab-range">Speed <output data-out="speed"></output>
        <input type="range" data-range="speed" min="0.5" max="2" step="0.1">
      </label>
      <div class="anim-lab-demo">
        <span>Replay</span>
        <button type="button" data-demo="tabs">Tabs</button>
        <button type="button" data-demo="term">Pane</button>
        <button type="button" data-demo="window">Window</button>
        <button type="button" data-demo="all">All</button>
      </div>
      <p class="anim-lab-hint">Fake tabs, window and line, removed after the run. Real launches use the same timing.</p>
    `;
    document.body.appendChild(panel);

    panel.querySelector('.anim-lab-close').addEventListener('click', () => this.closeAnimLab());
    panel.querySelectorAll('button[data-theme]').forEach((btn) => {
      btn.addEventListener('click', () => {
        this.setAnimTheme(btn.dataset.theme);
        this._syncAnimLab();
        this.demoEntrance('all');
      });
    });
    panel.querySelectorAll('.anim-lab-style').forEach((btn) => {
      btn.addEventListener('click', () => {
        const { attr, style } = btn.dataset;
        if (attr === 'tab') this.setTabAnimStyle(style);
        else if (attr === 'win') this.setWinAnimStyle(style);
        else if (attr === 'term') this.setTermAnimStyle(style);
        else this.setLineAnimStyle(style);
        this._syncAnimLab();
        this.demoEntrance({ tab: 'tabs', term: 'term' }[attr] || 'all');
      });
    });
    panel.querySelector('input[data-check="termSwitch"]').addEventListener('change', (e) => {
      this.setTermAnimOnSwitch(e.target.checked);
    });
    panel.querySelectorAll('input[data-range]').forEach((input) => {
      input.addEventListener('input', () => {
        if (input.dataset.range === 'stagger') this.setTabAnimStagger(Number(input.value));
        else this.setAnimSpeed(Number(input.value));
        this._syncAnimLab();
      });
      input.addEventListener('change', () => this.demoEntrance('all'));
    });
    panel.querySelectorAll('button[data-demo]').forEach((btn) => {
      btn.addEventListener('click', () => this.demoEntrance(btn.dataset.demo));
    });

    this._syncAnimLab();
  },

  closeAnimLab() {
    document.getElementById('animLab')?.remove();
    this._clearEntranceDemo();
  },

  _syncAnimLab() {
    const panel = document.getElementById('animLab');
    if (!panel) return;
    const current = {
      tab: this._tabAnimStyle,
      win: this._winAnimStyle,
      line: this._lineAnimStyle,
      term: this._termAnimStyle,
    };
    panel.querySelectorAll('.anim-lab-style').forEach((btn) => {
      btn.classList.toggle('selected', current[btn.dataset.attr] === btn.dataset.style);
    });
    panel.querySelectorAll('button[data-theme]').forEach((btn) => {
      const t = ANIM_THEMES.find((x) => x.key === btn.dataset.theme);
      btn.classList.toggle('selected', !!t && ['tab', 'win', 'line', 'term'].every((k) => t[k] === current[k]));
    });
    const check = panel.querySelector('input[data-check="termSwitch"]');
    if (check) check.checked = !!this._termAnimOnSwitch;
    panel.querySelector('input[data-range="stagger"]').value = String(this._tabAnimStagger);
    panel.querySelector('output[data-out="stagger"]').textContent = `${this._tabAnimStagger}ms`;
    panel.querySelector('input[data-range="speed"]').value = String(this._animSpeed);
    panel.querySelector('output[data-out="speed"]').textContent = `${this._animSpeed.toFixed(1)}x`;
  },

  _clearEntranceDemo() {
    clearTimeout(this._animDemoTimer);
    clearTimeout(this._animDemoWindowTimer);
    document.querySelectorAll('.session-tab[data-demo]').forEach((el) => el.remove());
    document.querySelectorAll('.subagent-window[data-demo]').forEach((el) => el.remove());
    document.getElementById('animLabLines')?.remove();
  },

  /**
   * The demo line gets its OWN svg overlay rather than sharing #connectionLines.
   * That overlay is rebuilt from real windows via `svg.innerHTML = ''`, so a fake
   * path dropped into it is erased the moment anything triggers a redraw -
   * including the demo window's own entrance finishing.
   */
  _demoLineSvg() {
    let svg = document.getElementById('animLabLines');
    if (!svg) {
      svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
      svg.id = 'animLabLines';
      svg.setAttribute('class', 'connection-lines-svg');
      document.body.appendChild(svg);
    }
    return svg;
  },

  /** @param {'tabs'|'term'|'window'|'all'} what */
  demoEntrance(what = 'all') {
    this._clearEntranceDemo();

    // The pane is a real, shared element rather than a throwaway, so replay it
    // through the same entry point a real launch uses (bypassing the owed-id
    // check, which only exists to keep background sessions from hijacking it).
    if (what === 'term' || what === 'all') {
      const wasOnSwitch = this._termAnimOnSwitch;
      this._termAnimOnSwitch = true;
      this.playTerminalEntrance(null);
      this._termAnimOnSwitch = wasOnSwitch;
    }
    if (what === 'term') return;

    const tabCount = what === 'window' ? 1 : 4;
    const tabs = this._demoTabs(tabCount);
    let total = Math.max(this._tabAnimDuration() + tabCount * this._tabAnimStagger, this._termAnimDuration());

    if (what !== 'tabs') {
      // Give the tab cascade a beat, so the window reads as coming out of it.
      const lead = what === 'all' ? Math.min(320, this._tabAnimStagger * 2) : 0;
      this._animDemoWindowTimer = setTimeout(() => this._demoWindow(tabs[0]), lead);
      total = Math.max(total, lead + this._winAnimDuration() + this._lineAnimDuration() + BEAM_HOLD_MS);
    }

    this._animDemoTimer = setTimeout(() => this._clearEntranceDemo(), total + 1800);
  },

  /** Append `count` throwaway tabs and run the tab entrance on them. */
  _demoTabs(count) {
    const container = this.$('sessionTabs');
    if (!container) return [];
    const made = [];
    const base = this.sessions?.size || 0;

    for (let i = 0; i < count; i++) {
      const tab = document.createElement('div');
      tab.className = 'session-tab';
      tab.dataset.demo = '1';
      tab.dataset.color = ['green', 'blue', 'purple', 'orange', 'pink', 'yellow', 'red'][i % 7];
      tab.innerHTML = `
        <span class="tab-number">${base + i + 1}</span>
        <span class="tab-status idle" aria-hidden="true"></span>
        <span class="tab-info"><span class="tab-name-row">
          <span class="tab-name">w${base + i + 1}-demo</span>
        </span></span>`;
      container.appendChild(tab);
      made.push(tab);
      if (this._tabAnimStyle !== 'off') {
        tab.style.setProperty('--tab-enter-delay', `${i * this._tabAnimStagger}ms`);
        void tab.offsetWidth; // force layout so the class add starts a fresh run
        tab.classList.add('tab-enter');
      }
    }
    return made;
  },

  /** Append a throwaway agent window under `originTab`, plus its connection line. */
  _demoWindow(originTab) {
    const tabRect = originTab?.getBoundingClientRect();
    const win = document.createElement('div');
    win.className = 'subagent-window';
    win.dataset.demo = '1';
    win.style.width = '360px';
    win.style.height = '220px';
    win.style.left = `${Math.max(24, (tabRect?.left ?? 120) - 40)}px`;
    win.style.top = `${(tabRect?.bottom ?? 60) + 160}px`;
    win.style.zIndex = '1001';
    win.innerHTML = `
      <div class="subagent-window-header">
        <div class="subagent-window-title"><span class="icon">&#129302;</span><span class="id">demo-agent</span>
          <span class="status running">running</span></div>
      </div>
      <div class="subagent-window-body"><div class="subagent-empty">Preview window</div></div>`;
    document.body.appendChild(win);
    this.applyWindowEntrance(win);
    this._demoLine(tabRect, win);
  },

  /** Draw a fake tab→window line into the lab's own overlay and animate it. */
  _demoLine(tabRect, win) {
    if (!tabRect) return;
    const svg = this._demoLineSvg();
    const winRect = win.getBoundingClientRect();
    const x1 = tabRect.left + tabRect.width / 2;
    const y1 = tabRect.bottom;
    const x2 = winRect.left + winRect.width / 2;
    const y2 = winRect.top;
    const midY = (y1 + y2) / 2;

    const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
    path.setAttribute('d', `M ${x1} ${y1} C ${x1} ${midY}, ${x2} ${midY}, ${x2} ${y2}`);
    path.setAttribute('class', 'connection-line');
    path.dataset.demo = '1';
    svg.appendChild(path);

    if ((this._lineAnimStyle || LINE_ANIM_DEFAULT) === 'off') return;
    const len = Math.max(1, Math.round(path.getTotalLength()));
    path.style.setProperty('--line-len', `${len}px`);
    path.style.setProperty('--line-enter-delay', '0ms');
    path.classList.add('line-enter');

    if (this._lineAnimStyle === 'packet') {
      const packet = path.cloneNode(false);
      packet.setAttribute('class', 'connection-line-packet');
      packet.dataset.demo = '1';
      packet.style.setProperty('--line-len', `${len}px`);
      packet.style.setProperty('--line-enter-delay', '0ms');
      svg.appendChild(packet);
    }
  },
});