diff --git a/skills/react-devtool-cli-repo/SKILL.md b/skills/react-devtool-cli-repo/SKILL.md index 5ad5e9e..d3fc921 100644 --- a/skills/react-devtool-cli-repo/SKILL.md +++ b/skills/react-devtool-cli-repo/SKILL.md @@ -1,6 +1,6 @@ --- name: react-devtool-cli-repo -description: Maintain and validate the `react-devtool-cli` repository. Use when working inside this repo to change source, run tests, validate `test-app` browser flows, inspect snapshot-aware node commands, verify profiler behavior, confirm package contents, or align runtime field semantics with the bundled repo references. +description: Maintain and validate the `react-devtool-cli` repository. Use when working inside this repo to change source, run tests, validate `test-app` browser flows, inspect snapshot-aware node commands, use interactive node picking, verify profiler behavior and export workflows, confirm package contents, or align runtime field semantics with the bundled repo references. Also use when debugging test failures, checking engine selection logic, or reviewing session lifecycle implementation. --- # React Devtool CLI Repo @@ -29,7 +29,8 @@ Use this skill for repository maintenance and validation. Treat the skill bundle 4. Treat `test-app/` as the default browser-backed validation target. 5. Run `node bin/rdt.js session doctor --session ` before profiler-heavy or helper-heavy validation. 6. Prefer built-in `interact` commands before ad hoc Playwright helper scripts. -7. Keep user-owned working tree changes out of commits unless explicitly requested. +7. Use `session status` to check session health and `session close` to clean up sessions. +8. Keep user-owned working tree changes out of commits unless explicitly requested. ## Core Repo Commands @@ -38,6 +39,8 @@ Use this skill for repository maintenance and validation. Treat the skill bundle ```bash node bin/rdt.js --help node bin/rdt.js session doctor --session app +node bin/rdt.js session status --session app +node bin/rdt.js session close --session app node bin/rdt.js interact wait --session app --ms 250 ``` @@ -54,6 +57,7 @@ npm run dev -- --host 127.0.0.1 --port 3000 node bin/rdt.js session open --url http://127.0.0.1:3000 --session app --timeout 10000 ``` +- Advanced session open options: `--browser`, `--engine`, `--channel`, `--device`, `--storage-state`, `--user-data-dir`, `--headless=false`. - Use `session attach` only when an external Chromium with CDP is already running. ## Validate Snapshot Workflows @@ -62,6 +66,7 @@ node bin/rdt.js session open --url http://127.0.0.1:3000 --session app --timeout - Persist the returned `snapshotId`. - Pass `--snapshot ` to `node search`, `node inspect`, `node highlight`, and `source reveal`. - If `snapshot-expired` appears, collect a fresh tree and do not reuse old node ids. +- Use `node pick` for interactive browser-based node selection (30s default timeout). Example: @@ -69,16 +74,17 @@ Example: node bin/rdt.js tree get --session app node bin/rdt.js node search SlowSearchDemo --session app --snapshot node bin/rdt.js node inspect --session app --snapshot +node bin/rdt.js node pick --session app --timeout-ms 30000 ``` ## Validate Profiler Workflows - Use the profiler against `test-app/`, especially `SlowSearchDemo`, `ResultList`, and `ResultRow`. - Treat profiler output as commit-oriented analysis with explicit limitations. -- Use the newer drill-down commands for commit analysis: +- Use the drill-down commands for commit analysis: ```bash -node bin/rdt.js profiler start --session app +node bin/rdt.js profiler start --session app [--profile-id ] node bin/rdt.js profiler stop --session app node bin/rdt.js profiler summary --session app node bin/rdt.js profiler commits --session app @@ -86,16 +92,20 @@ node bin/rdt.js profiler commit --session app node bin/rdt.js profiler ranked --session app --limit 10 node bin/rdt.js profiler flamegraph --session app node bin/rdt.js profiler compare --session app --left baseline --right candidate +node bin/rdt.js profiler export --session app [--output file.jsonl] [--compress] node bin/rdt.js node inspect --session app --commit ``` - Read `measurementMode`, `measuresComponentDuration`, `limitations`, and `runtimeWarnings` literally. - Treat rerender reasons as snapshot-diff inference, not changed-fiber truth. - Treat `node inspect --commit` node ids as commit-local profiler ids, not general tree snapshot ids. +- `flamegraph` and `export` do not support `--format yaml`. +- Exported `.jsonl` / `.jsonl.gz` files can be used as inputs to `profiler compare`. ## Prefer Built-in Interact Commands - Use `interact click`, `interact type`, `interact press`, and `interact wait` before ad hoc helper scripts. +- All interact commands accept optional `--timeout-ms ` for element location timeout. - Keep selectors deterministic and CSS-based. - Use `session doctor` to confirm `supportsBuiltInInteract` before relying on interaction replay. diff --git a/skills/react-devtool-cli-repo/references/repo-workflows.md b/skills/react-devtool-cli-repo/references/repo-workflows.md index 81e47c5..fafbb18 100644 --- a/skills/react-devtool-cli-repo/references/repo-workflows.md +++ b/skills/react-devtool-cli-repo/references/repo-workflows.md @@ -29,6 +29,33 @@ npm run dev -- --host 127.0.0.1 --port 3000 node bin/rdt.js session open --url http://127.0.0.1:3000 --session app --timeout 10000 ``` +- Advanced session open options: + - `--browser chromium|firefox|webkit` — defaults to chromium + - `--engine auto|custom|devtools` — defaults to auto + - `--channel ` — browser channel variant + - `--device ` — device emulation profile + - `--storage-state ` — saved browser state + - `--user-data-dir ` — persistent browser data directory + - `--headless=false` — launch with visible browser window + +- Use `session attach` only when an external Chromium with CDP is already running. + +## Session Management + +- Check session state with `session status`: + +```bash +node bin/rdt.js session status --session app +``` + +- Close a session when done: + +```bash +node bin/rdt.js session close --session app +``` + +Close attempts graceful shutdown first, then force-kills the process tree as fallback. + ## Validation Lanes ### Snapshot-aware inspection @@ -38,17 +65,42 @@ node bin/rdt.js session open --url http://127.0.0.1:3000 --session app --timeout - Pass `--snapshot ` to `node search`, `node inspect`, `node highlight`, and `source reveal`. - If `snapshot-expired` appears, collect a fresh tree and rerun lookup commands before trusting node ids. +### Interactive node selection + +- Use `node pick` to let the user click a component in the browser: + +```bash +node bin/rdt.js node pick --session app [--timeout-ms 30000] +``` + +Default timeout is 30 seconds. Returns the picked node details. + ### Interaction - Prefer built-in `interact click`, `interact type`, `interact press`, and `interact wait`. - Keep selectors deterministic and CSS-based. - Run `session doctor` first to confirm `supportsBuiltInInteract`. +- All interact commands accept optional `--timeout-ms ` for element location timeout. ### Profiler - Treat profiler output as commit-oriented analysis, not full DevTools frontend state. -- Use `profiler start`, `profiler stop`, `profiler summary`, `profiler commits`, `profiler commit`, `profiler ranked`, `profiler flamegraph`, and `profiler compare` for drill-down. +- Use `profiler start [--profile-id ]`, `profiler stop`, `profiler summary`, `profiler commits`, `profiler commit`, `profiler ranked`, `profiler flamegraph`, and `profiler compare` for drill-down. - Use `node inspect --commit ` only with profiler-local node ids from that commit. +- `flamegraph` does not support `--format yaml`. + +### Profiler export + +- Export recorded profiler events to NDJSON: + +```bash +node bin/rdt.js profiler export --session app [--output file.jsonl] [--compress] +``` + +- `--compress` produces gzip-compressed `.jsonl.gz`. +- `--output` sets the file path; defaults to `-.jsonl` in the current directory. +- `export` does not support `--format yaml`. +- Exported files can be used as `--left` or `--right` inputs to `profiler compare`. ## Publish Checks diff --git a/skills/react-devtool-cli-repo/references/runtime-semantics.md b/skills/react-devtool-cli-repo/references/runtime-semantics.md index ee2a8ca..d489c8f 100644 --- a/skills/react-devtool-cli-repo/references/runtime-semantics.md +++ b/skills/react-devtool-cli-repo/references/runtime-semantics.md @@ -6,19 +6,49 @@ - `react-devtools-core` is a naming and concept reference, not a runtime dependency. - `react-debug-tools` is a weak implementation reference in the current repo state. +## Engine Selection + +`rdt` supports multiple inspection engines, selected per-session via `--engine`: + +| Engine | Behavior | +|---|---| +| `auto` (default) | Resolves the best available engine at runtime; prefers custom, falls back to devtools | +| `custom` | Uses `rdt`'s own snapshot-diff inspection engine for tree collection and reason attribution | +| `devtools` | Uses the DevTools-aligned hook-based engine that mirrors `react-devtools-core` conventions | + +Engine selection affects: +- **Tree collection**: Each engine maintains its own snapshot store; snapshots from one engine are not interchangeable with another. +- **Reason attribution**: The custom engine uses snapshot-diff inference; the devtools engine relies on hook-reported change data. +- **Profiler capabilities**: The devtools engine may report different `measurementMode` and `measuresComponentDuration` values. +- **Available metadata fields**: Fields like `engineFallback`, `engineReasons`, and `availableEngines` appear in `session doctor` and `session status` output. + +### Engine fields in doctor/status output + +| Field | Meaning | +|---|---| +| `enginePreference` | The engine requested via `--engine` | +| `selectedEngine` | The engine actually in use after resolution | +| `availableEngines` | Engines that the runtime supports for this page | +| `recommendedEngine` | The engine the runtime considers optimal | +| `engineFallback` | `true` if the selected engine differs from the preference (auto resolved to a specific engine, or a forced engine was unavailable) | +| `engineReasons` | Human-readable explanation of why the engine was selected | + ## Concept Mapping | `rdt` concept | Closest DevTools concept | Meaning | | --- | --- | --- | | Playwright-managed session | Runtime/backend host process | `rdt` owns browser and session lifecycle directly. | | `__REACT_DEVTOOLS_GLOBAL_HOOK__` shim | DevTools global hook | Used for renderer and root discovery without adopting the frontend protocol. | -| `collectTree()` snapshot | Inspected tree payload | `rdt` serializes a CLI-friendly tree snapshot. | +| `collectTree()` snapshot | Inspected tree payload | `rdt` serializes a CLI-friendly tree snapshot. Engine-specific. | | `snapshotId` | No direct public equivalent | CLI-specific stability layer for follow-up commands. | -| Snapshot-local node id | Inspector element identity | Only valid within the collected snapshot. | +| Snapshot-local node id | Inspector element identity | Only valid within the collected snapshot and its engine. | | `node inspect` payload | Inspected element details | Snapshot-time serialized element details. | +| `node pick` | Element picker | Interactive browser-based component selection. | | Profiler summary/export | Profiler commit data | Commit-oriented summaries and NDJSON export. | | `interact` commands | No direct public equivalent | Playwright-backed deterministic interaction helpers. | | `session doctor` | No direct public equivalent | CLI-specific readiness and trust-boundary report. | +| `session status` | No direct public equivalent | Current session state including transport, engine, and runtime info. | +| `session close` | No direct public equivalent | Graceful shutdown with force-kill fallback. | ## Interpretation Rules @@ -27,16 +57,21 @@ - Treat `hooks` and `context` as simplified serialized views. - Expect `source` to be `null` in many builds when `_debugSource` is unavailable. - Treat rerender reasons as snapshot-diff inference, not changed-fiber truth. +- Check `selectedEngine` and `engineFallback` before making claims about what the profiler or inspector can observe. ## Snapshot Rules - Persist `snapshotId` from `tree get`. - Reuse node ids only with the same snapshot. - If a requested snapshot expires, recollect the tree before further node lookup. +- Snapshots are engine-specific: a snapshot collected under the custom engine cannot be used with the devtools engine, and vice versa. ## Profiler Rules - `measurementMode`, `measuresComponentDuration`, and `tracksChangedFibers` are capability flags that limit what can be claimed. - `nodeCountMeaning` is `live-tree-size-at-commit`. +- `profiler start` accepts `--profile-id` to assign a custom identifier. - `profiler compare` works with in-memory profile ids or exported `.jsonl` / `.jsonl.gz` files. +- `profiler export` writes NDJSON with optional gzip compression (`--compress`). - `node inspect --commit ` expects profiler-local node ids, not ids from `tree get`. +- Exported NDJSON includes engine metadata (`engine`, `enginePreference`, `selectedEngine`, `measurementSource`) in the summary record. diff --git a/skills/react-devtool-cli/SKILL.md b/skills/react-devtool-cli/SKILL.md index fda031d..e6c579d 100644 --- a/skills/react-devtool-cli/SKILL.md +++ b/skills/react-devtool-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: react-devtool-cli -description: Operate and troubleshoot the published `rdt` CLI outside the source repo. Use when a user wants help installing `react-devtool-cli`, opening or attaching sessions, collecting tree snapshots, inspecting nodes, running profiler flows, interpreting `session doctor`, comparing custom vs DevTools-aligned engine output, or understanding CLI trust boundaries. +description: Operate and troubleshoot the published `rdt` CLI outside the source repo. Use when a user wants help installing `react-devtool-cli`, opening or attaching sessions, checking session status, closing sessions, collecting tree snapshots, inspecting or picking nodes, running profiler flows, exporting profiler data, interpreting `session doctor`, comparing custom vs DevTools-aligned engine output, or understanding CLI trust boundaries. Also use when the user mentions React performance debugging, component tree inspection, or Playwright-based React tooling. --- # React Devtool CLI @@ -9,6 +9,8 @@ description: Operate and troubleshoot the published `rdt` CLI outside the source Use this skill for installed-CLI workflows used by real end users after distribution. Prefer published `rdt` commands and bundled references; if the task requires changing source code, validating `test-app/`, or editing repository docs, switch to `react-devtool-cli-repo` instead. +Requires Node.js >= 22. + ## Start Here - Read [references/cli-workflows.md](references/cli-workflows.md) before giving commands or interpreting output. @@ -26,8 +28,46 @@ Use this skill for installed-CLI workflows used by real end users after distribu 4. Prefer `--engine auto` unless the user explicitly wants to force `custom` or `devtools`. 5. Collect a tree with `tree get` and persist `snapshotId`. 6. Use snapshot-aware node commands with the same `snapshotId`. -7. Run profiler commands only after a reproducible user interaction is defined. -8. Prefer `primaryUpdateCommitId` or `recommendedCommitIds` over blindly drilling into `commit-1`. +7. For interactive selection, use `node pick` to let the user click a component in the browser. +8. Run profiler commands only after a reproducible user interaction is defined. +9. Prefer `primaryUpdateCommitId` or `recommendedCommitIds` over blindly drilling into `commit-1`. +10. Use `profiler export` with `--compress` to save profiler data for later comparison. +11. Use `session status` to check session health and `session close` to clean up when done. + +## Command Reference + +### Session +- `session open` — Launch a local Playwright-managed browser session +- `session connect` — Connect to a remote Playwright WebSocket endpoint +- `session attach` — Connect to an existing Chromium CDP target +- `session status` — Check current session state +- `session doctor` — Diagnose runtime readiness and trust boundaries +- `session close` — Gracefully close or force-kill a session + +### Inspection +- `tree get` — Collect a component tree snapshot (returns `snapshotId`) +- `node search` — Find nodes by display name within a snapshot +- `node inspect` — Inspect a specific node (supports `--commit` for profiler context) +- `node highlight` — Highlight a node in the browser +- `node pick` — Interactively select a node by clicking in the browser +- `source reveal` — Open the source file for a node in the editor + +### Interaction +- `interact click` — Click a DOM element by CSS selector +- `interact type` — Type text into an element +- `interact press` — Press a keyboard key +- `interact wait` — Wait for a duration + +### Profiler +- `profiler start` — Begin profiling (accepts `--profile-id`) +- `profiler stop` — Stop the current profiling session +- `profiler summary` — Get commit count, node ranges, measurement modes +- `profiler commits` — List all captured commits +- `profiler commit` — Detailed analysis for a specific commit +- `profiler ranked` — Ranked component analysis (accepts `--limit`) +- `profiler flamegraph` — Flamegraph visualization for a commit +- `profiler compare` — Compare two profiles by id or exported file path +- `profiler export` — Export profiler events as NDJSON (accepts `--output`, `--compress`) ## Interpretation Rules diff --git a/skills/react-devtool-cli/references/cli-workflows.md b/skills/react-devtool-cli/references/cli-workflows.md index 6a6a84a..53b951d 100644 --- a/skills/react-devtool-cli/references/cli-workflows.md +++ b/skills/react-devtool-cli/references/cli-workflows.md @@ -2,6 +2,7 @@ ## Install and Invocation +- Requires Node.js >= 22. - Install globally with `npm install -g react-devtool-cli`. - If a global install is not desired, use `npx react-devtool-cli ...`. - Confirm the CLI is available with: @@ -10,11 +11,63 @@ rdt --help ``` -## Session Selection +## Session Lifecycle -- Use `rdt session open --url --session ` for the normal local path. -- Use `rdt session connect --ws-endpoint --target-url --session ` when Playwright is already running remotely. -- Use `rdt session attach --cdp-url --target-url --session ` only for an existing Chromium CDP target. +### Opening a session + +Use `session open` for the normal local Playwright path: + +```bash +rdt session open --url --session +``` + +Full options for `session open`: + +| Option | Default | Description | +|---|---|---| +| `--url ` | *required* | Target URL to open | +| `--browser chromium\|firefox\|webkit` | `chromium` | Browser engine | +| `--engine auto\|custom\|devtools` | `auto` | React inspection engine | +| `--channel ` | | Browser channel variant (e.g. `chrome`, `msedge`) | +| `--device ` | | Device profile name for emulation | +| `--storage-state ` | | Saved browser state file (cookies, localStorage) | +| `--user-data-dir ` | | Persistent browser data directory | +| `--headless=false` | `true` | Set `false` to launch visible browser | +| `--timeout ` | `15000` | Connection timeout | +| `--session ` | auto-generated | Session identifier | +| `--format json\|yaml\|pretty` | `json` | Output format | + +### Connecting to a remote Playwright instance + +```bash +rdt session connect --ws-endpoint --target-url --session +``` + +Accepts `--browser`, `--engine`, `--target-url`, `--timeout`, `--session`, `--format`. + +### Attaching to Chromium CDP + +```bash +rdt session attach --cdp-url --target-url --session +``` + +Chromium only. Accepts `--engine`, `--target-url`, `--timeout`, `--session`, `--format`. + +### Checking session status + +```bash +rdt session status --session +``` + +Returns current session state including transport, browser, engine, and runtime readiness. + +### Closing a session + +```bash +rdt session close --session +``` + +Attempts a graceful shutdown first; falls back to force-killing the session process tree if the server does not respond within 3 seconds. ## Inspection Workflow @@ -23,6 +76,8 @@ rdt session doctor --session demo rdt tree get --session demo rdt node search App --session demo --snapshot rdt node inspect --session demo --snapshot +rdt node highlight --session demo --snapshot +rdt source reveal --session demo --snapshot ``` - `tree get` returns `snapshotId`. @@ -30,19 +85,27 @@ rdt node inspect --session demo --snapshot - If `--snapshot` is omitted, commands fall back to the latest collected snapshot. - If a requested snapshot was evicted, commands fail with `snapshot-expired`. +### Interactive node selection + +```bash +rdt node pick --session demo [--timeout-ms 30000] +``` + +Lets the user click a component in the browser to select it. Returns the picked node details. Default timeout is 30 seconds. + ## Interaction Workflow - Prefer built-in interaction commands: - - `rdt interact click --session --selector ` - - `rdt interact type --session --selector --text ` - - `rdt interact press --session --key [--selector ]` + - `rdt interact click --session --selector [--timeout-ms ]` + - `rdt interact type --session --selector --text [--timeout-ms ]` + - `rdt interact press --session --key [--selector ] [--timeout-ms ]` - `rdt interact wait --session --ms ` - Use `session doctor` to confirm `supportsBuiltInInteract` before relying on them. ## Profiler Workflow ```bash -rdt profiler start --session demo +rdt profiler start --session demo [--profile-id ] rdt profiler stop --session demo rdt profiler summary --session demo rdt profiler commits --session demo @@ -53,10 +116,23 @@ rdt profiler flamegraph --session demo rdt profiler compare --session demo --left baseline --right candidate ``` +- `profiler start` accepts `--profile-id ` to assign a custom profile identifier; auto-generated if omitted. - Treat profiler output as commit-oriented analysis. - Treat `commitKind`, `isLikelyInitialMount`, `isInteractionCandidate`, `primaryUpdateCommitId`, and `recommendedCommitIds` as the first pass for commit selection. -- `profiler compare` accepts in-memory profile ids or exported `.jsonl` / `.jsonl.gz` files. -- `node inspect --commit ` expects profiler-local node ids from that commit. +- `profiler compare` accepts in-memory profile ids or exported `.jsonl` / `.jsonl.gz` file paths. +- `node inspect --commit ` expects profiler-local node ids from that commit, not snapshot ids from `tree get`. +- `flamegraph` does not support `--format yaml`. + +### Exporting profiler data + +```bash +rdt profiler export --session demo [--output file.jsonl] [--compress] +``` + +- Exports recorded profiler events as NDJSON (`.jsonl`). +- `--compress` writes gzip-compressed `.jsonl.gz`. +- `--output` sets the file path; defaults to `-.jsonl` in the current directory. +- `export` does not support `--format yaml`. ## Doctor and Trust Boundaries @@ -64,8 +140,20 @@ rdt profiler compare --session demo --left baseline --right candidate - Read `recommendedWorkflow`, `unsafeConclusions`, `helperStrategy`, `observationLevel`, `limitations`, and `runtimeWarnings` literally. - `helperImportTarget` exists for cases where `rdt` can resolve Playwright but standalone helper scripts cannot. +## Engine Selection + +The `--engine` flag controls how `rdt` inspects the React tree: + +| Engine | Behavior | +|---|---| +| `auto` | Tries the custom engine first, falls back to DevTools-aligned if unavailable | +| `custom` | Uses `rdt`'s own snapshot-diff inspection engine | +| `devtools` | Uses the DevTools-aligned hook-based engine | + +Engine choice affects profiler capabilities, rerender reason attribution, and available metadata fields. Use `session doctor` to see which engine was actually selected (`selectedEngine`) and whether a fallback occurred (`engineFallback`). + ## Output Formats - Default output is `json`. - Human-readable output supports `--format yaml` and `--format pretty`. -- Raw profiler export is NDJSON as `.jsonl` or `.jsonl.gz` with `--compress`. +- `flamegraph` and `export` commands do not support `yaml`.