docs: Explorer parity + native-feel performance plan#304
Conversation
Detailed 4-phase plan for the Explorer-parity epic (https://trello.com/c/hmVekNGe) with deterministic checkpoint gates per phase. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: f6e6062 The changes in this PR will be included in the next version bump. This PR includes changesets to release 13 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
- Renumber phases linearly (metrics harness is now Phase 1) - Add full Explorer parity inventory as source-of-truth table - Add Explorer validation standards V1-V8 as testable gates - Add monorepo package impact matrix and testing strategy - Waive arrow-key navigation (owner decision) - Split drag & drop into its own revisit phase with dogfood spike - Add Phase 6 proof/showcase and Phase 7 post-validation cleanup Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…f work - Perf truth is now a launched VS Code window (@vscode/test-electron) with same-session built-in Explorer ratio comparisons; no headless perf anywhere - Remove drag & drop phase entirely (deferred to future epic; follow-up card filed in showcase phase); renumber to 6 phases - New dependency-maximization tasks: tree-sitter incremental re-parse + worker-pool cold index, ladybugdb patch-only writes off the interaction path, d3/react-force-graph simulation budget + sprite caching + LOD - Quality-tool loop documented: scoped/differential mutation only, mutation- site thresholds as a split-the-file signal, organization tool after, iterate until outputs are clean Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…n model, plugin ecosystem - Research appendix: Obsidian graph internals (PixiJS/WebGL, ~25k ceiling, main-thread sim bottleneck, idle CPU, MetadataCache decoupling, plugin lifecycle/manifest/template model) with sources; VS Code standards; react-force-graph + d3-force + tree-sitter levers - Code-audited monorepo facts: no incremental tree-sitter parse, per-call parser construction, zero worker_threads, scope toggles round-trip to host - New giant fixture (30k files) + gate 3-J to beat Obsidian's documented limits on react-force-graph, with worker-sim rung before any PixiJS talk - Phase 4: Graph Scope/projection flow (webview-local masks, hydration protocol, diff edges) with frame-budget toggle gates - Phase 5: desktop interaction model per owner spec (marquee default, Ctrl-drag pan, physical group drag, selection-wide context menus) - Phase 7: plugin ecosystem modeled on Obsidian + VS Code patterns - Executor reframed for GPT 5.6 autonomous loop on dedicated Mac mini; superpowers references replaced with Matt Pocock's skills Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
pnpm perf -- --smoke --fixture small --runs 1 --no-budget Before: unavailable (no in-window harness) After: coldOpenMs=1967.70 ms to PHYSICS_STABILIZED on VS Code 1.128.0 (single smoke run; not a baseline)
Add same-profile cold/warm launches, deterministic Git fixture states, production indexing, and armed Core/extension metric emitters. Before (discovery-only smoke, not comparable): small coldOpenMs 1967.70ms; warm and cache metrics unavailable. After (full indexed relationship graph): small coldOpenMs 3371.25ms, warmOpenMs 1575.39ms, cacheSaveMs 456.20ms, cacheBytes 2207744. Single local run; not a baseline.
Before (small indexed fixture, one local run): cold 3371.25 ms, warm 1575.39 ms, with 100 individual parse records emitted. After (small indexed fixture, one local run): cold 3419.17 ms, warm 1541.08 ms, with Tree-sitter records aggregated by dimension. These samples are directional and are not the checked-in baseline.
Before (small indexed fixture, one local pair): cold 3419.17 ms, warm 1541.08 ms, cache save 472.17 ms. After (small indexed fixture, one local pair): cold 3094.79 ms, warm 1601.78 ms, cache save 446.64 ms. These samples are directional and are not the checked-in baseline.
Add strict same-window Explorer comparisons, correlated scope and webview scenarios, deterministic self-workspace support, report assembly, stability budgets, and the PR performance workflow. pnpm perf -- --fixture small --runs 1 --no-budget Before: cold 3419.17ms, warm 1541.08ms, cache save 472.17ms. After: cold 3348.73ms, warm 1560.29ms, cache save 453.73ms. The post-refactor scope probe measured 108 transitions across 18 rows with 108 unique operation IDs and a 154.66ms maximum.
Before: editor-visible create timed out and produced no complete medium report. After (pnpm perf, medium): 10/10 scenarios complete; rename 826.284ms vs Explorer 4.012ms, create 822.224ms vs 11.310ms, delete 820.020ms vs 7.229ms; idle 0 ticks at 60.0fps.
|
Checkpoint pushed: The benchmark now opens CodeGraphy as an editor panel in column 2, keeps a real workspace editor in column 1, subscribes to the visible editor-panel bridge, and asserts the graph stays visible before/after Explorer samples. The create→undo failure was traced to the created file replacing the active graph tab; the perf runtime now focuses the column-1 document before exercising the production mutation path. Refresh waits now have separate activity-start and settlement deadlines. Fresh editor-visible
The ratios are intentionally ugly now that the comparison is honest; they are the Phase 3 optimization baseline. Verification: 129 perf tests, 105 focused extension tests, perf + extension lint/typecheck, acceptance ownership guard, and repo-wide pre-commit typecheck all green. Live progress: https://codegraphy-pr304-progress.poleski.chatgpt.site |
Before: giant --symbols built 540000 nodes and 569996 edges, then timed out waiting for PERF_RENDER_READY after 180000ms without a report. After: the editor-visible giant --symbols cold open completes in 193260.878ms (cacheSaveMs 117325.108); large --symbols completes in 32652.950ms. Full evidence stays available while react-force-graph renders an interactive file overview.
|
Checkpoint pushed: 2a7ac36 ( What changed:
Real editor-visible measurements:
Fresh verification:
Progress site (newest first): https://codegraphy-pr304-progress.poleski.chatgpt.site Next: finalized Phase 1 five-run medium baselines, full sweep, Linux runner baselines, then restore budget-enforcing small+medium PR CI. |
Carry a monotonic scope-projection revision through toggle completion, graph commits, and physics settling so the perf harness cannot accept stale or unrelated readiness events. Preserve layout-change intent across coalesced commits and keep cancelled render callbacks inert. Split the correlation, projection, lifecycle, and target logic into focused modules with direct unit and mutation coverage. Verification: extension tests 7,035/7,035; perf harness tests 129/129; changed logic mutation score 100%; lint, typecheck, and perf build passed. Five medium samples improved node:folder scope-toggle median from 175.22 ms to 125.04 ms and CV from 14.22% to 1.35%. The full command completed all scenario hosts but remains gated by unrelated local Explorer delete CV of 12.93% (8.19-11.45 ms), which will be rerun.
|
Checkpoint pushed: What landed:
Verification:
Editor-visible medium evidence:
The aggregate command still exited nonzero on a separate local Explorer baseline stability check: |
Reduce small-fixture watcher-to-graph save latency from 563.6 ms to 110.1 ms (80.5%) by suppressing the full atomic watcher burst after a document save. Enforce exactly one correlated single-save measurement in performance reports.
Checkpoint — atomic saves now refresh oncePushed
Local visible-Graph-View verification (
Quality evidence:
Next: adopt the clean small baseline, push the PR/dispatch workflow split and runner-class baseline separately, then finish the Phase 1 gate proof. |
Reduce the per-PR matrix from seven configurations to small and medium while preserving all seven for manual dispatch. Replace the unbudgeted three-run lane with the runner-class 20% regression budget and seed small/medium Linux baselines.
Explorer parity performance checkpointThe provisional Phase 8 report is now committed at Accepted evidence includes the 383-byte diff payload (99.923% below baseline), zero layout resets across five medium + five large saves, deterministic one-refresh 100-file bursts, 43.01% faster large cold indexing, and 831-byte adjacent-revision patches. Owner decision / further engineering is still required for:
The renderer policy in the plan reserves PixiJS/WebGL migration for owner discussion. Phase 9 remains blocked until the report/showcase are complete and exceptions or follow-up work are explicitly accepted. The deferred drag-to-folder / external OS-drop follow-up is filed at https://trello.com/c/z907ZEa2/259-graph-file-drag-to-folder-external-os-drop. |
1 participant
Summary
Handoff plan for the Trello epic Epic: VS Code Explorer parity + native-feel performance, written for an autonomous executor (GPT 5.6 looping on a dedicated Mac mini) —
docs/plans/2026-07-08-explorer-parity-performance.md.Nine phases with deterministic gates, plus a cited research appendix (Obsidian graph internals + plugin system, VS Code standards, react-force-graph/d3-force/tree-sitter levers) and code-audited monorepo facts (confirmed gaps: no incremental tree-sitter parsing, per-call parser construction, zero worker_threads, Graph Scope toggles round-trip to the host).
@vscode/test-electronsetup; same-session built-in Explorer ratio lane; newgiantfixture (30k files, past Obsidian's documented ~25k ceiling); idle-CPU and sim-tick metricsQuality tooling uses the repo's first-party
@poleski/quality-toolsloop (crap → scoped mutate → split-if-over-threshold → organize → repeat until clean); full-suite mutation explicitly excluded.Review notes
🤖 Generated with Claude Code