agentleFS
ahilles107ahilles107/gravity/.claude/skills/terminal-perf-test/SKILL.md

terminal-perf-test

Skill22 starsChanged 45 days agoMITView on GitHub

Verify terminal rendering performance and correctness (WebGL renderer, bot-switch terminal cache, forced-repaint nudge, replay bottom-pin) by running the real desktop app in Chrome against a local gravityd with the double runtime, seeding heavy ANSI output, and stress-testing switching/scrolling/streaming. Use when changing TerminalPane, terminalCache, the daemon's attach/replay/resize path, or investigating terminal CPU, lag, black screens, or rendering artifacts.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use Node 22+ for the driver and the prerequisites in CONTRIBUTING.md.

    line 22
  2. Distinctive:

    Run from the repository root in a dedicated terminal.

    line 23
  3. Very specific:

    Wait for $GRAVITY_HOME/gravityd.port, confirm it is 49555 and the recorded PID is still running, then check curl --fail …

    line 45
  4. Very specific:

    Stop on startup failure. Do not connect the driver to an installed daemon or use it with pty: its generated input belongs only in the echo …

    line 47
  5. Distinctive:

    Start the frontend in this shell, with shell tracing off.

    line 50
  6. Distinctive:

    Run each check; all must hold.

    line 77
  7. Very specific:

    Read afterwards: avg fps ≈ display refresh rate, longTasks 0, worst frame well under 100 ms.

    line 126
  8. Very specific:

    After a React tree crash, HMR cannot revive it and a stale module graph may linger: always location.reload() before re-testing a fix.

    line 139
  9. Very specific:

    Stop the foreground Vite session with Ctrl-C.

    line 149

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Terminal rendering performance test

Runs the real stack locally — gravityd with the deterministic double runtime, the Vite-served desktop frontend in Chrome — then seeds terminals with more output than the daemon's 1 MiB scrollback ring and stress-tests the paths that have historically broken: bulk replay after eviction, rapid bot switching, live streaming, scrolling under load.

Why the double runtime: it echoes every input byte back as terminal output (so a driver script can pump arbitrary ANSI at any rate), and it prints a [resize CxR] marker for every pty resize — making the forced-repaint nudge (shrink to rows-1, restore ~50 ms later; see REPAINT_NUDGE_DELAY in crates/gravityd/src/supervisor.rs) visible on screen.

Setup

Use Node 22+ for the driver and the prerequisites in CONTRIBUTING.md. Run from the repository root in a dedicated terminal. Verify test ports 49555 and 1420 are free first; choose unused ports consistently if needed.

umask 077
PERF_DIR=$(mktemp -d "${TMPDIR:-/tmp}/gravity-perf.XXXXXX")
PERF_DIR=$(cd "$PERF_DIR" && pwd -P)
export GRAVITY_HOME="$PERF_DIR"
export GRAVITY_WS=ws://127.0.0.1:49555/ws
cargo build -p gravityd
cat > "$GRAVITY_HOME/gravityd.toml" <<EOF
home = "$GRAVITY_HOME"
bind = ["127.0.0.1"]
port = 49555
negotiate_port = false
runtime = "double"
supervision_interval_ms = 500
EOF
./target/debug/gravityd --config "$GRAVITY_HOME/gravityd.toml" > "$PERF_DIR/gravityd.log" 2>&1 &
PERF_DAEMON_PID=$!

Wait for $GRAVITY_HOME/gravityd.port, confirm it is 49555 and the recorded PID is still running, then check curl --fail http://127.0.0.1:49555/health. Stop on startup failure. Do not connect the driver to an installed daemon or use it with pty: its generated input belongs only in the echo runtime.

Start the frontend in this shell, with shell tracing off. The dev token stays in the local process environment; do not print it or paste it into browser commands or chat.

export VITE_GRAVITY_DEV_PORT=49555
export VITE_GRAVITY_DEV_TOKEN="$(cat "$GRAVITY_HOME/secrets/client.token")"
(cd apps/desktop && env -u CONDUCTOR_PORT pnpm dev)

Open http://localhost:1420/ with available browser automation in a fresh test profile. Stored connection settings override these defaults: confirm the footer shows 127.0.0.1:49555 · connected before interacting. Never expose or deploy the dev frontend containing this token.

