[trees] Focus/Nav + Visible tree projection feature + performance optimizations (#490)

* Visible tree projection feature + performance optimizations

Add createVisibleTreeProjection API with benchmark/profile scripts, public types, static-store integration, test coverage, and tree controller/view integration.

Includes major performance optimizations:
- Rewrite createVisibleTreeProjection: single-pass with Int32Array parent/child tracking, lazy visibleIndexByPath Map
- Add DFS-based full-tree getVisibleSlice (avoids parent-walk for sibling finding)
- Inline file-node materialization in DFS (~70% of rows skip directory checks)
- Inline path cache + segment lookup in hot loop
- Cache DirectoryChildIndex in DFS stack frame (avoid per-child Map.get)
- Collapse benchmark uses preparePresortedInput to skip re-sorting
- Eager name-id map building in presorted builder finish
- Iterative recomputeCountsRecursive (explicit stack, -64% sub-timing)

Experiments: #1–#12, #15, #20, #21
toggle_wall_ms: 877ms → 143ms (-84%)
collapse_wall_ms: 4757ms → 1510ms (-68%)

* fix depth bug

Author: SlexAxton

apps/docs/app/trees-dev/_components/TreesDevSidebar.tsx

@@ -23,7 +23,7 @@ const DEMO_PAGES = [
 ] as const;
 
 const PATH_STORE_LANE_PAGES = [
-  { slug: 'path-store-powered', label: 'Expansion + Collapse' },
+  { slug: 'path-store-powered', label: 'Focus + Navigation' },
 ] as const;
 
 export function TreesDevSidebar({ onNavigate }: { onNavigate?: () => void }) {

apps/docs/app/trees-dev/path-store-powered/PathStorePoweredRenderDemoClient.tsx

@@ -75,7 +75,7 @@ export function PathStorePoweredRenderDemoClient({
   const options = useMemo<PathStoreFileTreeOptions>(
     () => ({
       ...sharedOptions,
-      id: 'pst-phase2',
+      id: 'pst-phase3',
       preparedInput,
     }),
     [preparedInput, sharedOptions]
@@ -87,19 +87,19 @@ export function PathStorePoweredRenderDemoClient({
         <p className="text-muted-foreground text-xs font-semibold tracking-wide uppercase">
           Path-store lane · provisional
         </p>
-        <h1 className="text-2xl font-bold">Expansion + Collapse</h1>
+        <h1 className="text-2xl font-bold">Focus + Navigation</h1>
         <p className="text-muted-foreground max-w-3xl text-sm leading-6">
-          Phase 2 adds the first full pointer-driven interaction slice to the
-          path-store-powered trees lane: directory expansion and collapse on top
-          of the always-virtualized renderer.
+          Phase 3 adds the first full keyboard interaction slice to the
+          path-store-powered trees lane: single-item focus, baseline tree
+          navigation, and virtualization-safe DOM focus recovery.
         </p>
       </header>
 
       <HydratedPathStoreExample
         containerHtml={containerHtml}
-        description="Click any directory row to toggle expansion. File rows stay inert, flattened rows toggle the terminal directory, and the renderer remains always virtualized."
+        description="Click or focus any row, then use Arrow keys plus Home/End. Directory rows keep the Phase 2 toggle behavior, flattened rows target the terminal directory, and keyboard navigation survives virtualization."
         options={options}
-        title="Expansion + Collapse"
+        title="Focus + Navigation"
       />
 
       <section className="space-y-3 rounded-lg border p-4">

apps/docs/app/trees-dev/path-store-powered/page.tsx

@@ -23,7 +23,7 @@ export default function PathStorePoweredPage() {
 
   const payload = preloadPathStoreFileTree({
     ...sharedOptions,
-    id: 'pst-phase2',
+    id: 'pst-phase3',
     preparedInput: linuxKernelPreparedInput,
   });
 

packages/path-store/package.json

@@ -18,9 +18,11 @@
   },
   "scripts": {
     "benchmark": "bun run ./scripts/benchmark.ts",
+    "benchmark:visible-tree-projection": "bun run ./scripts/benchmarkVisibleTreeProjection.ts",
     "build": "bun run vite build demo",
     "dev": "bun run vite demo --host 127.0.0.1 --port 4175",
     "profile:demo": "bun run ./scripts/profileDemo.ts",
+    "profile:visible-tree-projection": "bun run ./scripts/profileVisibleTreeProjection.ts",
     "test": "bun test",
     "test:demo": "(bun ./test/e2e/check-playwright-binary.js || bun run test:demo:installbinary) && bunx playwright test -c test/e2e/playwright.config.js",
     "test:demo:installbinary": "bunx playwright@1.51.1 install chromium",

packages/path-store/scripts/benchmarkVisibleTreeProjection.ts

@@ -0,0 +1,139 @@
+import { performance } from 'node:perf_hooks';
+
+import {
+  createVisibleTreeProjectionScenarios,
+  createVisibleTreeProjectionWorkload,
+  summarizeDurations,
+} from './visibleTreeProjectionShared';
+
+interface BenchmarkConfig {
+  json: boolean;
+  runs: number;
+  warmupRuns: number;
+  workloads: string[];
+}
+
+interface ScenarioBenchmarkResult {
+  description: string;
+  metrics: ReturnType<typeof summarizeDurations>;
+  name: string;
+  rowCount: number;
+  workload: {
+    collapseTargetPath: string | null;
+    expandedFolderCount: number;
+    fileCount: number;
+    name: string;
+    visibleCount: number;
+  };
+}
+
+function parseArgs(argv: readonly string[]): BenchmarkConfig {
+  const config: BenchmarkConfig = {
+    json: false,
+    runs: 20,
+    warmupRuns: 5,
+    workloads: ['linux-1x'],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '--json':
+        config.json = true;
+        break;
+      case '--runs':
+        config.runs = Number(argv[index + 1] ?? config.runs);
+        index += 1;
+        break;
+      case '--warmup-runs':
+        config.warmupRuns = Number(argv[index + 1] ?? config.warmupRuns);
+        index += 1;
+        break;
+      case '--workloads':
+        config.workloads = (argv[index + 1] ?? '')
+          .split(',')
+          .map((workload) => workload.trim())
+          .filter((workload) => workload.length > 0);
+        index += 1;
+        break;
+      default:
+        break;
+    }
+  }
+
+  return config;
+}
+
+function main(): void {
+  const config = parseArgs(process.argv.slice(2));
+  const results: ScenarioBenchmarkResult[] = [];
+
+  for (const workloadName of config.workloads) {
+    const workload = createVisibleTreeProjectionWorkload(workloadName);
+    const scenarios = createVisibleTreeProjectionScenarios(workload);
+
+    for (const scenario of scenarios) {
+      for (
+        let warmupIndex = 0;
+        warmupIndex < config.warmupRuns;
+        warmupIndex += 1
+      ) {
+        scenario.measure();
+      }
+
+      const durationsMs: number[] = [];
+      let rowCount = 0;
+      for (let runIndex = 0; runIndex < config.runs; runIndex += 1) {
+        const startedAt = performance.now();
+        const result = scenario.measure();
+        durationsMs.push(performance.now() - startedAt);
+        rowCount = result.rowCount;
+      }
+
+      results.push({
+        description: scenario.description,
+        metrics: summarizeDurations(durationsMs),
+        name: scenario.name,
+        rowCount,
+        workload: {
+          collapseTargetPath: workload.collapseTargetPath,
+          expandedFolderCount: workload.expandedFolderCount,
+          fileCount: workload.fileCount,
+          name: workload.name,
+          visibleCount: workload.visibleCount,
+        },
+      });
+    }
+  }
+
+  if (config.json) {
+    console.log(
+      JSON.stringify(
+        {
+          benchmark: 'visible-tree-projection',
+          config,
+          results,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  for (const result of results) {
+    console.log(
+      [
+        `${result.workload.name}:${result.name}`,
+        `rows=${String(result.rowCount)}`,
+        `avg=${result.metrics.averageMs.toFixed(3)}ms`,
+        `median=${result.metrics.medianMs.toFixed(3)}ms`,
+        `p95=${result.metrics.p95Ms.toFixed(3)}ms`,
+        `min=${result.metrics.minMs.toFixed(3)}ms`,
+        `max=${result.metrics.maxMs.toFixed(3)}ms`,
+      ].join('  ')
+    );
+  }
+}
+
+main();