In another terminal, set GRAVITY_HOME to this run's exact directory and GRAVITY_WS to the matching loopback URL, then seed:

node .claude/skills/terminal-perf-test/scripts/drive.mjs setup

This creates project "perf" and turbo1–turbo5. Turbo1 exceeds the 1 MiB ring; the others receive smaller histories. Keep the printed bot IDs for stream mode.

Verification checklist

Run each check; all must hold. Read browser console errors after every phase using the available tools; zero exceptions are expected throughout.

  1. WebGL renderer active — in the page:
    const host = document.querySelector('.terminal-host');
    ({ canvases: host.querySelectorAll('canvas').length,      // > 0
       domRows: host.querySelector('.xterm-rows') === null }) // true: no DOM renderer
  2. Bulk replay paints and lands pinned — select turbo1 (first visit = full replay of the ring). The transcript must be visible without scrolling and end at the newest line:
    const vp = document.querySelector('.xterm-viewport');
    vp.scrollHeight - vp.clientHeight - vp.scrollTop   // 0 once replay settles
    A screenshot mid-replay legitimately shows the tail still streaming; re-check after a few seconds before calling it a failure.
  3. Cache reuse on switch-back — tag the terminal's element, switch to another bot and back; the same node must return and no term.reset path should run (screen identical, no repaint flash, no new [resize ...] shrink marker):
    document.querySelector('.terminal-host').firstElementChild.dataset.perfTag = 'x';
    // switch away and back, then:
    document.querySelector('.terminal-host').firstElementChild.dataset.perfTag  // 'x'
  4. Eviction survives — visit 4+ other bots (cache holds 3), then return to turbo1. Expect: full replay again (fresh node, tag gone), content pinned at the bottom, and a nudge marker pair like [resize 163x45][resize 163x46] appended — shrink and restore observed by the runtime as two separate sizes. No console errors: eviction disposes a parked WebGL terminal, which is the path that once crashed the whole app.
  5. Live-stream stress with instrumentation — install the meter, then node .../drive.mjs stream <turbo1-id> 20, and during it scroll up (view must hold position while streaming), switch away and back:
    window.__perf = { frames: 0, longTasks: 0, worstFrame: 0, start: performance.now(), last: performance.now() };
    const tick = () => { const now = performance.now(); const d = now - window.__perf.last;
      if (d > window.__perf.worstFrame) window.__perf.worstFrame = d;
      window.__perf.last = now; window.__perf.frames++; requestAnimationFrame(tick); };
    requestAnimationFrame(tick);
    new PerformanceObserver(l => { for (const e of l.getEntries()) window.__perf.longTasks++; })
      .observe({ entryTypes: ['longtask'] });
    Read afterwards: avg fps ≈ display refresh rate, longTasks 0, worst frame well under 100 ms. Record the display refresh rate, hardware and elapsed time; compare with an unchanged build on the same machine. Reload afterwards to stop the meter.
  6. Rapid-switch storm — 25 programmatic clicks across all bots at 120 ms intervals (dispatch mousedown/mouseup/click on the sidebar rows from the javascript tool). Expect a fully painted, pinned terminal and zero console errors at the end.

Pitfalls learned the hard way

  • Vite/esbuild strips comments — never verify which code the page runs by fetching source and searching for a comment; search for a code token.
  • After a React tree crash, HMR cannot revive it and a stale module graph may linger: always location.reload() before re-testing a fix.
  • Chrome/Blink hides the DOM-renderer cost at this terminal size; the CPU win matters on WKWebView (prod). For renderer A/B evidence, comment out the loadWebgl(term) call in TerminalPane.tsx temporarily — and put it back.
  • The final prod check is still a release build on macOS: WKWebView is a different engine than the Chrome used here.

Cleanup

Stop the foreground Vite session with Ctrl-C. Stop only the daemon started in this live shell (kill "$PERF_DAEMON_PID"; wait "$PERF_DAEMON_PID"). If the session was lost, verify process ownership again before signalling. Do not use broad process-name matching. Unset the temporary Vite token environment.

Close the test browser profile. Retain the run directory for review and ask before deleting its exact path. Restore only your temporary A/B edits, preserving any pre-existing changes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.